API

cf_api

class cf_api.CloudController(base_url)

Provides base endpoints for building Cloud Controller requests

Attributes:

uaa (UAA): UAA instance that was used to authenticate. doppler (Doppler): Doppler instance that may be used to access logs. ssh_proxy (SSHProxy): SSH Proxy instance that may be used to access

an app instance shell.

version (int): Cloud Controller API version to be used when making

requests

info (CFInfo): CFInfo instance containing CF service entries for

various internal services (i.e. Cloud Controller, UAA, Doppler, etc.)

app_usage_events(*args)

Convenience function passing the app_usage_events url segment.

Args:

*args: url segments that will be appended after

app_usage_events

Returns:

CloudControllerRequest

apps(*args)

Convenience function passing the apps url segment.

Args:

*args: url segments that will be appended after apps

Returns:

CloudControllerRequest

blobstores(*args)

Convenience function passing the blobstores url segment.

Args:

*args: url segments that will be appended after blobstores

Returns:

CloudControllerRequest

buildpacks(*args)

Convenience function passing the buildpacks url segment.

Args:

*args: url segments that will be appended after buildpacks

Returns:

CloudControllerRequest

events(*args)

Convenience function passing the events url segment.

Args:

*args: url segments that will be appended after events

Returns:

CloudControllerRequest

get_all_resources(req)

Recursively gets all the resources specified by the request. Do not execute req.get() before passing it in. This implementation will call req.get() and continue calling next_url from the response and collect the results until the response has no next_url.

Args:

req (Request): a user prepared request that will be used to execute

and collect all results

Returns:

list[Resource]: collected resources in a single list

new_doppler()

Creates a new, authenticated Doppler instance

Returns:

Doppler

organizations(*args)

Convenience function passing the organizations url segment.

Args:

*args: url segments that will be appended after organizations

Returns:

CloudControllerRequest

private_domains(*args)

Convenience function passing the private_domains url segment.

Args:

*args: url segments that will be appended after private_domains

Returns:

CloudControllerRequest

quota_definitions(*args)

Convenience function passing the quota_definitions url segment.

Args:

*args: url segments that will be appended after

quota_definitions

Returns:

CloudControllerRequest

refresh_tokens(force=False)

This method will refresh the internal access token based on the expiration time encapsulated in the current token.

Args:

force (bool): Default is False. If True, then the tokens will be

refreshed regardless of whether they’ve expired

Returns:

self (CloudController)

request(*urls, **kwargs)

Creates a new CloudControllerRequest object with the API version prepended to the url segments specified.

Args:

*urls: list of URL segments **kwargs: supported params include

v (int): version to use on this request (i.e. 2, 3). Defaults

to the internal self.version

Returns:

CloudControllerRequest

resource_match(*args)

Convenience function passing the resource_match url segment.

Args:

*args: url segments that will be appended after resource_match

Returns:

CloudControllerRequest

routes(*args)

Convenience function passing the routes url segment.

Args:

*args: url segments that will be appended after routes

Returns:

CloudControllerRequest

security_groups(*args)

Convenience function passing the security_groups url segment.

Args:

*args: url segments that will be appended after security_groups

Returns:

CloudControllerRequest

service_bindings(*args)

Convenience function passing the service_bindings url segment.

Args:

*args: url segments that will be appended after

service_bindings

Returns:

CloudControllerRequest

service_brokers(*args)

Convenience function passing the service_brokers url segment.

Args:

*args: url segments that will be appended after service_brokers

Returns:

CloudControllerRequest

service_instances(*args)

Convenience function passing the service_instances url segment.

Args:

*args: url segments that will be appended after

service_instances

Returns:

CloudControllerRequest

service_plan_visibilities(*args)

Convenience function passing the service_plan_visibilities url segment.

Args:

*args: url segments that will be appended after

service_plan_visibilities

Returns:

CloudControllerRequest

service_plans(*args)

Convenience function passing the service_plans url segment.

Args:

*args: url segments that will be appended after service_plans

Returns:

CloudControllerRequest

