Equinix Metal

A Python client for the Equinix Metal API.

This repository is Maintained meaning that this software is supported by Equinix Metal and its community - available to use in production environments.

Table of Contents

• Installation
• Documentation
• Authentication
• Examples
  • List Projects
  • List Plans
  • Creating a Device
  • Checking the Status and Rebooting a Device
  • Listing all Devices Limiting to 50 per Page
  • Updating a Device
  • Deleting a Device
  • Creating a Device Batch
  • Creating a Volume
  • Attaching and Detaching a Volume
  • Creating and Restoring a Volume Snapshot
  • Listing Project IP Addresses
  • Creating a Project for an Organization
  • Creating a VLAN
• Contributing
• Copyright
• Changes

Installation

The Equinix Metal python api library can be installed using pip:

pip install packet-python

Package information available here:

https://pypi.python.org/pypi/packet-python

Documentation

Full Equinix Metal API documenation is available here: https://metal.equinix.com/developers/api/

Authentication

Provide your credentials when instantiating client:

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

Examples

List Projects

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

projects = manager.list_projects()
for project in projects:
    print(project)

List Plans

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

plans = manager.list_plans()
for plan in plans:
    print(plan)
    if 'cpus' in plan.specs:
        print(plan.specs['cpus'][0]['count'])

Creating a Device

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

device = manager.create_device(project_id='project-id',
                               hostname='node-name-of-your-choice',
                               plan='baremetal_1', metro='sv',
                               operating_system='ubuntu_18_04')
print(device)

Checking the Status and Rebooting a Device

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

device = manager.get_device('device-id')
print(device.state)
device.reboot()

Listing all Devices Limiting to 50 per Page

Equinix Metal API defaults to a limit of 10 per page

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")
params = {
    'per_page': 50
}
devices = manager.list_devices(project_id='project_id', params = params)
print(devices)

Updating a Device

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

device = manager.get_device('device-id')
device.hostname = "test02"
device.description = "new description"

device.update()

Deleting a Device

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

device = manager.get_device('device-id')
device.delete()

Creating a Device Batch

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

batch01 = packet.DeviceBatch({
            "hostname": "batch01",
            "quantity": 2,
            "facility": "ams1",
            "operating_system": "centos_7",
            "plan": "baremetal_0",
        })

device_batch = manager.create_batch(project_id="project_id", params=[batch01])
print(device_batch)

Creating a Volume

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

volume = manager.create_volume(project_id="project-id",
                                description="volume description",
                                plan="storage_1",
                                size="100",
                                facility="ewr1",
                                snapshot_count=7,
                                snapshot_frequency="1day")
print(volume)

Attaching and Detaching a Volume

import packet
import time

manager = packet.Manager(auth_token="yourapiauthtoken")
volume = manager.get_volume("volume_id")

volume.attach("device_id")

while True:
    if manager.get_device("device_id").state == "active":
        break
    time.sleep(2)

volume.detach()

Creating and Restoring a Volume Snapshot

import packet
import time

manager = packet.Manager(auth_token="yourapiauthtoken")

volume = manager.get_volume("volume_id")
volume.create_snapshot()

while True:
    if manager.get_volume(volume.id).state == "active":
        break
    time.sleep(2)

snapshots = manager.get_snapshots(volume.id)
volume.restore(snapshots[0].timestamp)

Listing Project IP Addresses

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

ips = manager.list_project_ips("project_id")
for ip in ips:
    print(ip.address)

Creating a Project for an Organization

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

project = manager.create_organization_project(
    org_id="organization_id",
    name="Integration Tests",
    customdata={"tag": "QA"}
)
print(project)

Creating a VLAN

import packet
manager = packet.Manager(auth_token="yourapiauthtoken")

vlan = manager.create_vlan(project_id="project_id", facility="ewr1")
print(vlan)

Contributing

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project.
• Start a feature/bugfix branch.
• Commit and push until you are happy with your contribution.
• You can test your changes with the tox, which is what GitHub Actions use to check builds.

Credits

