class ClusterMember(model.Model):
"""A LXD cluster member."""
url = model.Attribute(readonly=True)
database = model.Attribute(readonly=True)
server_name = model.Attribute(readonly=True)
status = model.Attribute(readonly=True)
message = model.Attribute(readonly=True)
cluster = model.Parent()
@classmethod
def get(cls, client, server_name):
"""Get a cluster member by name."""
response = client.api.cluster.members[server_name].get()
return cls(client, **response.json()["metadata"])
@classmethod
def all(cls, client, *args):
"""Get all cluster members."""
response = client.api.cluster.members.get()
nodes = []
for node in response.json()["metadata"]:
server_name = node.split("/")[-1]
nodes.append(cls(client, server_name=server_name))
return nodes
@property
def api(self):
return self.client.api.cluster.members[self.server_name]
class ClusterCertificate(model.Model):
"""A LXD cluster certificate"""
cluster_certificate = model.Attribute()
cluster_certificate_key = model.Attribute()
cluster = model.Parent()
@classmethod
def put(cls, client, cert, key):
response = client.api.cluster.certificate.put(
json={"cluster_certificate": cert, "cluster_certificate_key": key}
)
if response.status_code == 200:
return
raise LXDAPIException(response)
@property
def api(self):
return self.client.api.cluster.certificate
class Snapshot(model.Model):
"""A container snapshot."""
name = model.Attribute()
stateful = model.Attribute()
container = model.Parent()
@property
def api(self):
return self.client.api.containers[self.container.name].snapshots[
self.name]
@classmethod
def get(cls, client, container, name):
response = client.api.containers[container.name].snapshots[name].get()
snapshot = cls(client,
container=container,
**response.json()['metadata'])
# Snapshot names are namespaced in LXD, as
# container-name/snapshot-name. We hide that implementation
# detail.
snapshot.name = snapshot.name.split('/')[-1]
return snapshot
@classmethod
def all(cls, client, container):
response = client.api.containers[container.name].snapshots.get()
return [
cls(client, name=snapshot.split('/')[-1], container=container)
for snapshot in response.json()['metadata']
]
@classmethod
def create(cls, client, container, name, stateful=False, wait=False):
response = client.api.containers[container.name].snapshots.post(
json={
'name': name,
'stateful': stateful
})
snapshot = cls(client, container=container, name=name)
if wait:
Operation.wait_for_operation(client, response.json()['operation'])
return snapshot
def rename(self, new_name, wait=False):
"""Rename a snapshot."""
response = self.api.post(json={'name': new_name})
if wait:
Operation.wait_for_operation(self.client,
response.json()['operation'])
self.name = new_name
def publish(self, public=False, wait=False):
"""Publish a snapshot as an image.
If wait=True, an Image is returned.
This functionality is currently broken in LXD. Please see
https://github.com/lxc/lxd/issues/2201 - The implementation
here is mostly a guess. Once that bug is fixed, we can verify
that this works, or file a bug to fix it appropriately.
"""
data = {
'public': public,
'source': {
'type': 'snapshot',
'name': '{}/{}'.format(self.container.name, self.name),
}
}
response = self.client.api.images.post(json=data)
if wait:
operation = Operation.wait_for_operation(
self.client,
response.json()['operation'])
return self.client.images.get(operation.metadata['fingerprint'])
class Snapshot(model.Model):
"""A container snapshot."""
name = model.Attribute()
created_at = model.Attribute()
stateful = model.Attribute()
container = model.Parent()
@property
def api(self):
return self.client.api.containers[self.container.name].snapshots[
self.name]
@classmethod
def get(cls, client, container, name):
response = client.api.containers[container.name].snapshots[name].get()
snapshot = cls(client,
container=container,
**response.json()['metadata'])
# Snapshot names are namespaced in LXD, as
# container-name/snapshot-name. We hide that implementation
# detail.
snapshot.name = snapshot.name.split('/')[-1]
return snapshot
@classmethod
def all(cls, client, container):
response = client.api.containers[container.name].snapshots.get()
return [
cls(client, name=snapshot.split('/')[-1], container=container)
for snapshot in response.json()['metadata']
]
@classmethod
def create(cls, client, container, name, stateful=False, wait=False):
response = client.api.containers[container.name].snapshots.post(
json={
'name': name,
'stateful': stateful
})
snapshot = cls(client, container=container, name=name)
if wait:
client.operations.wait_for_operation(response.json()['operation'])
return snapshot
def rename(self, new_name, wait=False):
"""Rename a snapshot."""
response = self.api.post(json={'name': new_name})
if wait:
self.client.operations.wait_for_operation(
response.json()['operation'])
self.name = new_name
def publish(self, public=False, wait=False):
"""Publish a snapshot as an image.
If wait=True, an Image is returned.
This functionality is currently broken in LXD. Please see
https://github.com/lxc/lxd/issues/2201 - The implementation
here is mostly a guess. Once that bug is fixed, we can verify
that this works, or file a bug to fix it appropriately.
"""
data = {
'public': public,
'source': {
'type': 'snapshot',
'name': '{}/{}'.format(self.container.name, self.name),
}
}
response = self.client.api.images.post(json=data)
if wait:
operation = self.client.operations.wait_for_operation(
response.json()['operation'])
return self.client.images.get(operation.metadata['fingerprint'])
def restore(self, wait=False):
"""Restore this snapshot.
Attempts to restore a container using this snapshot. The container
should be stopped, but the method does not enforce this constraint, so
an LXDAPIException may be raised if this method fails.
:param wait: wait until the operation is completed.
:type wait: boolean
:raises: LXDAPIException if the the operation fails.
:returns: the original response from the restore operation (not the
operation result)
:rtype: :class:`requests.Response`
"""
return self.container.restore_snapshot(self.name, wait)
class Snapshot(model.Model):
"""A instance snapshot."""
name = model.Attribute()
created_at = model.Attribute()
stateful = model.Attribute()
instance = model.Parent()
@property
def api(self):
return self.client.api[self.instance._endpoint][
self.instance.name].snapshots[self.name]
@classmethod
def get(cls, client, instance, name):
response = client.api[instance._endpoint][
instance.name].snapshots[name].get()
snapshot = cls(client,
instance=instance,
**response.json()["metadata"])
# Snapshot names are namespaced in LXD, as
# instance-name/snapshot-name. We hide that implementation
# detail.
snapshot.name = snapshot.name.split("/")[-1]
return snapshot
@classmethod
def all(cls, client, instance):
response = client.api[instance._endpoint][
instance.name].snapshots.get()
return [
cls(client, name=snapshot.split("/")[-1], instance=instance)
for snapshot in response.json()["metadata"]
]
@classmethod
def create(cls, client, instance, name, stateful=False, wait=False):
response = client.api[instance._endpoint][
instance.name].snapshots.post(json={
"name": name,
"stateful": stateful
})
snapshot = cls(client, instance=instance, name=name)
if wait:
client.operations.wait_for_operation(response.json()["operation"])
return snapshot
def rename(self, new_name, wait=False):
"""Rename a snapshot."""
response = self.api.post(json={"name": new_name})
if wait:
self.client.operations.wait_for_operation(
response.json()["operation"])
self.name = new_name
def publish(self, public=False, wait=False):
"""Publish a snapshot as an image.
If wait=True, an Image is returned.
This functionality is currently broken in LXD. Please see
https://github.com/lxc/lxd/issues/2201 - The implementation
here is mostly a guess. Once that bug is fixed, we can verify
that this works, or file a bug to fix it appropriately.
"""
data = {
"public": public,
"source": {
"type": "snapshot",
"name": "{}/{}".format(self.instance.name, self.name),
},
}
response = self.client.api.images.post(json=data)
if wait:
operation = self.client.operations.wait_for_operation(
response.json()["operation"])
return self.client.images.get(operation.metadata["fingerprint"])
def restore(self, wait=False):
"""Restore this snapshot.
Attempts to restore a instance using this snapshot. The instance
should be stopped, but the method does not enforce this constraint, so
an LXDAPIException may be raised if this method fails.
:param wait: wait until the operation is completed.
:type wait: boolean
:raises: LXDAPIException if the the operation fails.
:returns: the original response from the restore operation (not the
operation result)
:rtype: :class:`requests.Response`
"""
return self.instance.restore_snapshot(self.name, wait)
class StorageVolume(model.Model):
"""An LXD Storage volume.
This corresponds to the LXD endpoing at
/1.0/storage-pools/<pool>/volumes
api_extension: 'storage'
"""
name = model.Attribute(readonly=True)
type = model.Attribute(readonly=True)
description = model.Attribute(readonly=True)
config = model.Attribute()
used_by = model.Attribute(readonly=True)
location = model.Attribute(readonly=True)
storage_pool = model.Parent()
@property
def api(self):
"""Provides an object with the endpoint:
/1.0/storage-pools/<storage_pool.name>/volumes/<self.type>/<self.name>
Used internally to construct endpoints.
:returns: an API node with the named endpoint
:rtype: :class:`pylxd.client._APINode`
"""
return self.storage_pool.api.volumes[self.type][self.name]
@classmethod
def all(cls, storage_pool):
"""Get all the volumnes for this storage pool.
Implements GET /1.0/storage-pools/<name>/volumes
Volumes returned from this method will only have the name
set, as that is the only property returned from LXD. If more
information is needed, `StorageVolume.sync` is the method call
that should be used.
Note that the storage volume types are 'container', 'image' and
'custom', and these maps to the names 'containers', 'images' and
everything else is mapped to 'custom'.
:param storage_pool: a storage pool object on which to fetch resources
:type storage_pool: :class:`pylxd.models.storage_pool.StoragePool`
:returns: a list storage volume if successful
:rtype: [:class:`pylxd.models.storage_pool.StorageVolume`]
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage' api extension is missing.
"""
storage_pool.client.assert_has_api_extension('storage')
response = storage_pool.api.volumes.get()
volumes = []
for volume in response.json()['metadata']:
(_type, name) = volume.split('/')[-2:]
# for each type, convert to the string that will work with GET
if _type == 'containers':
_type = 'container'
elif _type == 'images':
_type = 'image'
else:
_type = 'custom'
volumes.append(
cls(storage_pool.client,
name=name,
type=_type,
storage_pool=storage_pool))
return volumes
@classmethod
def get(cls, storage_pool, _type, name):
"""Get a StorageVolume by type and name.
Implements GET /1.0/storage-pools/<pool>/volumes/<type>/<name>
The `_type` param can only (currently) be one of 'container', 'image'
or 'custom'. This was determined by read the LXD source.
:param storage_pool: a storage pool object on which to fetch resources
:type storage_pool: :class:`pylxd.models.storage_pool.StoragePool`
:param _type: the type; one of 'container', 'image', 'custom'
:type _type: str
:param name: the name of the storage volume to get
:type name: str
:returns: a storage pool if successful, raises NotFound if not found
:rtype: :class:`pylxd.models.storage_pool.StorageVolume`
:raises: :class:`pylxd.exceptions.NotFound`
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage' api extension is missing.
"""
storage_pool.client.assert_has_api_extension('storage')
response = storage_pool.api.volumes[_type][name].get()
volume = cls(storage_pool.client,
storage_pool=storage_pool,
**response.json()['metadata'])
return volume
@classmethod
# def create(cls, storage_pool, definition, wait=True, *args):
def create(cls, storage_pool, *args, **kwargs):
"""Create a 'custom' Storage Volume in the associated storage pool.
Implements POST /1.0/storage-pools/<pool>/volumes/custom
See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-19 for
more details on what the `definition` parameter dictionary should
contain for various volume creation.
At the moment the only type of volume that can be created is 'custom',
and this is currently hardwired into the function.
The function signature 'hides' that the first parameter to the function
is the definition. The function should be called as:
>>> a_storage_pool.volumes.create(definition_dict, wait=<bool>)
where `definition_dict` is mandatory, and `wait` defaults to True,
which makes the default a synchronous function call.
Note that **all** fields in the `definition` parameter are strings.
If the caller doesn't wan't to wait for an async operation, then it
MUST be passed as a keyword argument, and not as a positional
substitute.
The function returns the a
:class:`~pylxd.models.storage_pool.StoragePool` instance, if it is
successfully created, otherwise an Exception is raised.
:param storage_pool: a storage pool object on which to fetch resources
:type storage_pool: :class:`pylxd.models.storage_pool.StoragePool`
:param definition: the fields to pass to the LXD API endpoint
:type definition: dict
:param wait: wait until an async action has completed (default True)
:type wait: bool
:returns: a storage pool volume if successful, raises NotFound if not
found
:rtype: :class:`pylxd.models.storage_pool.StorageVolume`
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage' api extension is missing.
:raises: :class:`pylxd.exceptions.LXDAPIException` if the storage pool
volume couldn't be created.
"""
# This is really awkward, but the implementation details mean,
# depending on how this function is called, we can't know whether the
# 2nd positional argument will be definition or a client object. This
# is an difficulty with how BaseManager is implemented, and to get the
# convenience of being able to call this 'naturally' off of a
# storage_pool. So we have to jump through some hurdles to get the
# right positional parameters.
storage_pool.client.assert_has_api_extension('storage')
wait = kwargs.get('wait', True)
definition = args[-1]
assert isinstance(definition, dict)
assert 'name' in definition
response = storage_pool.api.volumes.custom.post(json=definition)
if response.json()['type'] == 'async' and wait:
storage_pool.client.operations.wait_for_operation(
response.json()['operation'])
volume = cls.get(storage_pool, 'custom', definition['name'])
return volume
def rename(self, _input, wait=False):
"""Rename a storage volume
This requires api_extension: 'storage_api_volume_rename'.
Implements: POST /1.0/storage-pools/<pool>/volumes/<type>/<name>
This operation is either sync or async (when moving to a different
pool).
This command also allows the migration across instances, and therefore
it returns the metadata section (as a dictionary) from the call. The
caller should assume that the object is stale and refetch it after any
migrations are done. However, the 'name' attribute of the object is
updated for consistency.
Unlike :meth:`~pylxd.models.storage_pool.StorageVolume.create`, this
method does not override any items in the input definition, although it
does check that the 'name' and 'pool' parameters are set.
Please see: https://github.com/lxc/lxd/blob/master/doc/rest-api.md
#10storage-poolspoolvolumestypename
for more details.
:param _input: The `input` specification for the rename.
:type _input: dict
:param wait: Wait for an async operation, if it is async.
:type wait: bool
:returns: The dictionary from the metadata section of the response if
successful.
:rtype: dict[str, str]
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage_api_volume_rename' api extension is missing.
:raises: :class:`pylxd.exceptions.LXDAPIException` if the storage pool
volume couldn't be renamed.
"""
assert isinstance(_input, dict)
assert 'name' in _input
assert 'pool' in _input
response = self.api.post(json=_input)
response_json = response.json()
if wait:
self.client.operations.wait_for_operation(
response_json['operation'])
self.name = _input['name']
return response_json['metadata']
def put(self, put_object, wait=False):
"""Put the storage volume.
Implements: PUT /1.0/storage-pools/<pool>/volumes/<type>/<name>
Note that this is functionality equivalent to
:meth:`~pyxld.models.storage_pool.StorageVolume.save` but by using a
new object (`put_object`) rather than modifying the object and then
calling :meth:`~pyxld.models.storage_pool.StorageVolume.save`.
Putting to a storage volume may fail if the new configuration is
incompatible with the pool. See the LXD documentation for further
details.
Note that the object is refreshed with a `sync` if the PUT is
successful. If this is *not* desired, then the raw API on the client
should be used.
:param put_object: A dictionary. The most useful key will be the
`config` key.
:type put_object: dict
:param wait: Whether to wait for async operations to complete.
:type wait: bool
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage' api extension is missing.
:raises: :class:`pylxd.exceptions.LXDAPIException` if the storage pool
can't be modified.
"""
# Note this method exists so that it is documented via sphinx.
super(StorageVolume, self).put(put_object, wait)
def patch(self, patch_object, wait=False):
"""Patch the storage volume.
Implements: PATCH /1.0/storage-pools/<pool>/volumes/<type>/<name>
Patching the object allows for more fine grained changes to the config.
The object is refreshed if the PATCH is successful. If this is *not*
required, then use the client api directly.
:param patch_object: A dictionary. The most useful key will be the
`config` key.
:type patch_object: dict
:param wait: Whether to wait for async operations to complete.
:type wait: bool
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage' api extension is missing.
:raises: :class:`pylxd.exceptions.LXDAPIException` if the storage
volume can't be modified.
"""
# Note this method exists so that it is documented via sphinx.
super(StorageVolume, self).patch(patch_object, wait)
def save(self, wait=False):
"""Save the model using PUT back to the LXD server.
Implements: PUT /1.0/storage-pools/<pool>/volumes/<type>/<name>
*automagically*.
The field affected is `config`. Note that it is replaced *entirety*.
If finer grained control is required, please use the
:meth:`~pylxd.models.storage_pool.StorageVolume.patch` method directly.
Updating a storage volume may fail if the config is not acceptable to
LXD. An :class:`~pylxd.exceptions.LXDAPIException` will be generated in
that case.
:param wait: Whether to wait for async operations to complete.
:type wait: bool
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage' api extension is missing.
:raises: :class:`pylxd.exceptions.LXDAPIException` if the storage
volume can't be deleted.
"""
# Note this method exists so that it is documented via sphinx.
super(StorageVolume, self).save(wait=wait)
def delete(self):
"""Delete the storage pool.
Implements: DELETE /1.0/storage-pools/<pool>/volumes/<type>/<name>
Deleting a storage volume may fail if it is being used. See the LXD
documentation for further details.
:raises: :class:`pylxd.exceptions.LXDAPIExtensionNotAvailable` if the
'storage' api extension is missing.
:raises: :class:`pylxd.exceptions.LXDAPIException` if the storage pool
can't be deleted.
"""
# Note this method exists so that it is documented via sphinx.
super(StorageVolume, self).delete()