services(*args)

Convenience function passing the services url segment.

Args:

*args: url segments that will be appended after services

Returns:

CloudControllerRequest

set_doppler(doppler)

Sets the internal doppler client

Args:

doppler (Doppler)

Returns:

self (CloudController)

set_info(info)

Sets the API info object

Args:

info (CFInfo): API info data

set_refresh_tokens_callback(callback=None)

This method sets the internal request callback to refresh the tokens when they expire. This is a convenience method and is not set by default.

Args:

callback (callable): An optional callback that will be invoked on

every request to the Cloud Controller and will supply three required arguments:

req (instanceof Request): the request to be executed cc (CloudController): the cloud controller object did_refresh (bool): whether the tokens were updated

Note

Note that this callback is called after the tokens are updated internally.

Returns:

self (CloudController)

set_ssh_proxy(ssh_proxy)

Sets the internal ssh proxy configuration

Args:

ssh (SSHProxy)

Returns:

self (CloudController)

set_uaa(uaa)

Sets the internal UAA client

Args:

uaa (UAA): an initialized instance of UAA class

Returns:

self (CloudController)

set_version(version)

Sets the API version to be use when creating requests

Args:

version (int): API version number

shared_domains(*args)

Convenience function passing the shared_domains url segment.

Args:

*args: url segments that will be appended after shared_domains

Returns:

CloudControllerRequest

should_refresh()

Determines whether the internal refresh_interval has passed

Returns:

bool

space_quota_definitions(*args)

Convenience function passing the space_quota_definitions url segment.

Args:

*args: url segments that will be appended after

space_quota_definitions

Returns:

CloudControllerRequest

spaces(*args)

Convenience function passing the spaces url segment.

Args:

*args: url segments that will be appended after spaces

Returns:

CloudControllerRequest

stacks(*args)

Convenience function passing the stacks url segment.

Args:

*args: url segments that will be appended after stacks

Returns:

CloudControllerRequest

update_tokens(res)

This method accepts a token response object from the UAA server. Note that the res.data dict must contain at least access_token.

Args:

res (CloudControllerResponse)

users(*args)

Convenience function passing the users url segment.

Args:

*args: url segments that will be appended after users

Returns:

CloudControllerRequest

class cf_api.CloudControllerRequest(factory=None)

Encapsulates a request to the Cloud Controller API

get_by_name(value, name='name')

Executes the list entities function searching for the given name

Returns:

CloudControllerResponse

search(*qlist, **qdict)

Sets the q query parameter used in listing most entities and executes the request

Args:

*qlist (tuple[str]): every 2 strings will be joined with a ‘:’ as

per the search format and each set to a q param. If only 1 string is passed, it will be assumed to contain a ‘:’ and will be set in the q param directly.

**qdict (dict): sets any additional query parameters

Returns:

CloudControllerResponse

class cf_api.CloudControllerResponse(response)

Encapsulates a response from the Cloud Controller API

error_code

Extracts the error code from this response

error_message

Extracts the error message from this response

resource

If the response is an array this gets the first item resource, else return the raw response

Returns:

Resource

resources

Attempts to parse the response as a resource list

Returns:

list[Resource]

class cf_api.UAA(base_url, client_id=None, client_secret=None)

Provides base functions for building UAA requests

access_token

Deprecated. DO NOT USE!

authorization_code(code, response_type, redirect_uri=None, **kwargs)

Sends a request for the authorization_code grant_type to acquire an access_token

Request parameters:

POST /oauth/token
Accept: application/json

    code = code
    response_type = response_type
    grant_type = 'authorization_code'
    redirect_uri = redirect_uri

Args:

code (str): one time use code passed by UAA to the redirect_uri

after successful user login at UAA

response_type (str): must be the response_type string used to

acquire the code

redirect_uri (str|None): must be the redirect_uri used to acquire

the code

**kwargs (dict): any custom request body parameters

Returns:

Response

authorization_code_url(response_type, scope=None, redirect_uri=None, state=None, **kwargs)

