a8660a7e53
This patch set reorganizes Deckhand's documentation structure for better organization into 3 distinct categories: * developer's guide * operator's guide * user's guide This means that the RTD navigation menu on the left-hand side will have fewer links (see list above) making navigation much easier. This is similar to how Armada organizes its documentation too. This patch set also updates README section with a better overview and trims some fat from it (remove testing documentation as it doesn't really belong there -- there is a dedicated page for that already). Finally, this patch set changes the exceptions page to render as a basic list of autoexception classes because the current tabularized view is not rendering correctly on RTD [0]. [0] https://airship-deckhand.readthedocs.io/en/latest/exceptions.html Change-Id: I162383bf8e3bbd5004603c979ac7b0d760a210c4
5.5 KiB
Deckhand API Client Library Documentation
The recommended approach to instantiate the Deckhand client is via a Keystone session:
from keystoneauth1.identity import v3
from keystoneauth1 import session
keystone_auth = {
'project_domain_name': PROJECT_DOMAIN_NAME,
'project_name': PROJECT_NAME,
'user_domain_name': USER_DOMAIN_NAME,
'password': PASSWORD,
'username': USERNAME,
'auth_url': AUTH_URL,
}
auth = v3.Password(**keystone_auth)
sess = session.Session(auth=auth)
deckhandclient = client.Client(session=sess)You can also instantiate the client via one of Keystone's supported
auth plugins:
from keystoneauth1.identity import v3
keystone_auth = {
'auth_url': AUTH_URL,
'token': TOKEN,
'project_id': PROJECT_ID,
'project_domain_name': PROJECT_DOMAIN_NAME
}
auth = v3.Token(**keystone_auth)
deckhandclient = client.Client(auth=auth)Which will allow you to authenticate using a pre-existing, project-scoped token.
Alternatively, you can use non-session authentication to instantiate the client, though this approach has been deprecated.
from deckhand.client import client
deckhandclient = client.Client(
username=USERNAME,
password=PASSWORD,
project_name=PROECT_NAME,
project_domain_name=PROJECT_DOMAIN_NAME,
user_domain_name=USER_DOMAIN_NAME,
auth_url=AUTH_URL)Note
The Deckhand client by default expects that the service be registered
under the Keystone service catalog as deckhand. To provide
a different value pass service_type=SERVICE_TYPE to the
Client constructor.
After you have instantiated an instance of the Deckhand client, you can invoke the client managers' functionality:
# Generate a sample document.
payload = """
---
schema: deckhand/Certificate/v1
metadata:
schema: metadata/Document/v1
name: application-api
storagePolicy: cleartext
data: |-
-----BEGIN CERTIFICATE-----
MIIDYDCCAkigAwIBAgIUKG41PW4VtiphzASAMY4/3hL8OtAwDQYJKoZIhvcNAQEL
...snip...
P3WT9CfFARnsw2nKjnglQcwKkKLYip0WY2wh3FE7nrQZP6xKNaSRlh6p2pCGwwwH
HkvVwA==
-----END CERTIFICATE-----
"""
# Create a bucket and associate it with the document.
result = client.buckets.update('mop', payload)
>>> result
<Bucket name: mop>
# Convert the response to a dictionary.
>>> result.to_dict()
{'status': {'bucket': 'mop', 'revision': 1},
'schema': 'deckhand/Certificate/v1', 'data': {...} 'id': 1,
'metadata': {'layeringDefinition': {'abstract': False},
'storagePolicy': 'cleartext', 'name': 'application-api',
'schema': 'metadata/Document/v1'}}
# Show the revision that was created.
revision = client.revisions.get(1)
>>> revision.to_dict()
{'status': 'success', 'tags': {},
'url': 'https://deckhand/api/v1.0/revisions/1',
'buckets': ['mop'], 'validationPolicies': [], 'id': 1,
'createdAt': '2017-12-09T00:15:04.309071'}
# List all revisions.
revisions = client.revisions.list()
>>> revisions.to_dict()
{'count': 1, 'results': [{'buckets': ['mop'], 'id': 1,
'createdAt': '2017-12-09T00:29:34.031460', 'tags': []}]}
# List raw documents for the created revision.
raw_documents = client.revisions.documents(1, rendered=False)
>>> [r.to_dict() for r in raw_documents]
[{'status': {'bucket': 'foo', 'revision': 1},
'schema': 'deckhand/Certificate/v1', 'data': {...}, 'id': 1,
'metadata': {'layeringDefinition': {'abstract': False},
'storagePolicy': 'cleartext', 'name': 'application-api',
'schema': 'metadata/Document/v1'}}]Client Reference
For more information about how to use the Deckhand client, refer to the following documentation:
deckhand.client.client.SessionClient
deckhand.client.client.Client
Manager Reference
For more information about how to use the client managers, refer to the following documentation:
deckhand.client.buckets.Bucket
deckhand.client.buckets.BucketManager
deckhand.client.revisions.Revision
deckhand.client.revisions.RevisionManager
deckhand.client.tags.RevisionTag
deckhand.client.tags.RevisionTagManager
deckhand.client.validations.Validation
deckhand.client.validations.ValidationManager