chi.server

The chi.server module is used for interacting with server instances.

class chi.server.Flavor(name: str, disk: int, ram: int, vcpus: int)[source]

Represents a flavor in the system.

name

The name of the flavor.

Type:

str

disk

The disk size in GB.

Type:

int

ram

The RAM size in MB.

Type:

int

vcpus

The number of virtual CPUs.

Type:

int

class chi.server.Keypair(name: str, public_key: str)[source]

Represents a keypair object.

name

The name of the keypair.

Type:

str

public_key

The public key associated with the keypair.

Type:

str

class chi.server.Server(name: str, reservation_id: str | None = None, image_name: str = 'CC-Ubuntu22.04', image: Image | None = None, flavor_name: str = 'baremetal', key_name: str | None = None, keypair: Keypair | None = None, network_name: str = 'sharednet1')[source]

Represents an instance.

Parameters:

  • name (str) – The name of the server.

  • reservation_id (Optional[str]) – The reservation ID associated with the server. Defaults to None.

  • image_name (str) – The name of the image to use for the server. Defaults to DEFAULT_IMAGE_NAME.

  • image (Optional[str]) – The image ID or name to use for the server. Defaults to None.

  • flavor_name (str) – The name of the flavor to use for the server. Defaults to BAREMETAL_FLAVOR.

  • key_name (str) – The name of the keypair to use for the server. Defaults to None.

  • keypair (Optional[Keypair]) – The keypair object to use for the server. Defaults to None.

  • network_name (str) – The name of the network to use for the server. Defaults to DEFAULT_NETWORK.

name

The name of the server.

Type:

str

reservation_id

The reservation ID associated with the server.

Type:

Optional[str]

image_name

The name of the image used for the server.

Type:

str

flavor_name

The name of the flavor used for the server.

Type:

str

keypair

The keypair object used for the server.

Type:

Optional[Keypair]

network_name

The name of the network used for the server.

Type:

str

id

The ID of the server.

Type:

Optional[str]

addresses

The IP addresses associated with the server.

Type:

Dict[str, List[str]]

created_at

The timestamp when the server was created.

Type:

Optional[datetime]

host_id

The ID of the host where the server is running.

Type:

Optional[str]

host_status

The status of the host where the server is running.

Type:

Optional[str]

hypervisor_hostname

The hostname of the hypervisor where the server is running.

Type:

Optional[str]

is_locked

Indicates whether the server is locked.

Type:

bool

status

The status of the server.

Type:

Optional[str]

associate_floating_ip(fip: str | None = None) → None[source]

Associates a floating IP with the server. (BROKEN)

Parameters:

fip (str, optional) – The floating IP to associate with the server. If not provided, a new floating IP will be allocated.

Returns:

None

check_connectivity(wait: bool = True, host: str | None = None, port: int = 22, timeout: int = 500, show: str = 'widget') → bool[source]

Checks for server TCP connectivity from the local runtime.

Parameters:

  • wait (bool, optional) – Should this method block. Defaults to True.

  • host (str, optional) – The IP to connect to. Defaults to the value of get_floating_ip(), which returns the first floating IP of this server.

  • port (int, optional) – The TCP port to connect to. Defaults to 22.

  • timeout (int, optional) – The number of seconds to wait before timeout. Defaults to 500.

  • show (str, optional) – The type of server information to display after creation. Defaults to “widget”.

Raises:

ResourceError – If timeout occurs.

Returns:

whether connectivity could be established

Return type:

bool

detach_floating_ip(fip: str) → None[source]

Detaches a floating IP from the server. (BROKEN)

Parameters:

fip (str) – The floating IP to detach.

Returns:

None

execute(command: str, **kwargs)[source]

Execute a command on this server

Parameters:

command (str) – the shell command to execute.

get_floating_ip()[source]

Get an attached floating ip of this server, if exists

Returns:

Floating IP address of server

Return type:

str

refresh()[source]

Refreshes the server’s information by retrieving the latest details from the server provider.

Raises:

ResourceError – If the server refresh fails.

show(type: str = 'text', wait_for_active: bool = False) → None[source]

Display the content of the server.

Parameters:

  • type (str, optional) – The type of content to display. options are [“text”,”widget”]. Defaults to “text”.

  • wait_for_active (bool, optional) – Whether to wait for the server to be active before displaying the content. Defaults to False.

Raises:

CHIValueError – If an invalid show type is provided.

Returns:

None

ssh_connection(user='cc', **kwargs) → Connection[source]
Args:

kwargs: Arguments for the Fabric Connection

Returns:

`Fabric Connection

<https://docs.fabfile.org/en/latest/api/connection.html#fabric.connection.Connection>`__ to this server.

submit(wait_for_active: bool = True, show: str = 'widget', idempotent: bool = False) → Server[source]

Submits a server creation request to the Nova API.

Parameters:

  • wait_for_active (bool, optional) – Whether to wait for the server to become active before returning. Defaults to True.

  • show (str, optional) – The type of server information to display after creation. Defaults to “widget”.

  • idempotent (bool, optional) – Whether to create the server only if it doesn’t already exist. Defaults to False.

Raises:

Conflict – If the server creation fails due to a conflict and idempotent mode is not enabled.

upload(file: str, remote_path: str = '', **kwargs) → None[source]

Upload a local file to this server

Parameters:

  • file (str) – the path of the local file

  • remote_path (str, optional) – the remote path. Defaults to “”.

wait(status: str = 'ACTIVE', show: str = 'widget') → None[source]

Waits for the server’s status to reach the specified status.

Parameters:

  • status (str) – The status to wait for. Defaults to “ACTIVE”.

  • show (str, optional) – The type of server information to display after creation. Defaults to “widget”.

Raises:

ServiceError – If the server does not reach the specified status within the timeout period.

Returns:

None

chi.server.associate_floating_ip(server_id, floating_ip_address=None)[source]

Deprecated since version 1.0.

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-Ubuntu22.04', flavor_id=None, flavor_name=None, count=1, hypervisor_hostname=None) → Server | list[Server][source]

Deprecated since version 1.0.

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]

Deprecated since version 1.0.

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]

Deprecated since version 1.0.

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_keypair(name=None) → Keypair[source]

Retrieves a keypair by name.

Parameters:

name (str, optional) – The name of the keypair to retrieve. If not provided, it will use the JupyterHub keypair for the current user.

Returns:

An instance of the Keypair class representing the retrieved keypair.

Return type:

Keypair

chi.server.get_server(name: str) → Server[source]

Retrieves a server object by its name.

Parameters:

name (str) – The name of the server to retrieve.

Returns:

The server object corresponding to the given name.

Return type:

Server

Raises:

Exception – If the server with the given name does not exist.

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[Flavor][source]

Get a list of all available flavors.

Returns:

A list of all flavors.

chi.server.list_keypair() → List[Keypair][source]

Retrieve a list of keypairs from the Nova client.

Returns:

A list of Keypair objects, containing the name and public key of each keypair.

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

Returns a list of all servers in the current project.

Returns:

A list of Server objects representing the servers.

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

Deprecated since version 1.0.

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]

Deprecated since version 1.0.

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]

Deprecated since version 1.0.

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]

Deprecated since version 1.0.

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]

Deprecated since version 1.0.

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.