python-cratonclient/doc/source/usage.rst

Python API User Guide

Once you have installed python-cratonclient, there are a few things you need to get started using the Python API:

1. 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.

2. You need your credentials

3. You need the location of your Craton API service

Let's cover authentication first:

Authenticating to Craton

There are two ways to authenticate to Craton:

1. Using Craton's in-built authentication system (the default)
2. Using Keystone

Craton Authentication

In the Craton Authentication case, you need the URL for the Craton API service, your username, project ID, and token. To set up cratonclient for this authentication, you need only do the following:

from cratonclient import session
from cratonclient.v1 import client

craton_session = session.Session(
    username=USERNAME,
    password=TOKEN,
    project_id=PROJECT_ID,
)

craton = client.Client(
    session=craton_session,
    url=URL,
)

Keystone Authentication

When authenticating to Craton using Keystone, you need to know:

• the URL to use to authenticate to Keystone which we will refer to as AUTH_URL
• the username
• the password
• the project ID or name
• the user domain ID or name
• and the project domain ID or name

Then, we need to do the following:

from keystoneauth1.identity.v3 import password as password_auth
from keystoneauth1 import session as ksa_session

from cratonclient import session
from cratonclient.v1 import client

_auth = password_auth.Password(
    auth_url=AUTH_URL,
    password=PASSWORD,
    username=USERNAME,
    user_domain_name=USER_DOMAIN_NAME,
    project_name=PROJECT_NAME,
    project_domain_name=PROJECT_DOMAIN_NAME,
)
craton_session = session.Session(session=ksa_session.Session(auth=_auth))
craton = client.Client(
    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:

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.