chi.server¶

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

class chi.server.Flavor(id: str, name: str, description: str, disk: int, ram: int, vcpus: int, extras: dict)[source]¶

Represents a flavor in the system.

name¶

The name of the flavor.

Type:: str

description¶

The description 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

extras¶

Extra traits associated with this flavor.

Type:: dict

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 | None = '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 (Optional[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:: Optional[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]

add_security_group(security_group_name: str)[source]¶: Add a security group to the server.

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

Associates a floating IP with the server.

Parameters:

fip (str, optional) – The floating IP to associate with the server. If not provided, a new floating IP will be allocated.
port_id (str) – Optional port ID to assign the floating IP to. If not provided, the will use the first routable port on the server.

Returns:

None

attach_volume(volume_id: str) → None[source]¶

Attach a Cinder volume to the server. Only supported at KVM@TACC.

Parameters:: volume_id (str) – The volume to attach.

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

delete(idempotent: bool = False, delete_ips: bool = True) → None[source]¶

Deletes the server.

Parameters:

idempotent (bool, optional) – Whether to create the server only if it doesn’t already exist. Defaults to False.
delete_ips (bool, optional) – Whether to delete the server IPs from this project. Defauls to False

detach_floating_ip(fip: str, delete: bool | None = True) → None[source]¶

Detaches a floating IP from the server.

Parameters:

fip (str) – The floating IP to detach.
delete (Optional[bool], optional) – Whether to delete the floating IP after disassociation. Defaults to True.

Returns:

None

detach_volume(volume_id: str) → None[source]¶

Detach a Cinder volume from the server. Only supported at KVM@TACC.

Parameters:: volume_id (str) – The volume to detach.

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

Execute a command on this server

Parameters:: command (str) – the shell command to execute.

get_all_floating_ips()[source]¶

Get a list of attached floating ips of this server

Returns:: Floating IP addresses of server
Return type:: List[str[]

get_floating_ip()[source]¶

Get an attached floating ip of this server, if exists

Returns:: Floating IP address of server
Return type:: str

get_metadata() → Dict[str, str][source]¶

Get the metadata dictionary of this server

Returns:: The metadata dictionary of the server.
Return type:: Dict[str, str]

refresh()[source]¶

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

Raises:: ResourceError – If the server refresh fails.

remove_security_group(security_group_name: str)[source]¶: Removes a security group to the server.

set_metadata_item(key, value)[source]¶

Set a metadata item for the server.

Parameters:

key (str) – The metadata key
value (str) – The metadata value

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, retry_on_error: bool = False, wait_timeout: int = 1200, **kwargs) → 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.
retry_on_error (bool, optional) – Whether to retry the server creation if creation fails. Defaults to False.
wait_timeout (int) – How long to wait for server to start in seconds. Default 20 minutes.

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', timeout: int = 1200) → 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”.
timeout (int) – How long to wait for server to start in seconds. Default 20 minutes.

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, port_id=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.
port_id (str) – Optional port ID to assign the floating IP to. If not provided, the will use the first routable port on the server.

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(reservable=None, gpu=None, reservation_id=None) → List[Flavor][source]¶

Get a list of flavors

Parameters:

reservable (bool) – If given, whether to filter by reservable flavors.
gpu (bool) – If given, whether to filter by GPU flavors.
reservation_id (str, optional) – The reservation ID to filter by. Defaults to None.

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.