Introduction

Welcome to the redstone documentation.

Installation

The redstone package is available for install from PyPA with pip:

$ pip install -U redstone

Modules

redstone — Redstone Package

The redstone module is used to interact with various IBM Cloud services.

Basic usage involves getting a Session object, which can be used to build a client for interacting with a specific service.

For example, to interact with Resource Controller, we can use the default session to get a client to talk to Resource Controller:

>>> import redstone
>>> session = redstone.get_default_session()
>>> rc = session.service("ResourceController")

The service() function at the top level can be used as a shortcut for accessing the default session to build clients. This is equivalent to the above:

>>> import redstone
>>> rc = redstone.service("ResourceController")

The default session is constructed lazily on first access and looks for the environment variable IBMCLOUD_API_KEY to use as a credential for interacting with services.

The default session can be overriden or created manually if desired. Any clients created using the default session will then use that session instead.

>>> import redstone
>>> redstone.DEFAULT_SESSION = redstone.Session(iam_api_key="...")
>>> rc = redstone.service("ResourceController")

Members

redstone.DEFAULT_SESSION = None

Holds the current default Session or None if no session has been built yet.

class redstone.Session(region=None, iam_api_key=None)

Session objects are used to create clients used to interact with various services. They hold region endpoint information and a credential object that is used by the clients for authentication. It’s main purpose for sharing and caching credentials for use between multiple clients/services.

A Session can be created manually, but there is also a default session that can be accessed by using the get_default_session() function.

service(service_name, **kwargs)

redstone.get_default_session() → redstone.Session

Returns the current default session for building clients objects.

redstone.service(service_name, **kwargs)

Create and return a new client using the DEFAULT_SESSION.

redstone.auth — IBM Cloud IAM Authentication

This module holds functionality for authenticating with IBM Cloud services, which mainly involves getting a token from IAM and using that token while making requests to the various other services.

Most users will want to use the high level TokenManager which provides caching and automatic refresh for tokens.

There is also a low level auth() function that can be used to request a new token from IAM as needed.

Members

class redstone.auth.TokenManager(api_key, iam_endpoint=None)

TokenManager objects are a wrapper around an API key credential, which is used to request tokens when they are needed.

A TokenManager object caches tokens to minimize requests to IAM, and also will take care of requesting new tokens when the current cached one is expired.

Example usage:

tokman = TokenManager(api_key="my-cloud-api-key")

# get_token() will return a cached version or request one if needed
iam_token = tokman.get_token()

get_token() → str

Retrieve a valid, unexpired token from IAM if needed, or return a cached, unexpired token.

is_refresh_token_expired()

Use to check if the cached IAM Refresh token needs to be refreshed.

The Refresh token is a different token than the IAM token used to interact with services. A Refresh token is a longer lasting token that can be used instead of an API key or password credential to request a new IAM token. It is useful for some specific cases, where the API key or password needs to be dropped and the Refresh token can be used instead to generate IAM tokens.

Returns

bool, True if the Refresh token needs to be refreshed, False otherwise

is_token_expired()

Use to check if the cached IAM token needs to be refreshed.

Returns

bool, True if the token needs to be refreshed, False otherwise

redstone.auth.auth(username=None, password=None, apikey=None, refresh_token=None, iam_endpoint=None)

Makes a authentication request to the IAM API to retrieve an IAM token and IAM Refresh token.

Parameters

• username – Username

• password – Password

• apikey – IBMCloud/Bluemix API Key

• refresh_token – IBM IAM Refresh Token, if specified the refresh token is used to authenticate, instead of the API key

• iam_endpoint – base URL that can be specified to override the default IAM endpoint, if one, for example, wanted to test against their own IAM or an internal server

Returns

Response

redstone.auth.find_space_and_org(bearer_token, org_name, space_name)

redstone.auth.get_orgs(bearer_token)

redstone.auth.get_spaces(bearer_token, spaces_path)

redstone.auth.inspect_token(token)

redstone.auth.main()

redstone.client — Redstone Service Clients

This module holds the service specific client classes, as well as the BaseClient class that they extend from for shared business function.

If you wish to add or extend functionality to a client or service, this is where the concrete classes and logic are for those purposes.

Members

class redstone.client.BaseClient(region=None, service_instance_id=None, iam_api_key=None, verify=True, endpoint_url=None, credentials=None)

class redstone.client.CIS(*args, **kwargs)

endpoint_for_region(region)

get_pool(pool_id)

names = ['cis']

pools()

update_pool(pool)

class redstone.client.CISAuth(credentials)

class redstone.client.IKS(*args, **kwargs)

endpoint_for_region(region)

get_cluster_config(cluster)

Retrieve a KubeConfig that can be used with kubectl to interact with the given IKS cluster.

Returns

base64 encoded file data; can be decode and written to file, or used with the python kubernetes client to interact in the same process

get_clusters() → List[Dict]

List the current IKS clusters in a specific region.

Returns

A list of dict objects representing the cluster metadata.

get_kube_versions()

get_workers(cluster)

List the workers in an IKS cluster.

names = ['iks']

update_master(cluster, version)

Initate an update on the master nodes of a cluster.

update_worker(cluster, worker)

Initiate an update on a worker node.

The worker node will update to the latest revision that matches the master/API server version. i.e. If the master is at 1.16.x, the worker will update to the latest 1.16.x series.

class redstone.client.KeyProtect(*args, **kwargs)

API Docs: https://cloud.ibm.com/apidocs/key-protect

exception KeyProtectError

static wrap(http_error)

create(name, payload=None, raw_payload=None, root=False)

delete(key_id)

endpoint_for_region(region)

get(key_id)

keys()

names = ['kms']

rotate(key_id, payload=None)

unwrap(key_id, ciphertext, aad=None)

wrap(key_id, plaintext, aad=None)

class redstone.client.ResourceController(*args, **kwargs)

Client class for interacting with the Resource Controller service, which is used for managing service instances within the cloud account.

API Docs:

• https://console.bluemix.net/apidocs/resource-manager

• https://console.bluemix.net/apidocs/resource-controller

KEYPROTECT_PLAN_ID = 'eedd3585-90c6-4c8f-be3d-062069e99fc3'

create_instance(name, plan_id, region=None, resource_group=None)

Create/provision a service instance.

Returns

tuple of (service_GUID, service_CRN) if successful

Raises

Exception if there is an error –

delete_instance(instance_crn)

Delete/deprovision a service instance identified by the given CRN or UUID.

endpoint_for_region(region)

get_default_resource_group()

get_instance(instance_id)

list_instances()

Retrieve a list of all the service and resource instances in the current account.

Note this will return an iterator that will handle the underlying pagination of large sets of instances returned.

Returns

a generator type that iterates over the collection of instances returned from the API request

names = ['rc']

resource_groups()

class redstone.client.TokenAuth(credentials)

redstone.crypto — Encrypting/Decrypting with KeyProtect

Members

redstone.crypto.decrypt(source: bytes, session: Optional[redstone.Session] = None) → Tuple[bytes, redstone.crypto.MessageHeader]

Decrypt data previously encrypted with the encrypt function.

redstone.crypto.encrypt(source: bytes, key_crns: List[str], aad: Optional[str] = None, session: Optional[redstone.Session] = None) → Tuple[bytes, redstone.crypto.MessageHeader]

Encrypt byte data using a given set of keys from KeyProtect.

Indices and tables

• Index

• Module Index

• Search Page