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)[source]¶
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.
- redstone.get_default_session() Session [source]¶
Returns the current default session for building clients objects.
- redstone.service(service_name, **kwargs)[source]¶
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, use_refresh_token=False)[source]¶
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 [source]¶
Retrieve a valid, unexpired token from IAM if needed, or return a cached, unexpired token.
- is_refresh_token_expired()[source]¶
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
- redstone.auth.auth(username=None, password=None, apikey=None, refresh_token=None, iam_endpoint=None)[source]¶
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.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)[source]¶
- set_pre_send_fn(fn)[source]¶
Sets the provided function as a hook to be called per request, just before the requests are sent.
This allows for modifying any aspects of the requests before they are sent, or for recording/logging/tracing purposes.
The function must handle its own exceptions, and must return a requests.Request object.
If fn resolves to false-y then it will not be called. This can be used to remove any hook currently set, by calling set_pre_send_fn with None type.
Example:
def add_header(req): req.headers["X-Trace-ID"] = "my-tracing-id" return req client.set_pre_send_fn(add_header) # X-Trace-ID will be set for all requests from this client object for i in client.list_instances(): print(i) ...
- class redstone.client.IKS(*args, **kwargs)[source]¶
-
- get_cluster_config(cluster)[source]¶
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] [source]¶
List the current IKS clusters in a specific region.
- Returns
A list of dict objects representing the cluster metadata.
- names = ['iks']¶
- class redstone.client.KeyProtect(*args, **kwargs)[source]¶
API Docs: https://cloud.ibm.com/apidocs/key-protect
- cancel_dual_auth_delete(key_id: str)[source]¶
Remove an authorization for a key with a dual authorization policy
API Docs: https://cloud.ibm.com/apidocs/key-protect#unsetkeyfordeletion
- create(name, payload=None, raw_payload=None, root=False, alias_list=None)¶
- create_import_token(expiration: Optional[int] = None, max_allowed_retrievals: Optional[int] = None)[source]¶
Create an import token that can be used to import encrypted material as root keys.
- expiration: The time in seconds from the creation of a import token that determines how long it remains valid.
The minimum value is 300 seconds (5 minutes), and the maximum value is 86400 (24 hours). The default value is 600 (10 minutes).
- max_allowed_retrievals: The number of times that an import token can be retrieved within its expiration time
before it is no longer accessible. The default value is 1. The maximum value is 500.
API Docs: https://cloud.ibm.com/apidocs/key-protect#postimporttoken
- create_key_alias(key_id: str, alias: str)[source]¶
Creates an alias name for a key. An alias is a user defined string that can be used in place of a normal UUID Key ID
API Docs: https://cloud.ibm.com/apidocs/key-protect#createkeyalias
- create_key_ring(key_ring_id: str)[source]¶
Create a key ring in the instance with the specified name.
API Docs: https://cloud.ibm.com/apidocs/key-protect#createkeyring
- delete(key_id)¶
- delete_key_alias(key_id: str, alias: str)[source]¶
Deletes an alias name associated with a key
API Docs: https://cloud.ibm.com/apidocs/key-protect#deletekeyalias
- delete_key_ring(key_ring_id: str)[source]¶
Deletes a key ring from the associated instance
API Docs: https://cloud.ibm.com/apidocs/key-protect#deletekeyring
- disable_key(key_id: str)[source]¶
Disable a key.
The key will not be deleted, but it will not be active and key operations cannot be performed on a disabled key.
API Docs: https://cloud.ibm.com/apidocs/key-protect#disablekey
- enable_key(key_id: str)[source]¶
Enable a key.
Only disabled keys can be enabled. After calling this action, the key becomes active and key operations can be performed on it.
Note: This does not recover Deleted keys.
API Docs: https://cloud.ibm.com/apidocs/key-protect#enablekey
- get(key_id_or_alias)¶
- get_import_token()[source]¶
Retrieves an import token associated with the current service instance. Token must be previously created by a create import token call.
API Docs: https://cloud.ibm.com/apidocs/key-protect#getimporttoken
- get_instance_policies()[source]¶
Retrieves a list of policies that are associated with a specified service instance
- get_key_policies(key_id: str)[source]¶
Retrieves a list of policies that are associated with a specified key
API Docs: https://cloud.ibm.com/apidocs/key-protect#getpolicy
- get_key_rings()[source]¶
Get all key rings associated with specified instance
API Docs: https://cloud.ibm.com/apidocs/key-protect#listkeyrings
- get_registrations(key_id: Optional[str] = None, crn: Optional[str] = None)[source]¶
Retrieve a list of registrations
If key_id is None (the default) all registrations for the instance are returned, otherwise only the registrations associated with a specified root key are returned.
crn should be a str type that will be passed as the urlEncodedResourceCRNQuery parameter to the HTTP API. It is used to filter registration on a specific cloud resource. More information can be found in the API docs below.
- initiate_dual_auth_delete(key_id: str)[source]¶
Authorize deletion for a key with a dual authorization policy
API Docs: https://cloud.ibm.com/apidocs/key-protect#setkeyfordeletion
- keys()¶
- names = ['kms']¶
- purge_key(key_id: str)[source]¶
Purge key method shreds all the metadata and registrations associated with a key that has been deleted. The purge operation is allowed to be performed on a key from 4 hours after its deletion
- restore_key(key_id: str)[source]¶
Restore a key.
The RestoreKey method reverts a key’s status from Destroyed to Active. This method cannot be used to restore a key that has been purged.
API Docs: https://cloud.ibm.com/apidocs/key-protect#restorekey
- rotate(key_id, payload=None)¶
- set_instance_allowed_ip_policy(allowed_ip_enable: bool, allowed_ips: List[str])[source]¶
Updates the allowed IP policy for the instance
API Docs: https://cloud.ibm.com/apidocs/key-protect#putinstancepolicy
- set_instance_allowed_network_policy(allowed_network_enable: bool, network_type: str)[source]¶
Updates the allowed network policy for the instance
network_type is a str type, and must be one of “public-and-private” or “private-only”. The default is “public-and-private”, but can be set to “private-only” to disable access to the instance from Internet client addresses. API Docs: https://cloud.ibm.com/apidocs/key-protect#putinstancepolicy
- set_instance_dual_auth_policy(dual_auth_enable: bool)[source]¶
Updates the dual auth delete policy for the instance by passing the enable detail
API Docs: https://cloud.ibm.com/apidocs/key-protect#putinstancepolicy
- set_instance_key_create_import_access_policy(key_create_import_access_enable: bool, create_root_key: bool, create_standard_key: bool, import_root_key: bool, import_standard_key: bool, enforce_token: bool)[source]¶
Updates the key create import access policy details associated with an instance.
‘key_create_import_access_enable’ is boolean type, the instance policy is enabled if it’s set to true
API Docs: https://cloud.ibm.com/apidocs/key-protect#putinstancepolicy
- set_instance_metrics_policy(metrics_enable: bool)[source]¶
Updates the metrics policy details associated with an instance
API Docs: https://cloud.ibm.com/apidocs/key-protect#putinstancepolicy
- set_key_dual_auth_policy(key_id: str, dual_auth_enable: bool)[source]¶
Updates the dual auth delete policy by passing the key ID and enable detail
API Docs: https://cloud.ibm.com/apidocs/key-protect#putpolicy
- set_key_ring(key_id: str, key_ring_id: str, new_key_ring_id: str)[source]¶
Transfers a key associated with one key ring to another key ring
- set_key_rotation_policy(key_id: str, rotation_interval: int)[source]¶
Updates the rotation policy associated with a key by specifying key ID and rotation interval
API Docs: https://cloud.ibm.com/apidocs/key-protect#putpolicy
- sync_associated_resources(key_id: str)[source]¶
Executes the sync request which verifies and updates the resources associated with the key.
API Docs: https://cloud.ibm.com/apidocs/key-protect#syncassociatedresources
- class redstone.client.ResourceController(*args, **kwargs)[source]¶
Client class for interacting with the Resource Controller service, which is used for managing service instances within the cloud account.
- API Docs:
- KEYPROTECT_PLAN_ID = 'eedd3585-90c6-4c8f-be3d-062069e99fc3'¶
- create_instance(name, plan_id, region=None, resource_group=None)[source]¶
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)[source]¶
Delete/deprovision a service instance identified by the given CRN or UUID.
- list_instances()[source]¶
Retrieve a list of all 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']¶
- class redstone.client.Session[source]¶
- prepare_request(request)[source]¶
Constructs a
PreparedRequest
for transmission and returns it. ThePreparedRequest
has settings merged from theRequest
instance and those of theSession
.- Parameters
request –
Request
instance to prepare with this session’s settings.- Return type
requests.PreparedRequest