The following list summarizes the various authorization code flows in the UAA docs.:

Browser Flow:
    response_type='code', scope='...',
    redirect_uri='http://localhost/auth'

API Flow:
    response_type='code', state='somerandomstr',
    redirect_uri='http://localhost/auth'

Hybrid Flow:
    response_type='id_token code',
    redirect_uri='http://localhost/auth'

OpenID Connect Flow:
    response_type='id_token', scope='...',
    redirect_uri='http://localhost/auth'

    response_type='token id_token', scope='...',
    redirect_uri='http://localhost/auth'

Args:

response_type (str): valid response type strings (code, id_token,

token)

scope (str|list[str]|None): any scope strings you need redirect_uri (str|None): redirect URI that will receive the auth

code

state (str|None): used in API flow kwargs (dict): any additional request body params

Returns:

str: a URI to redirect the user for login with UAA. On successful

login, UAA will redirect to redirect_uri with a “code” query parameter containing a one time use code. The code is handled by the self.authorization_code() token function.

client_credentials()

Sends a request for client_credentials grant_type

Request parameters:

POST /oauth/token
Accept: application/json

    response_type = 'token',
    grant_type = 'client_credentials',

Returns:

Response

client_id

Get the internal client ID

Returns:

str

client_secret

Get the internal client secret

Returns:

str

get_access_token()

Get the internal access token

Returns:

JWT

get_refresh_token()

Get the internal refresh token

Returns:

JWT

password_grant(username, password)

Sends a request for password grant_type

Request parameters:

POST /oauth/token
Accept: application/json

    response_type = 'token'
    grant_type = 'password'
    client_id = self._client_id
    client_secret = self._client_secret
    username = username
    password = password

Returns:

Response

refresh_token(refresh_token=None)

Sends a request for refresh_token grant_type. This will use the internally set _refresh_token if the refresh_token arg is not set

Request parameters:

POST /oauth/token
Accept: application/json

    grant_type = 'refresh_token',
    client_id = self._client_id,
    client_secret = self._client_secret,
    refresh_token = str(refresh_token or self._refresh_token)

Args:

refresh_token (str|None): set a specific refresh token to be used.

Returns:

Response

set_access_token(access_token)

Set the internal access token

Args:

access_token (str)

Returns:

UAA

set_client_credentials(client_id, client_secret, set_basic_auth=False)

Set the internal client ID and secret

Args:

client_id (str): UAA client id client_secret (str): UAA client secret set_basic_auth (bool): if true, this will set the client ID and

secret in the Authorization as basic auth

set_refresh_token(refresh_token)

Set the internal refresh token

Args:

refresh_token (str)

Returns:

UAA

token_key()

Gets the token key for the internally set client_id

Returns:

Response

update_tokens(res)

Accepts a response object from the UAA Token Authorization API and updates this object with access_token and response_token.

Args:

res: Expects res.data[‘access_token’] and (optionally)

res.data[‘refresh_token’] to be set.

verify_token(token, **decode_kwargs)

Verifies the OAuth2 Token (or ID Token) using the client’s public key.

Args:

token (str): oauth token to be verified decode_kwargs (dict): keyword args for jwt.decode(**kwargs). This

is useful for specifying conditions of verification.

Returns:

dict: contents of the JWT

with_authorization()

Deprecated. DO NOT USE!

class cf_api.Resource(response, factory=None)

Provides shortcuts to the most commonly used fields of Cloud Controller resource objects.

guid

Shortcut to metadata.guid

name

Shortcut to entity.name

org_guid

Shortcut to entity.organization_guid

organization_url

Shortcut to entity.organization_url

routes_url

Shortcut to entity.routes_url

space_guid

Shortcut to entity.space_guid

spaces_url

Shortcut to entity.spaces_url

class cf_api.JWT(token_str, verify=False, **verify_kwargs)

Wrapper around the JWT object

is_expired

Indicates if the token is expired

to_string()

Get the original string representation of the token

class cf_api.Doppler(base_url, websocket_class=<class 'requests_factory.WebSocket'>)

