Add user documentation for the Python API
Most of the copy is duplicated except for the places where it matters. This allows for any page of this documentation to be page one. If someone only cares about using hosts first, they can go directly there and start listing hosts, creating them, etc. without much other prompting. Change-Id: Id621947af5d4c3ca53af24904f5f16d3d88bc8b8
This commit is contained in:
parent
40e6be281c
commit
75c3531c43
|
@ -14,7 +14,7 @@ Contents:
|
|||
|
||||
readme
|
||||
installation
|
||||
usage
|
||||
usage/index
|
||||
v1-api-documentation
|
||||
authentication-documentation
|
||||
contributing
|
||||
|
|
|
@ -2,6 +2,15 @@
|
|||
Installation
|
||||
==============
|
||||
|
||||
.. note::
|
||||
|
||||
There has not been a stable release of python-cratonclient to PyPI yet. To
|
||||
install the current version in development use:
|
||||
|
||||
.. code::
|
||||
|
||||
pip install git+https://git.openstack.org/openstack/python-cratonclient
|
||||
|
||||
At the command line::
|
||||
|
||||
$ pip install python-cratonclient
|
||||
|
|
|
@ -1,24 +1,8 @@
|
|||
=======================
|
||||
Python API User Guide
|
||||
=======================
|
||||
.. _usage-auth:
|
||||
|
||||
Once you have installed ``python-cratonclient``, there are a few things you
|
||||
need to get started using the Python API:
|
||||
|
||||
#. You need to know how to authenticate to the Craton API you wish to talk to
|
||||
|
||||
Some Craton API services will be deployed using Craton's in-built
|
||||
authentication system while others may use Keystone.
|
||||
|
||||
#. You need your credentials
|
||||
|
||||
#. You need the location of your Craton API service
|
||||
|
||||
Let's cover authentication first:
|
||||
|
||||
|
||||
Authenticating to Craton
|
||||
========================
|
||||
==========================
|
||||
Authenticating to Craton
|
||||
==========================
|
||||
|
||||
There are two ways to authenticate to Craton:
|
||||
|
||||
|
@ -71,9 +55,6 @@ Then, we need to do the following:
|
|||
|
||||
.. code-block:: python
|
||||
|
||||
from keystoneauth1.identity.v3 import password as password_auth
|
||||
from keystoneauth1 import session as ksa_session
|
||||
|
||||
from cratonclient import auth
|
||||
from cratonclient.v1 import client
|
||||
|
||||
|
@ -89,46 +70,3 @@ Then, we need to do the following:
|
|||
session=craton_session,
|
||||
url=URL,
|
||||
)
|
||||
|
||||
|
||||
Communicating with Craton
|
||||
=========================
|
||||
|
||||
Now that you've configured your authentication method, you can interact with
|
||||
your ``craton`` object like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for region in craton.regions.list():
|
||||
print('Region {} contains:'.format(region.name))
|
||||
for host in craton.hosts.list(region_id=region.id):
|
||||
print(' {}'.format(host.name))
|
||||
|
||||
|
||||
The Craton API has the following resources:
|
||||
|
||||
- Cells
|
||||
|
||||
- Hosts
|
||||
|
||||
- Network Devices
|
||||
|
||||
- Network Interfaces
|
||||
|
||||
- Networks
|
||||
|
||||
- Projects
|
||||
|
||||
- Regions
|
||||
|
||||
- Users
|
||||
|
||||
Of these:
|
||||
|
||||
- Cells
|
||||
|
||||
- Hosts
|
||||
|
||||
- Regions
|
||||
|
||||
Are implemented.
|
|
@ -0,0 +1,136 @@
|
|||
=====================
|
||||
Using the Cells API
|
||||
=====================
|
||||
|
||||
Here we will assume that we already have a
|
||||
:class:`~cratonclient.client.Client` instance configured with the appropriate
|
||||
authentication method (as demonstrated in :ref:`usage-auth`).
|
||||
|
||||
Listing Cells
|
||||
-------------
|
||||
|
||||
The Cells API implements pagination. This means that by default, it does not
|
||||
return all cells known to Craton. To ignore page limits and offsets, we can
|
||||
allow cratonclient to do handle pagination for us:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for cell in craton.cells.list():
|
||||
print_cell_info(cell)
|
||||
|
||||
By default :meth:`~cratonclient.v1.cells.CellsManager.list` will handle
|
||||
pagination for you. If, instead, you want to handle it yourself you will want
|
||||
to do something akin to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
first_page_of_cells = list(craton.cells.list(autopaginate=False))
|
||||
marker_id = first_page_of_cells[-1].id
|
||||
second_page_of_cells = list(craton.cells.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
marker_id = second_page_of_cells[-1].id
|
||||
third_page_of_cells = list(craton.cells.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
# etc.
|
||||
|
||||
A more realistic example, however, might look like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cells_list = None
|
||||
marker = None
|
||||
while cells_list and cells_list is not None:
|
||||
cells_list = list(craton.cells.list(
|
||||
marker=marker,
|
||||
autopaginate=False,
|
||||
))
|
||||
# do something with cells_list
|
||||
if cells_list:
|
||||
marker = cells_list[-1].id
|
||||
|
||||
This will have the effect of stopping the while loop when you eventually
|
||||
receive an empty list from ``craton.cells.list(...)``.
|
||||
|
||||
Creating Cells
|
||||
--------------
|
||||
|
||||
Cells live below a Region in Craton. To create a cell, the only required items
|
||||
are a ``name`` for the cell, a cloud ID, and a region ID. The name must be
|
||||
unique among cells in the same project.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cell = craton.cells.create(
|
||||
name='my-cell-0',
|
||||
cloud_id=cloud_id,
|
||||
region_id=region_id,
|
||||
note='This is my cell, there are many like it, but this is mine.',
|
||||
variables={
|
||||
'some-var': 'some-var-value',
|
||||
},
|
||||
)
|
||||
|
||||
Retrieving a Specific Cell
|
||||
--------------------------
|
||||
|
||||
Cells can be retrieved by id.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cell = craton.cells.get(1)
|
||||
|
||||
Using a Cell's Variables
|
||||
-------------------------
|
||||
|
||||
Once we have a cell we can introspect its variables like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cell = craton.cells.get(cell_id)
|
||||
cell_vars = cell.variables.get()
|
||||
|
||||
To update them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
updated_vars = {
|
||||
'var-a': 'new-var-a',
|
||||
'var-b': 'new-var-b',
|
||||
'updated-var': 'updated value',
|
||||
}
|
||||
cell.variables.update(**updated_vars)
|
||||
|
||||
To delete them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cell.variables.delete('var-a', 'var-b', 'updated-var')
|
||||
|
||||
Updating a Cell
|
||||
---------------
|
||||
|
||||
We can update a cell's attributes (but not its variables) like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.cells.update(
|
||||
cell_id,
|
||||
name='new name',
|
||||
note='Updated note.',
|
||||
)
|
||||
|
||||
Most attributes that you can specify on creation can also be specified for
|
||||
updating the cell as well.
|
||||
|
||||
Deleting a Cell
|
||||
---------------
|
||||
|
||||
We can delete with only its id:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.cells.delete(cell_id)
|
|
@ -0,0 +1,134 @@
|
|||
======================
|
||||
Using the Clouds API
|
||||
======================
|
||||
|
||||
Here we will assume that we already have a
|
||||
:class:`~cratonclient.client.Client` instance configured with the appropriate
|
||||
authentication method (as demonstrated in :ref:`usage-auth`).
|
||||
|
||||
Listing Clouds
|
||||
--------------
|
||||
|
||||
The Clouds API implements pagination. This means that by default, it does not
|
||||
return all clouds known to Craton. To ignore page limits and offsets, we can
|
||||
allow cratonclient to do handle pagination for us:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for cloud in craton.clouds.list():
|
||||
print_cloud_info(cloud)
|
||||
|
||||
By default :meth:`~cratonclient.v1.clouds.CloudsManager.list` will handle
|
||||
pagination for you. If, instead, you want to handle it yourself you will want
|
||||
to do something akin to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
first_page_of_clouds = list(craton.clouds.list(autopaginate=False))
|
||||
marker_id = first_page_of_clouds[-1].id
|
||||
second_page_of_clouds = list(craton.clouds.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
marker_id = second_page_of_clouds[-1].id
|
||||
third_page_of_clouds = list(craton.clouds.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
# etc.
|
||||
|
||||
A more realistic example, however, might look like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
clouds_list = None
|
||||
marker = None
|
||||
while clouds_list and clouds_list is not None:
|
||||
clouds_list = list(craton.clouds.list(
|
||||
marker=marker,
|
||||
autopaginate=False,
|
||||
))
|
||||
# do something with clouds_list
|
||||
if clouds_list:
|
||||
marker = clouds_list[-1].id
|
||||
|
||||
This will have the effect of stopping the while loop when you eventually
|
||||
receive an empty list from ``craton.clouds.list(...)``.
|
||||
|
||||
Creating Clouds
|
||||
---------------
|
||||
|
||||
Clouds are the top-level item in Craton. To create a cloud, the only required
|
||||
item is a ``name`` for the cloud. This must be unique among clouds in the same
|
||||
project.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cloud = craton.clouds.create(
|
||||
name='my-cloud-0',
|
||||
note='This is my cloud, there are many like it, but this is mine.',
|
||||
variables={
|
||||
'some-var': 'some-var-value',
|
||||
},
|
||||
)
|
||||
|
||||
Retrieving a Specific Cloud
|
||||
---------------------------
|
||||
|
||||
Clouds can be retrieved by id.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cloud = craton.clouds.get(1)
|
||||
|
||||
Using a Cloud's Variables
|
||||
-------------------------
|
||||
|
||||
Once we have a cloud we can introspect its variables like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cloud = craton.clouds.get(cloud_id)
|
||||
cloud_vars = cloud.variables.get()
|
||||
|
||||
To update them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
updated_vars = {
|
||||
'var-a': 'new-var-a',
|
||||
'var-b': 'new-var-b',
|
||||
'updated-var': 'updated value',
|
||||
}
|
||||
cloud.variables.update(**updated_vars)
|
||||
|
||||
To delete them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cloud.variables.delete('var-a', 'var-b', 'updated-var')
|
||||
|
||||
Updating a Cloud
|
||||
----------------
|
||||
|
||||
We can update a cloud's attributes (but not its variables) like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.clouds.update(
|
||||
cloud_id,
|
||||
name='new name',
|
||||
note='Updated note.',
|
||||
)
|
||||
|
||||
Most attributes that you can specify on creation can also be specified for
|
||||
updating the cloud as well.
|
||||
|
||||
Deleting a Cloud
|
||||
----------------
|
||||
|
||||
We can delete with only its id:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.clouds.delete(cloud_id)
|
|
@ -0,0 +1,32 @@
|
|||
=======================
|
||||
Using the Devices API
|
||||
=======================
|
||||
|
||||
Here we will assume that we already have a
|
||||
:class:`~cratonclient.client.Client` instance configured with the appropriate
|
||||
authentication method (as demonstrated in :ref:`usage-auth`).
|
||||
|
||||
.. note::
|
||||
|
||||
The Devices API is quite unlike other API endpoints presently in craton.
|
||||
At the moment, it returns both hosts and network devices. It concatenates
|
||||
the two lists in an indeterminate manner. On one invocation, you may
|
||||
receive the hosts first and then the network devices, on another you may
|
||||
receive them in the alternate order. If more items are returned in these
|
||||
listings, then the number of different orderings will only increase
|
||||
factorially.
|
||||
|
||||
Listing Devices
|
||||
---------------
|
||||
|
||||
The Devices API implements pagination. This means that by default, it does not
|
||||
return all devices known to Craton. To ignore page limits and offsets, we can
|
||||
allow cratonclient to do handle pagination for us:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for device in craton.devices.list():
|
||||
print_device_info(device)
|
||||
|
||||
By default :meth:`~cratonclient.v1.devices.DevicesManager.list` will handle
|
||||
pagination for you.
|
|
@ -0,0 +1,148 @@
|
|||
=====================
|
||||
Using the Hosts API
|
||||
=====================
|
||||
|
||||
Here we will assume that we already have a
|
||||
:class:`~cratonclient.client.Client` instance configured with the appropriate
|
||||
authentication method (as demonstrated in :ref:`usage-auth`).
|
||||
|
||||
Listing Hosts
|
||||
-------------
|
||||
|
||||
The Hosts API implements pagination. This means that by default, it does not
|
||||
return all hosts known to Craton. To ignore page limits and offsets, we can
|
||||
allow cratonclient to do handle pagination for us:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for host in craton.hosts.list():
|
||||
print_host_info(host)
|
||||
|
||||
By default :meth:`~cratonclient.v1.hosts.HostsManager.list` will handle
|
||||
pagination for you. If, instead, you want to handle it yourself you will want
|
||||
to do something akin to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
first_page_of_hosts = list(craton.hosts.list(autopaginate=False))
|
||||
marker_id = first_page_of_hosts[-1].id
|
||||
second_page_of_hosts = list(craton.hosts.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
marker_id = second_page_of_hosts[-1].id
|
||||
third_page_of_hosts = list(craton.hosts.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
# etc.
|
||||
|
||||
A more realistic example, however, might look like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
hosts_list = None
|
||||
marker = None
|
||||
while hosts_list and hosts_list is not None:
|
||||
hosts_list = list(craton.hosts.list(
|
||||
marker=marker,
|
||||
autopaginate=False,
|
||||
))
|
||||
# do something with hosts_list
|
||||
if hosts_list:
|
||||
marker = hosts_list[-1].id
|
||||
|
||||
This will have the effect of stopping the while loop when you eventually
|
||||
receive an empty list from ``craton.hosts.list(...)``.
|
||||
|
||||
Creating Hosts
|
||||
--------------
|
||||
|
||||
Hosts live inside either a Region or Cell in Craton. To create a host, one
|
||||
needs:
|
||||
|
||||
- A unique name
|
||||
|
||||
- A unique IP address
|
||||
|
||||
- A "device type" (this is freeform), e.g., "server", "container", "nova-vm",
|
||||
etc.
|
||||
|
||||
- A cloud ID
|
||||
|
||||
- A region ID
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
host = craton.hosts.create(
|
||||
name='my-host-0',
|
||||
ip_address='127.0.1.0',
|
||||
device_type='server',
|
||||
cloud_id=cloud_id,
|
||||
region_id=region_id,
|
||||
note='This is my host, there are many like it, but this is mine.',
|
||||
variables={
|
||||
'some-var': 'some-var-value',
|
||||
},
|
||||
)
|
||||
|
||||
Retrieving a Specific Host
|
||||
--------------------------
|
||||
|
||||
Hosts can be retrieved by id.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
host = craton.hosts.get(1)
|
||||
|
||||
Using a Host's Variables
|
||||
------------------------
|
||||
|
||||
Once we have a host we can introspect its variables like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
host = craton.hosts.get(host_id)
|
||||
host_vars = host.variables.get()
|
||||
|
||||
To update them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
updated_vars = {
|
||||
'var-a': 'new-var-a',
|
||||
'var-b': 'new-var-b',
|
||||
'updated-var': 'updated value',
|
||||
}
|
||||
host.variables.update(**updated_vars)
|
||||
|
||||
To delete them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
host.variables.delete('var-a', 'var-b', 'updated-var')
|
||||
|
||||
Updating a Host
|
||||
---------------
|
||||
|
||||
We can update a host's attributes (but not its variables) like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.hosts.update(
|
||||
host_id,
|
||||
name='new name',
|
||||
note='Updated note.',
|
||||
)
|
||||
|
||||
Most attributes that you can specify on creation can also be specified for
|
||||
updating the host as well.
|
||||
|
||||
Deleting a Host
|
||||
---------------
|
||||
|
||||
We can delete with only its id:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.hosts.delete(host_id)
|
|
@ -0,0 +1,30 @@
|
|||
=======================
|
||||
Python API User Guide
|
||||
=======================
|
||||
|
||||
Once you have installed ``python-cratonclient``, there are a few things you
|
||||
need to get started using the Python API:
|
||||
|
||||
#. You need to know how to authenticate to the Craton API you wish to talk to
|
||||
|
||||
Some Craton API services will be deployed using Craton's in-built
|
||||
authentication system while others may use Keystone.
|
||||
|
||||
#. You need your credentials
|
||||
|
||||
#. You need the location of your Craton API service
|
||||
|
||||
This chapter of python-cratonclient's documentation is broken down into
|
||||
chapters:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
authentication
|
||||
supported-apis
|
||||
clouds
|
||||
regions
|
||||
cells
|
||||
hosts
|
||||
devices
|
||||
projects
|
|
@ -0,0 +1,135 @@
|
|||
========================
|
||||
Using the Projects API
|
||||
========================
|
||||
|
||||
Here we will assume that we already have a
|
||||
:class:`~cratonclient.client.Client` instance configured with the appropriate
|
||||
authentication method (as demonstrated in :ref:`usage-auth`).
|
||||
|
||||
Listing Projects
|
||||
----------------
|
||||
|
||||
The Projects API implements pagination. This means that by default, it does not
|
||||
return all projects known to Craton. To ignore page limits and offsets, we can
|
||||
allow cratonclient to do handle pagination for us:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for project in craton.projects.list():
|
||||
print_project_info(project)
|
||||
|
||||
By default :meth:`~cratonclient.v1.projects.ProjectsManager.list` will handle
|
||||
pagination for you. If, instead, you want to handle it yourself you will want
|
||||
to do something akin to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
first_page_of_projects = list(craton.projects.list(autopaginate=False))
|
||||
marker_id = first_page_of_projects[-1].id
|
||||
second_page_of_projects = list(craton.projects.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
marker_id = second_page_of_projects[-1].id
|
||||
third_page_of_projects = list(craton.projects.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
# etc.
|
||||
|
||||
A more realistic example, however, might look like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
projects_list = None
|
||||
marker = None
|
||||
while projects_list and projects_list is not None:
|
||||
projects_list = list(craton.projects.list(
|
||||
marker=marker,
|
||||
autopaginate=False,
|
||||
))
|
||||
# do something with projects_list
|
||||
if projects_list:
|
||||
marker = projects_list[-1].id
|
||||
|
||||
This will have the effect of stopping the while loop when you eventually
|
||||
receive an empty list from ``craton.projects.list(...)``.
|
||||
|
||||
Creating Projects
|
||||
-----------------
|
||||
|
||||
Projects are top-level items in Craton. To create a project, one needs:
|
||||
|
||||
- A unique name
|
||||
|
||||
- Permission to create new projects
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
project = craton.projects.create(
|
||||
name='my-project-0',
|
||||
variables={
|
||||
'some-var': 'some-var-value',
|
||||
},
|
||||
)
|
||||
|
||||
Retrieving a Specific Project
|
||||
-----------------------------
|
||||
|
||||
Projects can be retrieved by id.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
project = craton.projects.get(1)
|
||||
|
||||
Using a Project's Variables
|
||||
---------------------------
|
||||
|
||||
Once we have a project we can introspect its variables like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
project = craton.projects.get(project_id)
|
||||
project_vars = project.variables.get()
|
||||
|
||||
To update them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
updated_vars = {
|
||||
'var-a': 'new-var-a',
|
||||
'var-b': 'new-var-b',
|
||||
'updated-var': 'updated value',
|
||||
}
|
||||
project.variables.update(**updated_vars)
|
||||
|
||||
To delete them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
project.variables.delete('var-a', 'var-b', 'updated-var')
|
||||
|
||||
Updating a Project
|
||||
------------------
|
||||
|
||||
We can update a project's attributes (but not its variables) like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.projects.update(
|
||||
project_id,
|
||||
name='new name',
|
||||
)
|
||||
|
||||
Most attributes that you can specify on creation can also be specified for
|
||||
updating the project as well.
|
||||
|
||||
Deleting a Project
|
||||
------------------
|
||||
|
||||
We can delete with only its id:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.projects.delete(project_id)
|
|
@ -0,0 +1,135 @@
|
|||
=======================
|
||||
Using the Regions API
|
||||
=======================
|
||||
|
||||
Here we will assume that we already have a
|
||||
:class:`~cratonclient.client.Client` instance configured with the appropriate
|
||||
authentication method (as demonstrated in :ref:`usage-auth`).
|
||||
|
||||
Listing Regions
|
||||
---------------
|
||||
|
||||
The Regions API implements pagination. This means that by default, it does not
|
||||
return all regions known to Craton. To ignore page limits and offsets, we can
|
||||
allow cratonclient to do handle pagination for us:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for region in craton.regions.list():
|
||||
print_region_info(region)
|
||||
|
||||
By default :meth:`~cratonclient.v1.regions.RegionsManager.list` will handle
|
||||
pagination for you. If, instead, you want to handle it yourself you will want
|
||||
to do something akin to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
first_page_of_regions = list(craton.regions.list(autopaginate=False))
|
||||
marker_id = first_page_of_regions[-1].id
|
||||
second_page_of_regions = list(craton.regions.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
marker_id = second_page_of_regions[-1].id
|
||||
third_page_of_regions = list(craton.regions.list(
|
||||
autopaginate=False,
|
||||
marker=marker_id,
|
||||
))
|
||||
# etc.
|
||||
|
||||
A more realistic example, however, might look like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
regions_list = None
|
||||
marker = None
|
||||
while regions_list and regions_list is not None:
|
||||
regions_list = list(craton.regions.list(
|
||||
marker=marker,
|
||||
autopaginate=False,
|
||||
))
|
||||
# do something with regions_list
|
||||
if regions_list:
|
||||
marker = regions_list[-1].id
|
||||
|
||||
This will have the effect of stopping the while loop when you eventually
|
||||
receive an empty list from ``craton.regions.list(...)``.
|
||||
|
||||
Creating Regions
|
||||
----------------
|
||||
|
||||
Regions are required to be part of a Cloud in Craton. To create a region, the
|
||||
only required items are a ``name`` for the region and the ID of the cloud it
|
||||
belongs to. The name must be unique among regions in the same project.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
region = craton.regions.create(
|
||||
name='my-region-0',
|
||||
cloud_id=cloud_id,
|
||||
note='This is my region, there are many like it, but this is mine.',
|
||||
variables={
|
||||
'some-var': 'some-var-value',
|
||||
},
|
||||
)
|
||||
|
||||
Retrieving a Specific Region
|
||||
----------------------------
|
||||
|
||||
Regions can be retrieved by id.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
region = craton.regions.get(1)
|
||||
|
||||
Using a Region's Variables
|
||||
--------------------------
|
||||
|
||||
Once we have a region we can introspect its variables like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
region = craton.regions.get(region_id)
|
||||
region_vars = region.variables.get()
|
||||
|
||||
To update them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
updated_vars = {
|
||||
'var-a': 'new-var-a',
|
||||
'var-b': 'new-var-b',
|
||||
'updated-var': 'updated value',
|
||||
}
|
||||
region.variables.update(**updated_vars)
|
||||
|
||||
To delete them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
region.variables.delete('var-a', 'var-b', 'updated-var')
|
||||
|
||||
Updating a Region
|
||||
-----------------
|
||||
|
||||
We can update a region's attributes (but not its variables) like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.regions.update(
|
||||
region_id,
|
||||
name='new name',
|
||||
note='Updated note.',
|
||||
)
|
||||
|
||||
Most attributes that you can specify on creation can also be specified for
|
||||
updating the region as well.
|
||||
|
||||
Deleting a Region
|
||||
-----------------
|
||||
|
||||
We can delete with only its id:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
craton.regions.delete(region_id)
|
|
@ -0,0 +1,50 @@
|
|||
===========================
|
||||
Communicating with Craton
|
||||
===========================
|
||||
|
||||
Now that you've configured your authentication method, you can interact with
|
||||
your ``craton`` object like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for region in craton.regions.list():
|
||||
print('Region {} contains:'.format(region.name))
|
||||
for host in craton.hosts.list(region_id=region.id):
|
||||
print(' {}'.format(host.name))
|
||||
|
||||
|
||||
The Craton API has the following resources:
|
||||
|
||||
- Cells
|
||||
|
||||
- Clouds
|
||||
|
||||
- Devices
|
||||
|
||||
- Hosts
|
||||
|
||||
- Network Devices
|
||||
|
||||
- Network Interfaces
|
||||
|
||||
- Networks
|
||||
|
||||
- Projects
|
||||
|
||||
- Regions
|
||||
|
||||
- Users
|
||||
|
||||
Of these:
|
||||
|
||||
- Cells
|
||||
|
||||
- Clouds
|
||||
|
||||
- Hosts
|
||||
|
||||
- Projects
|
||||
|
||||
- Regions
|
||||
|
||||
Are implemented.
|
Loading…
Reference in New Issue