decapodlib API

decapodlib is a library to work with Decapod API. Also, it provides user with a bunch of additional convenient utilities.

Usage example

API

decapodlib Library to work with Decapod API.
decapodlib.client This module contains implementation of RPC client for Decapod API.
decapodlib.auth This module contains implementation of authorization for Decapod API.
decapodlib.exceptions Exceptions raised in decapodlib.
decapodlib.cloud_config This module has routines to help user to build user-data configs for cloud-init.

decapodlib

Library to work with Decapod API.

Top level module provides a list of shortcuts to use with Decapod. Right now, it has only current decapodlib.Client implementation as decapodlib.Client.

decapodlib.Client[source]

An actual version of JSON client for Decapod.

alias of V1Client

decapodlib.client

This module contains implementation of RPC client for Decapod API.

Decapod client Client is a simple RPC client and thin wrapper for the requests library which allows end user to work with remote API without worrying about connections and endpoints.

RPC client itself manages authorization (therefore you have to supply it with user/password pair on initialization) so there is no need in explicit session objects but if you do not like that way, you may always relogin explicitly.

Usage example:

client = Client(url="http://localhost", login="root", password="root")

This will initialize new client. Initialization does not imply immediate login, login would be occured thread-safely on the first real method execution.

users = client.get_users()

This will return end user a list with active users in Decapod.

[
    {
        "data": {
            "email": "noreply@example.com",
            "full_name": "Root User",
            "login": "root",
            "role_id": "37fb532f-2620-4e0d-80e6-b68ed6988a6d"
        },
        "id": "6567c2ab-54cc-40b7-a811-6147a3f3ea83",
        "initiator_id": null,
        "model": "user",
        "time_deleted": 0,
        "time_updated": 1478865388,
        "version": 1
    }
]

Incoming JSON will be parsed. If it is not possible, decapodlib.exceptions.DecapodError will be raised.

class decapodlib.client.Client(url, login, password, timeout=None, verify=True, certificate_file=None)[source]

A base RPC client model.

Parameters:
  • url (str) – URL of Decapod API (without version prefix like /v1).
  • login (str) – Login of user in Decapod.
  • password (str) – Password of user in Decapod.
  • timeout (int or None) – Timeout for remote requests. If None is set, default socket timeout (e.g which is set by socket.setdefaulttimeout()) will be used.
  • verify (bool) – If remote URL implies SSL, then using this option client will check SSL certificate for validity.
  • certificate_file (str or None) – If SSL works with client certificate, this option sets the path to such certificate. If None is set, then it implies that no client certificate should be used.
AUTH_CLASS = None

Base class for authenication.

class decapodlib.client.V1Client(url, login, password, timeout=None, verify=True, certificate_file=None)[source]

Implemetation of decapodlib.client.Client which works with API version 1.

Please check parameters for decapodlib.client.Client class.

Note

All **kwargs keyword arguments here are the same as requests.Session.request() takes.

AUTH_CLASS

alias of V1Auth

cancel_execution(execution_id, **kwargs)[source]

This method cancels existing execution.

This method does DELETE /v1/execution/ endpoint call.

Parameters:

execution_id (str) – UUID4 (RFC 4122) in string form of execution’s ID.
Returns:

Canceled execution model.
Return type:

dict
Raises:
create_cluster(name, **kwargs)[source]

This method creates new cluster model.

This method does POST /v1/cluster/ endpoint call.

Parameters:

name (str) – Name of the cluster.
Returns:

New cluster model.
Return type:

dict
Raises:
create_execution(playbook_configuration_id, playbook_configuration_version, **kwargs)[source]

This method creates new execution model.

This method does POST /v1/execution/ endpoint call.

Parameters:
  • playbook_configuration_id (str) – UUID4 (RFC 4122) in string form of playbook configuration’s ID.
  • playbook_configuration_version (int) – Version of playbook configuration model.
Returns:

New execution model.
Return type:

dict
Raises:
create_playbook_configuration(name, cluster_id, playbook_id, server_ids, hints=None, **kwargs)[source]