Provides base functions for building Doppler/Loggregator API endpoints

apps(first, *url)

Create a new request object using the url segments

Args:

first (str): required url segment url (tuple[str]): optional url segments

Returns:

Request

set_websocket_class(websocket_class)

Sets the internal websocket wrapper class

Args:

websocket_class (WebSocket|callable): websocket class wrapper

Returns:

self (Doppler)

ws_request(first, *url)

Create a new WebSocket instance using the url segments

Args:

first (str): required url segment url (tuple[str]): optional url segments

Returns:

WebSocket

class cf_api.CFInfo(cc)

doppler_url

The base URL for Doppler

Returns:

str

ssh_client_id

The client ID to be used in authenticating with UAA before using the SSH proxy

Returns:

str

ssh_host_key_fingerprint

The SSH proxy host key fingerprint to verify when connecting to an application instance via SSH

Returns:

str

ssh_url

The base SSH proxy url

Returns:

str

uaa_url

The base URL for UAA

Returns:

str

class cf_api.SSHProxy(uaa, ssh_proxy, client_id, fingerprint)

cf_api.new_uaa(cc=None, base_url=None, verify_ssl=None, validate_ssl=None, username=None, password=None, client_id=None, client_secret=None, authorization_code=None, refresh_token=None, access_token=None, no_auth=False, cloud_controller_class=None, uaa_class=None)

Creates a new UAA client object. This function requires args base_url OR cc; base_url takes precedence over cc. If base_url not given, then cc must be an instance of str or CloudController. If an instance of str, then it’s converted into an instance of CloudController. CloudController.info().get() is called to get the UAA endpoint.

If no other authorization method is set, then client_credentials authorization will be attempted with the client_id and secret; however, if no_auth=True is passed, then no authorization will be attempted.

This method supports environment variable settings if some required arguments are left blank. See cc, client_id, client_secret, and verify_ssl.

Args:

cc (str|CloudController|None):

optional(if base_url is set), defaults to env var PYTHON_CF_URL. If base_url is passed, then this value is ignored

client_id (str|None):

required, defaults to env var PYTHON_CF_CLIENT_ID

client_secret (str|None):

required, defaults to env var PYTHON_CF_CLIENT_SECRET

verify_ssl (bool|None):

optional, defaults to env var !PYTHON_CF_IGNORE_SSL

base_url (str):

optional if cc is set, sets the UAA base endpoint url

username (str):

optional, user’s name

password (str):

optional, user’s password

authorization_code (dict):

optional, authorization_code method arguments. Setting this triggers the authorization_code() authorization method

refresh_token (str):

optional, refresh token string. Setting this will also trigger the refresh_token() authorization method. But if access_token is set, then the refresh token auth method will not be triggered, and the refresh token will be set on the UAA object.

access_token (str):

optional, access token string. If set, this set the access_token on the UAA object that is returned. If refresh_token is passed, then that will be set on the UAA object as well.

no_auth (bool):

optional, indicates to skip authorizing UAA. Neither access_token nor refresh_token will be set if this value is True.

validate_ssl (bool|None):

DEPRECATED use verify_ssl DEPRECATED

Returns:

UAA

cf_api.new_cloud_controller(base_url=None, validate_ssl=None, verify_ssl=None, username=None, password=None, client_id=None, client_secret=None, init_doppler=False, authorization_code=None, refresh_token=None, access_token=None, no_auth=False, version=2, cloud_controller_class=None, uaa_class=None, **kwargs)

Creates a new Cloud Controller client object AND attempts to get an Access Token from UAA using the user and/or client credentials. If username/password is given then the password grant_type will be used, otherwise, the client_credentials grant_type will be used.

The following arguments will default to the environment variable settings

Args:

base_url (str):

required, defaults to env var PYTHON_CF_URL

client_id (str|None):

required, defaults to env var PYTHON_CF_CLIENT_ID

client_secret (str|None):

required, defaults to env var PYTHON_CF_CLIENT_SECRET

verify_ssl (bool|None):