CargoCulted with much gratitude from: https://github.com/koalalorenzo/python-digitalocean

Changes

See the Changelog for further details.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog. This project adheres to Semantic Versioning.

[1.45.0] - Unreleased

Added

Changed

Fixed

[1.44.3] - 2022-07-27

Fixed

• Fix handling non-dict error data in ResponseError #128 #129

[1.44.2] - 2021-11-18

Fixed

• Fix logic behind validate_metro_capacity #125

[1.44.1] - 2021-09-20

Fixed

• Fix metros URL used in Metro API lists #122
• Catch TypeError when HardwareReservations do not have a device assignment #120

[1.44.0] - 2021-05-19

Added

• User-Agent header added to client requests #113
• Metro class added (https://feedback.equinixmetal.com/changelog/new-metros-feature-live) #110
• Adds metro property to DeviceBatch, Device, IPAddress, VLan #110
• Adds metro to create_device, reserve_ip_address, create_vlan, create_connection #110
• Adds list_metros, validate_metro_capacity to Manager #110
• Adds CODE_OF_CONDUCT.md, SUPPORT.md, OWNERS.md #102, #101, #100
• Adds package metadata for author, author_email, copyright #114

Changed

• facility is now optional in create_device, reserve_ip_address, create_vlan, create_connection #110
• CI is using GH Actions instead of Drone #115

Fixed

• Handles when IPAddress Facility is null in API responses #117

[1.43.1] - 2020-09-04

Fixed

• ResponseError fixed for Python2.7 compatibility

[1.43.0] - 2020-07-14

Added

• Support for reinstalling the operating system to a device, including changing the operating system.
• Manager.create_vlan now includes a description argument

Changed

• ResponseError will now be raised when an API call results in an error

Fixed

• Manager.validate_capacity now considers availability
• Manager.create_project_ssh_key will retry when it encounters 404 responses following a successful creation.
• API responses with {"error":""} keys were not handled well, and will now be handled just like {"errors":[""]} keys.

[1.42.0] - 2020-02-14

Added

• Capturing of available_in to Plan
• Capturing of hardware_reservation, spot_price_max, termination_time, and provisioning_percentage to Device
• Support for creating project ssh keys
• Support for passing custom_data when creating a device

Fixed

• Black not building for CI and thus failing

[1.41.0] - 2019-10-16

Added

• Support for retrieval of hardware reservations
• CPR support at device creation

[1.40.0] - 2019-10-14

Added

• Integration tests are only run if PACKET_PYTHON_TEST_ACTUAL_API envvar is set
• Rescue action and along with test
• Missing SPDX and source encoding meta comments

Removed

• Use of Travis CI

[1.39.1] - 2019-09-17

Added

• Support for hardware_reservation_id

[1.39.0] - 2019-08-26

Added

• Support for Organizations, Events, Emails, VLAN, Snapshot Policies, Batches, Ports, VPN and IPs.
• Live tests

[1.38.2] - 2019-05-30

Added

• Test fixtures to sdist

[1.38.1] - 2019-05-30

Fixed

• Changelog

[1.38.0] - 2019-05-30

Added

• Support for python3.7
• legacy param to get_capacity function

Removed

• Support for python3.3

Changed

• setup.py no longer converts markdown to reST because pypi now supports markdown, woop.

[1.37.1] - 2018-01-08

Fixed

• Version number in setup.py

[1.37.0] - 2018-01-08

Added

• Spot Market Support
• Ability to specify ssh keys on device creation

[1.36.0] - 2017-10-16

Added

• Better tests using PacketMockManager
• Test on 2.7 and 3.[3-6]
• Changelog

Changed

• Use tox for testing

[1.35] - 2017-08-04

Fixed

• Some tests were broken

[1.35]

Added

• public_ipv4_subnet_size

[1.34] - 2017-08-04

Added

• Custom iPXE and always_pxe setting
• Volume coloning
• Device Tags

Fixed

• Handling of error messages from api response

[1.33] - 2017-03-15

Fixed

• Default payment method