This method creates new playbook configuration model.

This method does POST /v1/playbook_configuration/ endpoint call.

Hints for playbook configuration are the list of optional parameters for creating playbook configuration. It has to be the list key/value parameters obtained from decapodlib.client.V1Client.get_playbooks().

[
    {
        "id": "dmcrypt",
        "value": true
    }
]
Parameters:
  • name (str) – Name of the playbook configuration.
  • cluster_id (str) – UUID4 (RFC 4122) in string form of cluster’s ID
  • playbook_id (str) – ID of playbook to use.
  • server_ids ([str, ...]) – List of server UUID4 (RFC 4122) in string form of server model IDs.
  • hints (list) – List of hints for playbook configuration.
Returns:

New cluster model.
Return type:

dict
Raises:
create_role(name, permissions, **kwargs)[source]

This method creates new role model.

This method does POST /v1/role endpoint call.

This method accepts parameter permissions. This is a list of permissions like that:

[
    {
        "name": "playbook",
        "permissions": [
            "add_osd",
            "cluster_deploy",
            "hello_world",
            "purge_cluster",
            "remove_osd"
        ]
    },
    {
        "name": "api",
        "permissions": [
            "create_cluster",
            "create_execution",
            "create_playbook_configuration",
            "create_role",
            "create_server",
            "create_user",
            "delete_cluster",
            "delete_execution",
            "delete_playbook_configuration",
            "delete_role",
            "delete_server",
            "delete_user",
            "edit_cluster",
            "edit_playbook_configuration",
            "edit_role",
            "edit_server",
            "edit_user",
            "view_cluster",
            "view_cluster_versions",
            "view_execution",
            "view_execution_steps",
            "view_execution_version",
            "view_playbook_configuration",
            "view_playbook_configuration_version",
            "view_role",
            "view_role_versions",
            "view_server",
            "view_server_versions",
            "view_user",
            "view_user_versions"
        ]
    }
]

So, each element is a dict with name and permissions field.

Parameters:
  • name (str) – Name of the role.
  • permissions (list) – A list of permissions. Please check example above.
Returns:

New role model.
Return type:

dict
Raises:
create_server(server_id, host, username, **kwargs)[source]

This method creates new server model.

This method does POST /v1/server/ endpoint call.

Warning

You should avoid to use this method manually. Servers must be discovered using cloud-init based discovery mechanism.

Parameters:
  • server_id (str) – Unique ID of server.
  • host (str) – Hostname of the server (should be accessible by Decapod). It is better to have FQDN here.
  • username (str) – The name of the user for Ansible on this server. Decapod will use Ansible which SSH to machine with hostname given in host parameter and that username.
Returns:

New server model.
Return type:

dict
Raises:
create_user(login, email, full_name='', role_id=None, **kwargs)[source]

This method creates new user model.

This method does POST /v1/user/ endpoint call.

Parameters:

name (str) – Name of the user.
Returns:

New user model.
Return type:

dict
Raises:
delete_cluster(cluster_id, **kwargs)[source]

This methods deletes cluster model.

Please be noticed that no real delete is performed, cluster model is marked as deleted (time_deleted > 0) and model will be skipped from listing, updates are forbidden.

This method does DELETE /v1/cluster/ endpoint call.

Parameters:

cluster_id (str) – UUID4 (RFC 4122) in string form of cluster’s ID
Returns:

Deleted cluster model.
Return type:

dict
Raises:
delete_playbook_configuration(playbook_configuration_id, **kwargs)[source]

This method deletes playbook configuration model.

Please be noticed that no real delete is performed, playbook configuration model is marked as deleted (time_deleted > 0) and model will be skipped from listing, updates are forbidden.

This method does DELETE /v1/playbook_configuration/ endpoint call.

Parameters:

playbook_configuration_id (str) – UUID4 (RFC 4122) in string form of playbook configuration’s ID
Returns:

Deleted playbook configuration model.
Return type:

dict
Raises:
delete_role(role_id, **kwargs)[source]

This methods deletes role model.