optional, defaults to env var !PYTHON_CF_IGNORE_SSL

username (str|None):

optional, see new_uaa()

password (str|None):

optional, see new_uaa()

authorization_code (dict|None):

optional, see new_uaa()

refresh_token (str|None):

optional, see new_uaa()

access_token (str|None):

optional, see new_uaa()

no_auth (bool|None):

optional, see new_uaa()

validate_ssl (bool|None):

DEPRECATED use verify_ssl DEPRECATED

Returns:

CloudController

cf_api.new_doppler(cc=None, base_url=None, verify_ssl=None, access_token=None)

Sets a the doppler base endpoint on this client. If cc is set, then all other args will be ignored.

Args:

cc (CloudController|None): initialized cloud controller instance base_url (str|None): base doppler url verify_ssl (bool|None): verify SSL certs access_token (str|None): access token string

Returns:

self (Doppler)

cf_api.deploy_manifest

class cf_api.deploy_manifest.Deploy(cc, manifest_filename, **manifest)

This class is able to deploy or destroy applications from Cloud Foundry Application Manifest files. Only part of the manifest spec is supported at this time. See https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html for available manifest parameters and further documentation.

Supported manifest attributes include the following:

name
random-route
buildpack
stack
command
host
hosts
routes
  route
instances
memory
disk
no-route
no-hostname
timeout
health-check-type
env
services
docker-image
  uri
  username
  password OR envvar:CF_DOCKER_PASSWORD

clone(new_name)

Copy this manifest to a new Deploy object with a new app name. All manifest attributes will be copied.

Args:

new_name (str): name to be replaced into the copied Deploy object

Returns:

Deploy

destroy(destroy_routes=False)

This command orchestrates the entire teardown and cleanup of the app’s resources. This command attempts to replicate the cf delete command. This command will optionally destroy any routes associated with this app as well.

The flow is roughly as follows:

Check if the app exists
Stop the app
Unbind services
Unbind routes (and optionally destroy)
Delete the app

Args:

destroy_routes (bool): if true, this will delete all routes

associated with the application

Returns:

None

log(*args, **kwargs)

Logs for this class, while respecting the debug flag

static parse_manifest(manifest_filename, cloud_controller)

This function parses an application manifest and creates a list of deploy instances to orchestrate push/destroying the app. This function will also handle the merging of top level attributes onto individual app declarations as well.

Args:

manifest_filename (str): filename to the application manifest cloud_controller: an initialized instance of cf_api.CloudController

Returns:

list[Deploy]: a list of application manifest objects that can be

pushed

push(no_start=False)

This command orchestrates the entire deployment of an app, handling both create and update scenarios. This command attempts to replicate the cf push command.

The flow is roughly as follows:

Create or update the app parameters
Bind services to the app
Archive and upload the app bits
Create and bind routes to the app
Restart the app

Returns:

None

set_debug(is_debug)

Sets a debug flag indicating whether this deployment will log progress messages

Args:

is_debug (bool)

Returns:

Deploy: self

set_org_and_space(org_name, space_name)

Sets the org / space where this application will be deployed

Args:

org_name (str): application’s org name space_name (str): application’s space name

Returns:

Deploy: self

set_org_and_space_dicts(org_dict, space_dict)

Sets the internal org / space settings using existing resource dicts where this application will be deployed. Using this method saves the extra requests required to internally fetch the org and space.

Args:

org_dict (dict|Resource): application’s org dict to be used

internally

space_dict (dict|Resource): application’s space dict to be used

internally

Returns:

Deploy: self

set_source_dirname(dirname)

Sets the app source directory which will be deployed

Args:

dirname (str)

Returns:

Deploy: self

start()

Start the app

Returns:

Deploy: self

stop()

Stop the app

Returns:

Deploy: self

wait_for_app_start(interval=20, timeout=300, tailing=False)

This function checks if the app has started on the given interval and 1) finishes when the app has started or 2) throws if the timeout has passed and the app has not started

Args:

interval (int): seconds on which to check if the app has started timeout (int): max seconds for which to wait for the app to start tailing (bool): if true, this will open a websocket and print out

the application logs in real-time

static wait_for_apps_start(deploys, interval=20, timeout=300, tailing=False)

This function waits for the apps to be staged with all instances running. It will check every interval and time out if it all instances are not up within the timeout.

Args:

deploys list[Deploy]: accepts a list of initialized manifest

objects

interval (int): seconds on which to check if the apps are started timeout (int): seconds to wait for the apps to start tailing (bool): if true, this will open a websocket and print out

the application logs in real-time

cf_api.deploy_service

class cf_api.deploy_service.DeployService(cc)

This class provides a basic interface to create and destroy services. Note you MUST set a space in which to operate before you can do anything with an instance of this class. See set_org_and_space() or set_space_guid() for more info on setting the space.

create(name, service_name, service_plan_name, tags=None, parameters=None)

Creates a service with the user defined name (name), service type (service_name), and service plan name (service_plan_name).

Args:

name (str): user defined service name service_name (str): type of service to be created service_plan_name (str): plan of the service to be create

Returns:

cf_api.Resource: the created or existing service object

destroy(name)

Destroys a service with the user defined name

Args:

name (str): user defined name of the service

Returns:

cf_api.Resource: deleted service instance

is_deprovisioned(name)

Checks if the service is de-provisioned

Args:

name (str): user defined name of the service

Returns:

bool

is_provision_state(name, state)

Checks if the service with name is in the given state

Args:

name (str): user defined service name state (str): allowed values are provisioned or deprovisioned

Returns:

bool

is_provisioned(name)

Checks if the service is provisioned

Args:

name (str): user defined name of the service

Returns:

bool

set_debug(debug)

Sets a debug flag on whether this client should print debug messages

Args:

debug (bool)

Returns:

DeployService: self

set_org_and_space(org_name, space_name)

Sets the org and space to be used in this service deployment

Args:

org_name (str): name of the organization space_name (str): name of the space

Returns:

DeployService: self

set_org_and_space_dicts(org_dict, space_dict)

Sets the internal org / space settings using existing resource dicts where this service will be deployed.

Args:

org_dict (dict|Resource): service instance’s org dict to be used

internally

space_dict (dict|Resource): service instance’s space dict to be

used internally

Returns:

DeployService: self

set_space_guid(space_guid)

Sets the guid of the space to be used in this deployment

Args:

space_guid (str): guid of the space

Returns:

DeployService: self

wait_service(name, state, timeout=300, interval=30)

Waits for the service with name to enter the state within the given timeout, while checking on the interval. This method WILL block until it’s the service is in the desired state, or the timeout has passed.

Args:

name (str): user defined service name state (str): allowed values are provisioned or deprovisioned timeout (int=300): units in seconds interval (int=30): units in seconds

cf_api.deploy_space

class cf_api.deploy_space.Space(cc, org_name=None, org_guid=None, space_name=None, space_guid=None, is_debug=None)

This class provides support for working with a particular space. It mainly provides convenience functions for deploying, fetching, and destroying the space, apps, and services.

create(**params)

Creates the space

Keyword Args:

params: HTTP body args for the space create endpoint

deploy_blue_green(manifest_filename, **kwargs)

Deploys the application in from the given manifest using the BlueGreen deployment strategy

Args:

manifest_filename (str) **kwargs (dict): are passed along to the BlueGreen constructor

Returns:

list

deploy_manifest(manifest_filename, **kwargs)

Deploys all apps in the given app manifest into this space.

Args:

manifest_filename (str): app manifest filename to be deployed

destroy(destroy_routes=False)

Destroys the space, and, optionally, any residual routes existing in the space.

Keyword Args:

destroy_routes (bool): indicates if to destroy routes

destroy_manifest(manifest_filename, destroy_routes=False)

Destroys all apps in the given app manifest in this space.

Args:

manifest_filename (str): app manifest filename to be destroyed

Keyword Args:

destroy_routes (bool): indicates whether to destroy routes

