chi.server

The chi.server module exposes both a functional interface and an object-oriented interface for interacting with server instances.

Functional interface

Any of the following functions can be directly imported and used individually:

from chi.server import get_server

s = server.get_server('my-server-name')
chi.server.associate_floating_ip(server_id, floating_ip_address=None)[source]

Associate an allocated Floating IP with a server.

If no Floating IP is specified, one will be allocated dynamically.

Parameters:
  • server_id (str) – The ID of the server.

  • floating_ip_address (str) – The IPv4 address of the Floating IP to assign. If specified, this Floating IP must already be allocated to the project.

chi.server.create_server(server_name, reservation_id=None, key_name=None, network_id=None, network_name='sharednet1', nics=[], image_id=None, image_name='CC-Ubuntu20.04', flavor_id=None, flavor_name=None, count=1, hypervisor_hostname=None) NovaServer | list[NovaServer][source]

Launch a new server instance.

Parameters:
  • server_name (str) – A name to give the server.

  • reservation_id (str) – The ID of the Blazar reservation that will be used to select a target host node. It is required to make a reservation for bare metal server instances.

  • key_name (str) – A key pair name to associate with the server. Any user holding the private key for the key pair will be able to SSH to the instance as the cc user. Defaults to the key specified by the “key_name” context variable.

  • network_id (str) – The network ID to connect the server to. The server will obtain an IP address on this network when it boots.

  • network_name (str) – The name of the network to connect the server to. If network_id is also set, that takes priority.

  • nics (list[dict]) –

  • image_id (str) – The image ID to use for the server’s disk image.

  • image_name (str) – The name of the image to user for the server’s disk image. If image_id is also set, that takes priority. (Default DEFAULT_IMAGE.)

  • flavor_id (str) – The flavor ID to use when launching the server. If not set, and no flavor_name is set, the first flavor found is used.

  • flavor_name (str) – The name of the flavor to use when launching the server. If flavor_id is also set, that takes priority. If not set, and no flavor_id is set, the first flavor found is used.

  • count (int) – The number of instances to launch. When launching bare metal server instances, this number must be less than or equal to the total number of hosts reserved. (Default 1).

Returns:

The created server instance. If count was larger than 1, then a

list of all created instances will be returned instead.

Raises:

ValueError – if an invalid count is provided.

chi.server.delete_server(server_id)[source]

Delete a server by its ID.

Parameters:

server_id (str) – The ID of the server to delete.

chi.server.detach_floating_ip(server_id, floating_ip_address)[source]

Remove an allocated Floating IP from a server by name.

Parameters:
  • server_id (str) – The name of the server.

  • floating_ip_address (str) – The IPv4 address of the Floating IP to remove from the server.

chi.server.get_flavor(ref) FlavorAccess[source]

Get a flavor by its ID or name.

Parameters:

ref (str) – The ID or name of the flavor.

Returns:

The flavor matching the ID or name.

Raises:

NotFound – If the flavor could not be found.

chi.server.get_flavor_id(name) str[source]

Look up a flavor’s ID from its name.

Parameters:

name (str) – The name of the flavor.

Returns:

The ID of the found flavor.

Raises:

NotFound – If the flavor could not be found.

chi.server.get_server(ref) Server[source]

Get a server by its ID.

Parameters:

ref (str) – The ID or name of the server.

Returns:

The server matching the ID.

Raises:

NotFound – If the server could not be found.

chi.server.get_server_id(name) str[source]

Look up a server’s ID from its name.

Parameters:

name (str) – The name of the server.

Returns:

The ID of the found server.

Raises:

NotFound – If the server could not be found.

chi.server.list_flavors() list[FlavorAccess][source]

Get a list of all available flavors.

Returns:

A list of all flavors.

chi.server.list_servers(**kwargs) list[Server][source]

List all servers under the current project.

Parameters:

kwargs – Keyword arguments, which will be passed to novaclient.v2.servers.list(). For example, to filter by instance name, provide search_opts={'name': 'my-instance'}

Returns:

All servers associated with the current project.

chi.server.show_flavor(flavor_id) FlavorAccess[source]

Get a flavor by its ID.

Parameters:

flavor_id (str) – the ID of the flavor

Returns:

The flavor with the given ID.

chi.server.show_flavor_by_name(name) FlavorAccess[source]

Get a flavor by its name.

Parameters:

name (str) – The name of the flavor.

Returns:

The flavor with the given name.

Raises:

NotFound – If the flavor could not be found.