Please be noticed that no real delete is performed, role model is marked as deleted (time_deleted > 0) and model will be skipped from listing, updates are forbidden.

This method does DELETE /v1/role/ endpoint call.

Parameters:

role_id (str) – UUID4 (RFC 4122) in string form of role’s ID
Returns:

Deleted role model.
Return type:

dict
Raises:
delete_server(server_id, **kwargs)[source]

This methods deletes server model.

Please be noticed that no real delete is performed, server model is marked as deleted (time_deleted > 0) and model will be skipped from listing, updates are forbidden.

This method does DELETE /v1/server/ endpoint call.

Parameters:

server_id (str) – UUID4 (RFC 4122) in string form of server’s ID
Returns:

Deleted server model.
Return type:

dict
Raises:
delete_user(user_id, **kwargs)[source]

This methods deletes user model.

Please be noticed that no real delete is performed, user model is marked as deleted (time_deleted > 0) and model will be skipped from listing, updates are forbidden.

This method does DELETE /v1/user/ endpoint call.

Parameters:

user_id (str) – UUID4 (RFC 4122) in string form of user’s ID
Returns:

Deleted user model.
Return type:

dict
Raises:
get_cinder_integration(cluster_id, root='/etc/ceph', **kwargs)[source]

This method fetches data for integration with Cinder.

This method does GET /v1/cinder_integration/{cluster_id} endpoint call.

Parameters:
  • cluster_id (str) – UUID4 (RFC 4122) in string form of cluster’s ID
  • root (str) – Root on file system where files should be stored.
Returns:

Integration data
Return type:

dict
Raises:
get_cluster(cluster_id, **kwargs)[source]

This method fetches a single cluster model (latest version) from API.

This method does GET /v1/cluster/{cluster_id} endpoint call.

Parameters:

cluster_id (str) – UUID4 (RFC 4122) in string form of cluster’s ID
Returns:

Cluster model of latest available version
Return type:

dict
Raises:
get_cluster_version(cluster_id, version, **kwargs)[source]

This method fetches a certain version of particular cluster model.

This method does GET /v1/cluster/{cluster_id}/version/{version} endpoint call.

Parameters:
  • cluster_id (str) – UUID4 (RFC 4122) in string form of cluster’s ID
  • version (int) – The number of version to fetch.
Returns:

Cluster model of certain version.
Return type:

dict
Raises:
get_cluster_versions(cluster_id, query_params, **kwargs)[source]

This method fetches a list of all versions for a certain cluster model.

This method does GET /v1/cluster/{cluster_id}/version/ endpoint call.

Parameters:

cluster_id (str) – UUID4 (RFC 4122) in string form of cluster’s ID
Returns:

List of cluster versions for cluster with ID cluster_id.
Return type:

list
Raises:
get_clusters(query_params, **kwargs)[source]

This method fetches a list of latest cluster models from API.

By default, only active clusters will be listed.

This method does GET /v1/cluster endpoint call.

Returns:

List of latest cluster models.
Return type:

list
Raises:
get_execution(execution_id, **kwargs)[source]

This method fetches a single execution model (latest version) from API.

This method does GET /v1/execution/{execution_id} endpoint call.

Parameters:

execution_id (str) – UUID4 (RFC 4122) in string form of execution’s ID
Returns:

Execution model of latest available version
Return type:

dict
Raises:
get_execution_log(execution_id, **kwargs)[source]

This method fetches text execution log for a certain execution.

Execution log is a raw Ansible execution log, that one, which is generated by ansible-playbook program.

This method does GET /v1/execution/{execution_id}/log endpoint call.

Parameters:

execution_id (str) – UUID4 (RFC 4122) in string form of execution’s ID.
Returns:

List of execution steps.
Return type:

list
Raises:
get_execution_steps(execution_id, query_params, **kwargs)[source]

This method fetches step models of the execution.

This method does GET /v1/execution/{execution_id}/steps endpoint call.

Parameters:

execution_id (str) – UUID4 (RFC 4122) in string form of execution’s ID.
Returns:

List of execution steps.
Return type:

list
Raises:
get_execution_version(execution_id, version, **kwargs)[source]

This method fetches a certain version of particular execution model.

This method does GET /v1/execution/{execution_id}/version/{version} endpoint call.

Parameters:
  • execution_id (str) – UUID4 (RFC 4122) in string form of execution’s ID
  • version (int) – The number of version to fetch.
Returns:

Execution model of certain version.
Return type:

dict
Raises:
get_execution_versions(execution_id, query_params, **kwargs)[source]

This method fetches a list of all versions for a certain execution model.

This method does GET /v1/execution/{execution_id}/version/ endpoint call.

Parameters:

execution_id (str) – UUID4 (RFC 4122) in string form of execution’s ID
Returns:

List of execution versions for execution with ID execution_id.
Return type:

list
Raises:
get_executions(query_params, **kwargs)[source]

This method fetches a list of latest execution models from API.

This method does GET /v1/execution endpoint call.

Returns:

List of latest execution models.
Return type:

list
Raises:
get_info(**kwargs)[source]

This method fetches basic data from Decapod API.

It makes no sense to use this method for anything, it is just a healthcheck that service actually works.

Example of result:

{
    "time": {
        "local": "2016-11-16T12:46:55.868153",
        "unix": 1479300415,
        "utc": "2016-11-16T12:46:55.868220"
    },
    "version": "0.1.0"
}

Important

This method is basically the only one you may access being not logged in.

Returns:

Something
Return type:

dict
Raises:
get_permissions(**kwargs)[source]

This method lists exisiting permissions in system. Not those, which available for current user, but overall ones. This is mostly required if you compose new role.

This method does GET /v1/permission endpoint call.

Example of result:

{
    "items": [
        {
            "name": "api",
            "permissions": [
                "create_cluster",
                "create_execution",
                "create_playbook_configuration",
                "create_role",
                "create_server",
                "create_user",
                "delete_cluster",
                "delete_execution",
                "delete_playbook_configuration",
                "delete_role",
                "delete_server",
                "delete_user",
                "edit_cluster",
                "edit_playbook_configuration",
                "edit_role",
                "edit_server",
                "edit_user",
                "view_cluster",
                "view_cluster_versions",
                "view_execution",
                "view_execution_steps",
                "view_execution_version",
                "view_playbook_configuration",
                "view_playbook_configuration_version",
                "view_role",
                "view_role_versions",
                "view_server",
                "view_server_versions",
                "view_user",
                "view_user_versions"
            ]
        },
        {
            "name": "playbook",
            "permissions": [
                "add_osd",
                "cluster_deploy",
                "hello_world",
                "purge_cluster",
                "remove_osd"
            ]
        }
    ]
}

Note

As you can see, there are 2 types of permissions in Decapod:

  1. api
  2. playbook

api permissions are responsible for accessing API endpoints. If user wants to access some API endpoint, he has to have appropriate permission in his role. Some endpoints require several permissions and rule of thumb here is common sense: is user wants to update role, he has to have a permission to view it.

playbook permissions are slightly different beasts. Each permission allows user to execute a certain playbook.

Returns:

A list of premissions like those mentioned above
Return type:

list
Raises:
get_playbook_configuration(playbook_configuration_id, **kwargs)[source]

This method fetches a single playbook configuration model (latest version) from API.

This method does GET /v1/playbook_configuration/{playbook_configuration_id} endpoint call.

Parameters:

playbook_configuration_id (str) – UUID4 (RFC 4122) in string form of playbook configuration’s ID.
Returns:

Playbook configuration model of latest available version.
Return type:

dict
Raises:
get_playbook_configuration_version(playbook_configuration_id, version, **kwargs)[source]

This method fetches a certain version of particular playbook configuration model.

This method does GET /v1/playbook_configuration/{playbook_configuration_id}/version/{version} endpoint call.

Parameters:
  • playbook_configuration_id (str) – UUID4 (RFC 4122) in string form of playbook configuration’s ID
  • version (int) – The number of version to fetch.