get_app_by_name(name)

Searches the space for an app with the name

get_blue_green(manifest_filename, **kwargs)

Parses the manifest and searches for app_name, returning an instance of the BlueGreen deployer object.

Args:

manifest_filename (str) **kwargs (dict): are passed along to the BlueGreen constructor

Returns:

list[cf_api.deploy_blue_green.BlueGreen]

get_deploy_manifest(manifest_filename)

Parses the manifest deployment list and sets the org and space to be used in deployment.

get_deploy_service()

Returns a service deployment client with the org and space to be used in deployment.

get_routes(host=None)

Searches the space for routes

get_service_instance_by_name(name)

Searches the space for a service instance with the name

org

Returns the currently set org

request(*urls)

Creates a request object with a base url (i.e. /v2/spaces/<id>)

set_debug(debug)

Sets a debug flag on whether this client should print debug messages

Args:

debug (bool)

Returns:

self (Space)

set_org(org_name)

Sets the organization name for this space

Args:

org_name (str): name of the organization

Returns:

space (Space): self

set_org_guid(org_guid)

Sets and loads the organization by the given GUID

set_space(space_name)

Sets the space name

Args:

space_name (str): name of the space

Returns:

space (Space): self

set_space_guid(space_guid)

Sets the GUID of the space to be used in this deployment

Args:

space_guid (str): guid of the space

Returns:

self (Space)

space

Returns the currently set space

wait_manifest(manifest_filename, interval=20, timeout=300, tailing=False)

Waits for an app to start given a manifest filename.

Args:

manifest_filename (str): app manifest filename to be waited on

Keyword Args:

interval (int): how often to check if the app has started timeout (int): how long to wait for the app to start

cf_api.deploy_blue_green

class cf_api.deploy_blue_green.BlueGreen(space, manifest, verbose=True, wait_kwargs=None, **kwargs)

This class orchestrates a Blue-Green deployment in the style of the Autopilot CF CLI plugin.

deploy()

Deploy the new application, wait for it to start, then clean up the old application.

deploy_app()

Deploys the new application

classmethod parse_manifest(space, manifest_filename, **kwargs)

Parses a deployment manifest and creates a BlueGreen instance for each application in the manifest.

Args:

space (cf_api.deploy_space.Space):

space to which the manifest should be deployed

manifest_filename (str):

application manifest to be deployed

**kwargs (dict):

passed into the BlueGreen constructor

Returns:

list[BlueGreen]

wait_and_cleanup()

Waits for the new application to start and then destroys the old version of the app.

cf_api.dropsonde_util

class cf_api.dropsonde_util.DopplerEnvelope(pbstr)

Utility class for parsing Doppler Envelope protocol buffers messages and accessing their members

app_id

Fetches the application UUID converting it from the UUID envelope message type. Currently this is only applicable to the HttpStartStop and LogMessage event types.

is_event_type(*event_type)

Checks if the event type is one of the passed in arguments

Args:

event_type (tuple[str]): HttpStartStop, LogMessage, CounterEvent,

ContainerEvent, ValueMetric

Returns:

bool

message

String message representing this envelope customized for several event types

request_id

Fetches the request UUID converting it from the UUID envelope message type. Currently this is only applicable to the HttpStartStop event type

static wrap(pbstr)

Parses a protobuf string into an Envelope dictionary

Args:

pbstr (basestring)

Returns:

DopplerEnvelope|None: if a falsy value is passed in, None is returned, else a DopplerEnvelope is returned.

cf_api.dropsonde_util.format_unixnano(unixnano)

Formats an integer unix timestamp from nanoseconds to a user readable string

Args:

unixnano (int): integer unix timestamp in nanoseconds

Returns:

formatted_time (str)

cf_api.dropsonde_util.get_uuid_string(**x)

This method parses a UUID protobuf message type from its component ‘high’ and ‘low’ longs into a standard formatted UUID string

Args:

x (dict): containing keys, ‘low’ and ‘high’ corresponding to the UUID

protobuf message type

Returns:

str: UUID formatted string