chi.server.show_server(server_id) Server[source]

Get a server by its ID.

Parameters:

server_id (str) – the ID of the server

Returns:

The server with the given ID.

chi.server.show_server_by_name(name) Server[source]

Get a server by its name.

Parameters:

name (str) – The name of the server.

Returns:

The server with the given name.

Raises:

NotFound – If the server could not be found.

chi.server.update_keypair(key_name=None, public_key=None) Keypair[source]

Update a key pair’s public key.

Due to how OpenStack Nova works, this requires deleting and re-creating the key even for public key updates. The key will not be re-created if it already exists and the fingerprints match.

Parameters:
  • key_name (str) – The name of the key pair to update. Defaults to value of the “key_name” context variable.

  • public_key (str) – The public key to update the key pair to reference. Defaults to the contents of the file specified by the “keypair_public_key” context variable.

Returns:

The updated (or created) key pair.

chi.server.wait_for_active(server_id, timeout=1200)[source]

Wait for the server to go in to the ACTIVE state.

If the server goes in to an ERROR state, this function will terminate. This is a blocking function.

Note

For bare metal servers, when the server transitions to ACTIVE state, this actually indicates it has started its final boot. It may still take some time for the boot to complete and interfaces e.g., SSH to come up.

If you want to wait for a TCP service like SSH, refer to wait_for_tcp().

Parameters:
  • server_id (str) – The ID of the server.

  • timeout (int) – The number of seconds to wait for before giving up. Defaults to 20 minutes.

chi.server.wait_for_tcp(host, port, timeout=1200, sleep_time=5)[source]

Wait until a port on a server starts accepting TCP connections.

The implementation is taken from wait_for_tcp_port.py.

Parameters:
  • host (str) – The host that should be accepting connections. This can be either a Floating IP or a hostname.

  • port (int) – Port number.

  • timeout (int) – How long to wait before raising errors, in seconds. Defaults to 20 minutes.

  • sleep_time (int) – How long to wait between each attempt in seconds. Defaults to 5 seconds.

Raises:

TimeoutError – If the port isn’t accepting connection after time specified in timeout.

Object-oriented interface

The Server abstraction has been available historically for those who wish to use something with more of an OOP flavor.

class chi.server.Server(id=None, lease=None, key=None, image='CC-Ubuntu20.04', **kwargs)[source]

A wrapper object referring to a server instance.

This class is helpful if you want to use a more object-oriented programming approach when building your infrastrucutre. With the Server abstraction, you can for example do the following:

with Server(lease=my_lease, image=my_image) as server:
    # When entering this block, the server is guaranteed to be
    # in the "ACTIVE" state if it launched successfully.
    server.associate_floating_ip()
    # Interact with the server (via, e.g., SSH), then...
# When the block exits, the server will be terminated and deleted

The above example uses a context manager. The class can also be used without a context manager:

# Triggers the launch of the server instance
server = Server(lease=my_lease, image=my_image)
# Wait for server to be active
server.wait()
server.associate_floating_ip()
# Interact with the server, then...
server.delete()
id

The ID of an existing server instance. Use this if you have already launched the instance and just want a convenient wrapper object for it.

Type:

str

lease

The Lease the instance will be launched under.

Type:

Lease

key

The name of the key pair to associate with the image. This is only applicable if launching the image; key pairs cannot be added to a server that has already been launched and wrapped via the id attribute.

Type:

str

image

The name or ID of the disk iage to use.

Type:

str

name

A name to give the new instance. (Defaults to an auto-generated name.)

Type:

str

net_ids

A list of network IDs to associate the instance with. The instance will obtain an IP address on each network during boot.

Note

For bare metal instances, the number of network IDs cannot exceed the number of enabled NICs on the bare metal node.

Type:

list[str]

kwargs

Additional keyword arguments to pass to Nova’s server create() function.

associate_floating_ip()[source]

Attach a floating IP to this server instance.

delete()[source]

Delete this server instance.

disassociate_floating_ip()[source]

Detach the floating IP attached to this server instance, if any.

property error: bool

Check if the instance is in an error state.

property ready: bool

Check if the instance is marked as active.

rebuild(image_ref)[source]

Rebuild this server instance.

Note

For bare metal instances, this effectively redeploys to the host and overwrites the local disk.

refresh()[source]

Poll the latest state of the server instance.

property status: str

Get the instance status.

wait()[source]

Wait for the server instance to finish launching.

If the server goes into an error state, this function will return early.