Returns:

Playbook configuration model of certain version.
Return type:

dict
Raises:
get_playbook_configuration_versions(playbook_configuration_id, query_params, **kwargs)[source]

This method fetches a list of all versions for a certain playbook configuration model.

This method does GET /v1/playbook_configuration/{playbook_configuration_id}/version/ endpoint call.

Parameters:

playbook_configuration_id (str) – UUID4 (RFC 4122) in string form of playbook configuration’s ID.
Returns:

List of playbook configuration versions for playbook configuration with ID playbook_configuration_id.
Return type:

list
Raises:
get_playbook_configurations(query_params, **kwargs)[source]

This method fetches a list of latest playbook configuration models from API.

By default, only active playbook configurations will be listed.

This method does GET /v1/playbook_configuration endpoint call.

Returns:

List of latest playbook configuration models.
Return type:

list
Raises:
get_playbooks(**kwargs)[source]

This method returns a list of playbooks avaialble for execution.

This method does GET /v1/playbook endpoint call.

Example of result:

{
    "items": [
        {
            "description": "Adding new OSD to the cluster.",
            "id": "add_osd",
            "name": "Add OSD to Ceph cluster",
            "required_server_list": true,
            "hints": []
        },
        {
            "description": "Ceph cluster deployment playbook.",
            "id": "cluster_deploy",
            "name": "Deploy Ceph cluster",
            "required_server_list": true,
            "hints": [
                {
                    "description": "Setup OSDs with dmcrypt",
                    "id": "dmcrypt",
                    "type": "boolean",
                    "values": []
                }
            ]
        },
        {
            "description": "Example plugin for playbook.",
            "id": "hello_world",
            "name": "Hello World",
            "required_server_list": false
            "hints": []
        },
        {
            "description": "Purge whole Ceph cluster.",
            "id": "purge_cluster",
            "name": "Purge cluster",
            "required_server_list": false,
            "hints": []
        },
        {
            "description": "Remove OSD host from cluster.",
            "id": "remove_osd",
            "name": "Remove OSD host from Ceph cluster",
            "required_server_list": true,
            "hints": []
        }
    ]
}

Note

Please remember that playbook parameter in POST /v1/playbook_configuration is id field here.

Returns:

A list of playbook data.
Return type:

list
Raises:
get_role(role_id, **kwargs)[source]

This method fetches a single role model (latest version) from API.

This method does GET /v1/role/{role_id} endpoint call.

Parameters:

role_id (str) – UUID4 (RFC 4122) in string form of role’s ID
Returns:

Role model of latest available version
Return type:

dict
Raises:
get_role_self(**kwargs)[source]

This methods requests model of role of current user.

This method does GET /v1/role/self/ endpoint call.

Returns:

Role model of current user.
Return type:

dict
Raises:
get_role_version(role_id, version, **kwargs)[source]

This method fetches a certain version of particular role model.

This method does GET /v1/role/{role_id}/version/{version} endpoint call.

Parameters:
  • role_id (str) – UUID4 (RFC 4122) in string form of role’s ID
  • version (int) – The number of version to fetch.
Returns:

Role model of certain version.
Return type:

dict
Raises:
get_role_versions(role_id, query_params, **kwargs)[source]

This method fetches a list of all versions for a certain role model.

This method does GET /v1/role/{role_id}/version/ endpoint call.

Parameters:

role_id (str) – UUID4 (RFC 4122) in string form of role’s ID
Returns:

List of role versions for role with ID role_id.
Return type:

list
Raises:
get_roles(query_params, **kwargs)[source]

This method fetches a list of latest role models from API.

By default, only active roles will be listed.

This method does GET /v1/role endpoint call.

Returns:

List of latest role models.
Return type:

list
Raises:
get_server(server_id, **kwargs)[source]

This method fetches a single server model (latest version) from API.

This method does GET /v1/server/{server_id} endpoint call.

Parameters:

server_id (str) – UUID4 (RFC 4122) in string form of server’s ID
Returns:

Server model of latest available version
Return type:

dict
Raises:
get_server_version(server_id, version, **kwargs)[source]

This method fetches a certain version of particular server model.

This method does GET /v1/server/{server_id}/version/{version} endpoint call.

Parameters:
  • server_id (str) – UUID4 (RFC 4122) in string form of server’s ID
  • version (int) – The number of version to fetch.
Returns:

Server model of certain version.
Return type:

dict
Raises:
get_server_versions(server_id, query_params, **kwargs)[source]

This method fetches a list of all versions for a certain server model.

This method does GET /v1/server/{server_id}/version/ endpoint call.

Parameters:

server_id (str) – UUID4 (RFC 4122) in string form of server’s ID
Returns:

List of server versions for server with ID server_id.
Return type:

list
Raises:
get_servers(query_params, **kwargs)[source]

This method fetches a list of latest server models from API.

By default, only active servers will be listed.

This method does GET /v1/server endpoint call.

Returns:

List of latest server models.
Return type:

list
Raises:
get_user(user_id, **kwargs)[source]

This method fetches a single user model (latest version) from API.

This method does GET /v1/user/{user_id} endpoint call.

Parameters:

user_id (str) – UUID4 (RFC 4122) in string form of user’s ID
Returns:

User model of latest available version
Return type:

dict
Raises:
get_user_self(**kwargs)[source]

This methods requests model of current user.

This method does GET /v1/user/self/ endpoint call.

Returns:

User model of current user.
Return type:

dict
Raises:
get_user_version(user_id, version, **kwargs)[source]

This method fetches a certain version of particular user model.

This method does GET /v1/user/{user_id}/version/{version} endpoint call.

Parameters:
  • user_id (str) – UUID4 (RFC 4122) in string form of user’s ID
  • version (int) – The number of version to fetch.
Returns:

User model of certain version.
Return type:

dict
Raises:
get_user_versions(user_id, query_params, **kwargs)[source]

This method fetches a list of all versions for a certain user model.

This method does GET /v1/user/{user_id}/version/ endpoint call.

Parameters:

user_id (str) – UUID4 (RFC 4122) in string form of user’s ID
Returns:

List of user versions for user with ID user_id.
Return type:

list
Raises:
get_users(query_params, **kwargs)[source]

This method fetches a list of latest user models from API.

By default, only active users will be listed.

This method does GET /v1/user endpoint call.

Returns:

List of latest user models.
Return type:

list
Raises:
login(**kwargs)[source]

This methods logins users into API.

Basically, you do not need to execute this method by yourself, client will implicitly execute it when needed.

This method does POST /v1/auth endpoint call.

Returns:

Model of the Token.
Return type:

dict
Raises:
logout(**kwargs)[source]

This method logouts users from API (after that security token will be deleted).

Basically, you do not need to execute this method by yourself, client will implicitly execute it when needed.

This method does DELETE /v1/auth endpoint call.

Raises:
peek_password_reset(reset_token, **kwargs)[source]

This method checks if password reset with given token is still requested. It does not consume token, it just checks if it is possible or not.

Example of result:

{
    "message": "Password reset was requested."
}
Parameters:

reset_token (str) – Password reset token from email.
Returns:

A message that password reset was requested.
Return type:

dict
Raises:
put_server(model_data, **kwargs)[source]

This methods updates server model.

Please be noticed that no real update is performed, just a new version of the same server is created.

This method does PUT /v1/server/ endpoint call.

Parameters:

model_data (dict) – Updated model of the server.
Returns:

Updated server model.
Return type:

dict
Raises:
request_password_reset(login, **kwargs)[source]

This method requests password resetting for a user.

Please be noticed that no real password resetting is occured, it just requesting password reset. After that, user will receive secret link on his email. If user will proceed that link, he can actually reset her password.

This method does POST /v1/password_reset endpoint call.

Example of result:

{
    "message": "Password reset was requested."
}
Parameters:

login (str) – Login of user who is required to reset password.
Returns:

A message that password reset was requested.
Return type:

dict
Raises:
reset_password(reset_token, new_password, **kwargs)[source]

This method does actual password resetting.

Example of result:

{
    "message": "Password has been reset."
}
Parameters:
  • reset_token (str) – Password reset token from email.
  • new_password (str) – New password for user.
Returns:

A message that password was reset.
Return type:

dict
Raises:
update_cluster(model_data, **kwargs)[source]

This methods updates cluster model.

Please be noticed that no real update is performed, just a new version of the same cluster is created.

This method does PUT /v1/cluster/ endpoint call.

Parameters:

model_data (dict) – Updated model of the cluster.
Returns:

Updated cluster model.
Return type:

dict
Raises:
update_playbook_configuration(model_data, **kwargs)[source]

This method updates playbook configuration model.

Please be noticed that no real update is performed, just a new version of the same playbook configuration is created.

This method does PUT /v1/playbook_configuration/ endpoint call.

Parameters:

model_data (dict) – Updated model of the playbook configuration.
Returns:

Updated playbook configuration model.
Return type:

dict
Raises:
update_role(model_data, **kwargs)[source]

This methods updates role model.

Please be noticed that no real update is performed, just a new version of the same role is created.

This method does PUT /v1/role/ endpoint call.

Parameters:

model_data (dict) – Updated model of the role.
Returns:

Updated role model.
Return type:

dict
Raises:
update_user(model_data, **kwargs)[source]

This methods updates user model.

Please be noticed that no real update is performed, just a new version of the same user is created.

This method does PUT /v1/user/ endpoint call.

Parameters:

model_data (dict) – Updated model of the user.
Returns:

Updated user model.
Return type:

dict
Raises:

decapodlib.auth

This module contains implementation of authorization for Decapod API.

Decapod client uses requests library to access its API so authentication is done using requests’s classes. Please check official guide for details.

class decapodlib.auth.V1Auth(client)[source]

Request authentication provider for Decapod API V1.

The idea of that provider is really simple: it stores authentication token from Decapod API and injects it into proper header on every request. If no token is defined, it will authorize for you transparently using decapodlib.client.Client login method.

AUTH_URL = '/v1/auth/'

URL of authentication.

revoke_token()[source]

Resets information about known token.

decapodlib.auth.no_auth(request)[source]

Trivial authenticator which does no authentication for a request.

decapodlib.exceptions

Exceptions raised in decapodlib.

Please be noticed, that all exception raised from decapodlib will be wrapped in decapodlib.exceptions.DecapodError or its subclasses.

exception decapodlib.exceptions.DecapodAPIError(response)[source]

Common error in API.

Parameters:response (requests.Response) – Original response which is a base of that exception.
json

Return this error as parsed JSON.

Example of result:

{
    "code": 403,
    "error": "Forbidden",
    "description": "Access was forbidden!"
}
exception decapodlib.exceptions.DecapodError(exc)[source]

Basic error raised in decapodlib.

Parameters:exc (Exception) – Original exception, wrapped in this class.

Original exception is stored in exception field.

decapodlib.cloud_config

This module has routines to help user to build user-data configs for cloud-init.

Decapod uses cloud-init to implement server discovery. On each server boot user-data will be executed (you may consider cloud-init as rc.local on steroids).

Basically, it creates several files on the host system and put their execution into host rc.local.

decapodlib.cloud_config.generate_cloud_config(url, server_discovery_token, public_key, username, timeout=20, no_discovery=False)[source]

This function generates user-data config (or cloud config) for cloud-init.

Parameters:
  • url (str) – URL of Decapod API. This URL should be accessible from remote machine.
  • server_discovery_token (str) – Server discovery token from Decapod config.
  • public_key (str) – SSH public key of Ansible. This key will be placed in ~username/.ssh/authorized_keys.
  • username (str) – Username of the user, which Ansible will use to access this host.
  • timeout (int) – Timeout of connection to Decapod API.
  • no_discovery (bool) – Generate config with user and packages but no discovery files. It can be used if user wants to add servers manually.
Returns:

Generated user-data in YAML format.
Return type:

str