Packet.net Guide
Introduction
Packet.net is a bare metal infrastructure host that is supported by the community.general collection through six cloud modules. The six modules are:
community.general.packet_device: manages servers on Packet. You can use this module to create, restart and delete devices.
community.general.packet_ip_subnet: assign IP subnet to a bare metal server
community.general.packet_project: create/delete a project in Packet host
community.general.packet_sshkey: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys.
community.general.packet_volume: create/delete a volume in Packet host
community.general.packet_volume_attachment: attach/detach a volume to a device in the Packet host
Note, this guide assumes you are familiar with Ansible and how it works. If you are not, have a look at their docs before getting started.
Requirements
The Packet modules connect to the Packet API using the packet-python package. You can install it with pip:
$ pip install packet-python
In order to check the state of devices created by Ansible on Packet, it is a good idea to install one of the Packet CLI clients. Otherwise you can check them through the Packet portal.
To use the modules you will need a Packet API token. You can generate an API token through the Packet portal here. The simplest way to authenticate yourself is to set the Packet API token in an environment variable:
$ export PACKET_API_TOKEN=Bfse9F24SFtfs423Gsd3ifGsd43sSdfs
If you are not comfortable exporting your API token, you can pass it as a parameter to the modules.
On Packet, devices and reserved IP addresses belong to projects. In order to use the packet_device module, you need to specify the UUID of the project in which you want to create or manage devices. You can find a project’s UUID in the Packet portal here (it is just under the project table) or through one of the available CLIs.
If you want to use a new SSH key pair in this tutorial, you can generate it to ./id_rsa
and ./id_rsa.pub
as:
$ ssh-keygen -t rsa -f ./id_rsa
If you want to use an existing key pair, just copy the private and public key over to the playbook directory.
Device Creation
The following code block is a simple playbook that creates one Type 0 server (the plan
parameter). You have to supply plan
and operating_system
. location
defaults to ewr1
(Parsippany, NJ). You can find all the possible values for the parameters through a CLI client.
# playbook_create.yml
- name: Create Ubuntu device
hosts: localhost
tasks:
- community.general.packet_sshkey:
key_file: ./id_rsa.pub
label: tutorial key
- community.general.packet_device:
project_id: <your_project_id>
hostnames: myserver
operating_system: ubuntu_16_04
plan: baremetal_0
facility: sjc1
After running ansible-playbook playbook_create.yml
, you should have a server provisioned on Packet. You can verify through a CLI or in the Packet portal.
If you get an error with the message “failed to set machine state present, error: Error 404: Not Found”, please verify your project UUID.
Updating Devices
The two parameters used to uniquely identify Packet devices are: “device_ids” and “hostnames”. Both parameters accept either a single string (later converted to a one-element list), or a list of strings.
The device_ids
and hostnames
parameters are mutually exclusive. The following values are all acceptable:
device_ids:
a27b7a83-fc93-435b-a128-47a5b04f2dcf
hostnames:
mydev1
device_ids:
[a27b7a83-fc93-435b-a128-47a5b04f2dcf, 4887130f-0ccd-49a0-99b0-323c1ceb527b]
hostnames:
[mydev1, mydev2]
In addition, hostnames can contain a special %d
formatter along with a count
parameter that lets you easily expand hostnames that follow a simple name and number pattern; in other words, hostnames: "mydev%d", count: 2
will expand to [mydev1, mydev2].
If your playbook acts on existing Packet devices, you can only pass the hostname
and device_ids
parameters. The following playbook shows how you can reboot a specific Packet device by setting the hostname
parameter:
# playbook_reboot.yml
- name: reboot myserver
hosts: localhost
tasks:
- community.general.packet_device:
project_id: <your_project_id>
hostnames: myserver
state: rebooted
You can also identify specific Packet devices with the device_ids
parameter. The device’s UUID can be found in the Packet Portal or by using a CLI. The following playbook removes a Packet device using the device_ids
field:
# playbook_remove.yml
- name: remove a device
hosts: localhost
tasks:
- community.general.packet_device:
project_id: <your_project_id>
device_ids: <myserver_device_id>
state: absent
More Complex Playbooks
In this example, we will create a CoreOS cluster with user data.
The CoreOS cluster will use etcd for discovery of other servers in the cluster. Before provisioning your servers, you will need to generate a discovery token for your cluster:
$ curl -w "\n" 'https://discovery.etcd.io/new?size=3'
The following playbook will create an SSH key, 3 Packet servers, and then wait until SSH is ready (or until 5 minutes passed). Make sure to substitute the discovery token URL in user_data
, and the project_id
before running ansible-playbook
. Also, feel free to change plan
and facility
.
# playbook_coreos.yml
- name: Start 3 CoreOS nodes in Packet and wait until SSH is ready
hosts: localhost
tasks:
- community.general.packet_sshkey:
key_file: ./id_rsa.pub
label: new
- community.general.packet_device:
hostnames: [coreos-one, coreos-two, coreos-three]
operating_system: coreos_beta
plan: baremetal_0
facility: ewr1
project_id: <your_project_id>
wait_for_public_IPv: 4
user_data: |
#cloud-config
coreos:
etcd2:
discovery: https://discovery.etcd.io/<token>
advertise-client-urls: http://$private_ipv4:2379,http://$private_ipv4:4001
initial-advertise-peer-urls: http://$private_ipv4:2380
listen-client-urls: http://0.0.0.0:2379,http://0.0.0.0:4001
listen-peer-urls: http://$private_ipv4:2380
fleet:
public-ip: $private_ipv4
units:
- name: etcd2.service
command: start
- name: fleet.service
command: start
register: newhosts
- name: wait for ssh
ansible.builtin.wait_for:
delay: 1
host: "{{ item.public_ipv4 }}"
port: 22
state: started
timeout: 500
loop: "{{ newhosts.results[0].devices }}"
As with most Ansible modules, the default states of the Packet modules are idempotent, meaning the resources in your project will remain the same after re-runs of a playbook. Thus, we can keep the packet_sshkey
module call in our playbook. If the public key is already in your Packet account, the call will have no effect.
The second module call provisions 3 Packet Type 0 (specified using the plan
parameter) servers in the project identified by the project_id
parameter. The servers are all provisioned with CoreOS beta (the operating_system
parameter) and are customized with cloud-config user data passed to the user_data
parameter.
The packet_device
module has a wait_for_public_IPv
that is used to specify the version of the IP address to wait for (valid values are 4
or 6
for IPv4 or IPv6). If specified, Ansible will wait until the GET API call for a device contains an Internet-routeable IP address of the specified version. When referring to an IP address of a created device in subsequent module calls, it is wise to use the wait_for_public_IPv
parameter, or state: active
in the packet_device module call.
Run the playbook:
$ ansible-playbook playbook_coreos.yml
Once the playbook quits, your new devices should be reachable through SSH. Try to connect to one and check if etcd has started properly:
tomk@work $ ssh -i id_rsa core@$one_of_the_servers_ip
core@coreos-one ~ $ etcdctl cluster-health
If you have any questions or comments let us know! help@packet.net