cf_api.dropsonde_util.parse_envelope_protobuf(pbstr)

Parses a protocol buffers string into a dictionary representing a Dropsonde Envelope protobuf message type

Args:

pbstr (basestring): protocol buffers string

Returns:

dict

cf_api.dropsonde_util.render_log_http_start_stop(m)

Formats an HttpStartStop protobuf event type

Args:

m (DopplerEnvelope): envelope object

Returns:

str: string message that may be printed

cf_api.exceptions

exception cf_api.exceptions.CFException(message, status_hint)

Base class of all exceptions used in this library

exception cf_api.exceptions.InvalidArgsException(message, status_hint)

Indicates that invalid arguments have been provided to the function

exception cf_api.exceptions.NotFoundException(message, status_hint)

Indicates that the requested object cannot be found

exception cf_api.exceptions.TimeoutException(message, status_hint)

Indicates that an operation has timed out

exception cf_api.exceptions.UnavailableException(message, status_hint)

Indicates that the requested Cloud Foundry component is unavailable

cf_api.logs_util

cf_api.routes_util

cf_api.routes_util.compose_route(host, domain, port, path)

Builds a string representation of the route components.

Args:

host (str): the first dot-segment of the hostname domain (str): the remainder of the hostname after the first dot-segment port (int|str): port number if applicable. If it’s a Falsy value, then

it will be ignored

path (str): if there’s no specific path, then just set ‘/’

Returns:

str: the form is ‘host.domain(:port)?/(path)?’

cf_api.routes_util.decompose_route(url)

Decomposes a URL into the parts relevant to looking up a route with the Cloud Controller.

Args:

url (str): some URL to an app hosted in Cloud Foundry

Returns:

tuple[str]: four parts, ‘host’, ‘domain’, ‘port’, ‘path’. Note that

‘host’ is the first dot-segment of the hostname and ‘domain’ is the remainder of the hostname

cf_api.routes_util.get_app_fqdns(cc, app_id, use_cache=True)

Get all FQDNs for and app id.

Args:

cc (cf_api.CloudController) app_id (str) use_cache (bool)

Returns:

list

cf_api.routes_util.get_default_fqdn(cc, app_id=None, app_resource=None)

Gets the default fully qualified domain name for an application.

Args:

cc (cf_api.CloudController) app_id (str): app GUID app_resource (cf_api.Resource): app Resource object

cf_api.routes_util.get_route_apps_from_url(cc, url, use_cache=True, require_one=True, started_only=True)

Get apps belonging to a URL hosted in Cloud Foundry. If you set require_one=True and start_only=False, then be aware that if there is an app in the STOPPED state in addition to the STARTED state attached to the underlying route, you’ll get an exception.

Args:

cc (cf_api.CloudController): initialized Cloud Controller instance url (str): some URL to an app hosted in Cloud Foundry use_cache (bool): use the internal caching mechanism to speed up

route/domain lookups

require_one (bool): assert that there is only one app belonging to this

URL and throw an error if there is more than one, else returns that one directly

started_only (bool): indicates to limit the search to apps with the

state of ‘STARTED’

Returns:

cf_api.Resource|list[cf_api.Resource]: If require_one=False, then a

list is returned, else the app resource object is returned

cf_api.routes_util.get_route_from_url(cc, url, use_cache=True, ignore_path=False, ignore_port=False, require_one=True)

Gets all routes that are associated with the given URL.

Args:

cc (cf_api.CloudController): initialized Cloud Controller instance url (str): some URL to an app hosted in Cloud Foundry use_cache (bool): use the internal caching mechanism to speed up

route/domain lookups

ignore_port (bool): indicates to ignore the URL port when looking up

the route

ignore_path (bool): indicates to ignore the URL path when looking up

the route

require_one (bool): assert that there is only one route belonging to

this URL and throw an error if there is more than one, else returns that one directly

Returns:

cf_api.Resource|list[cf_api.Resource]: If require_one=False, then a

list is returned, else the route resource object is returned

cf_api.ssh_util