Client Tools (“ccmanage”)

These are the collection of modules and scripts used to perform common tasks like launching a single node. They generally use the Python APIs, so are kept separate in the ccmanage package.

Because they use the Python APIs, they may be sensitive to the versions installed; consult the requirements.txt file for what’s known to work. Notably, the Blazar client comes from a repo rather than PyPI, so may be a bit volatile.

These APIs are also used by Abracadabra, the automated Chameleon appliance builder thing.

Quicknode

The quicknode script creates a 24-hour lease, launches an instance on it, then binds a floating IP to it. One command, a 10 to 15 minute wait, and you can SSH in to your very own bare metal node.

ccmanage.quicknode.main(argv=None)

This script must be run as a module using python -m ccmanage.quicknode. In the future it could be configured as an entry point in setup.py and installed like the hammers scripts.

$ python -m ccmanage.quicknode --help
usage: quicknode.py [-h] [--osrc OSRC] [--node-type NODE_TYPE]
                    [--key-name KEY_NAME] [--image IMAGE] [--no-clean]
                    [--net-name NET_NAME] [--no-floatingip]

Fire up a single node on Chameleon to do something with.

optional arguments:
-h, --help            show this help message and exit
--osrc OSRC           OpenStack parameters file that overrides envvars.
                        (default: None)
--node-type NODE_TYPE
                        Node type to launch. May be custom or likely one of:
                        'compute_skylake', 'gpu_p100',
                        'gpu_p100_nvlink', 'gpu_k80', 'gpu_m40',
                        'compute_haswell_ib', 'storage', 'atom',
                        'compute_haswell', 'storage_hierarchy', 'arm64',
                        'fpga', 'lowpower_xeon' (default: compute_haswell)
--key-name KEY_NAME   SSH keypair name on OS used to create an instance.
                        Must exist in Nova (default: default)
--image IMAGE         Name or ID of image to launch. (default: CC-CentOS7)
--no-clean            Do not clean up on failure. (default: False)
--net-name NET_NAME   Name of network to connect to. (default: sharednet1)
--no-floatingip       Skip assigning a floating IP. (default: False)

It can either read the environment variables (i.e. you did a source osvars.rc) or be given a file with them—including the password—in it (--osrc). There must be a key pair loaded into Nova that matches the option for --key-name. A basic run:

$ python -m ccmanage.quicknode --image CC-CentOS7
Lease: creating...started <Lease 'lease-JTCMZOKMHE' on chi.uc.chameleoncloud.org (ad67ccb1-edeb-462b-a9b3-83727578b937)>
Server: creating...building...started <Server 'instance-KYJCM5N55A' on chi.uc.chameleoncloud.org (36d52a0d-428d-45a8-88fb-232898aff0cb)>...bound ip 192.5.87.37 to server.

'ssh cc@192.5.87.37' available.
Press enter to terminate lease and server.

It attempts to remove the lease after hitting enter, the instance is deleted along with it.

The main function is also a handy reference for how the other objects in ccmanage work, specifically ccmanage.lease.Lease and ccmanage.server.Server (created in a factory method of Lease)

Authentication

Generate “real” Keystone auth objects versus the DIY methods like in hammers.osapi

ccmanage.auth.add_arguments(parser)

Inject our args into the user’s ArgumentParser parser. The resulting argument namespace can be inspected by session_from_args().

ccmanage.auth.auth_from_rc(rc)

Generates a Keystone Auth object from an OS parameter dictionary. Dict key format is the same as environment variables (OS_AUTH_URL, et al.)

We do some dumb gymnastics because everything expects the parameters in their own cap/delim format:

• envvar name: OS_AUTH_URL
• loader option name: auth-url
• loader argument name: auth_url

ccmanage.auth.session_from_vars(os_vars)

Generates a keystoneauth1.session.Session object from an OS parameter dictionary akin to auth_from_rc(). This one is generally more useful as the session object can be used directly with most clients:

>>> from novaclient.client import Client as NovaClient
>>> from ccmanage.auth import session_from_vars
>>> session = session_from_vars({'OS_AUTH_URL': ...})
>>> nova = NovaClient('2', session=session)

ccmanage.auth.session_from_args(args=None, rc=False)

Combine the osrc attribute in the namespace args (if provided) with the environment vars and produce a Keystone session for use by clients.

Optionally return the RC dictionary with the OS vars used to construct the session as the second value in a 2-tuple if rc is true.

Leases

Lease management

class ccmanage.lease.Lease(keystone_session, *, sequester=False, _no_clean=False, **lease_kwargs)

Creates and manages a lease, optionally with a context manager (with).

with Lease(session, node_type='compute_haswell') as lease:
    instance = lease.create_server()
    ...

When using the context manager, on entering it will wait for the lease to launch, then on exiting it will delete the lease, which in-turn also deletes the instances launched with it.

Parameters:

• keystone_session – session object
• sequester (bool) – If the context manager catches that an instance failed to start, it will not delete the lease, but rather extend it and rename it with the ID of the instance that failed.
• _no_clean (bool) – Don’t delete the lease at the end of a context manager
• lease_kwargs – Parameters passed through to lease_create_nodetype() and in turn lease_create_args()

create_server(*server_args, **server_kwargs)

Generates instances using the resource of the lease. Arguments are passed to ccmanage.server.Server and returns same object.

delete()

Deletes the lease

classmethod from_existing(keystone_session, id)

Attach to an existing lease by ID. When using in conjunction with the context manager, it will not delete the lease at the end.

ready

Returns True if the lease has started.

refresh()

Updates the lease data

status

Refreshes and returns the status of the lease.

wait()

Blocks for up to 150 seconds, waiting for the lease to be ready. Raises a RuntimeError if it times out.

ccmanage.lease.lease_create_nodetype(*args, *, node_type, **kwargs)

Wrapper for lease_create_args() that adds the resource_properties payload to specify node type.

Parameters:node_type (str) – Node type to filter by, compute_haswell, et al. Raises:ValueError – if there is no node_type named argument.

ccmanage.lease.lease_create_args(name=None, start='now', length=None, end=None, nodes=1, resource_properties='')

Generates the nested object that needs to be sent to the Blazar client to create the lease. Provides useful defaults for Chameleon.

Parameters:

• name (str) – name of lease. If None, generates a random name.
• start (str/datetime) – when to start lease as a datetime.datetime object, or if the string 'now', starts in about a minute.
• length – length of time as a datetime.timedelta object or number of seconds as a number. Defaults to 1 day.
• end (datetime.datetime) – when to end the lease. Provide only this or length, not both.
• nodes (int) – number of nodes to reserve.
• resource_properties – object that is JSON-encoded and sent as the resource_properties value to Blazar. Commonly used to specify node types.

Servers

class ccmanage.server.Server(session, id=None, lease=None, key='default', image='CC-CentOS7', net_ids=None, net_name=None, **extra)

Launches an instance on a lease.