Rancher Container Service Documentation

Rancher is a container orchestration platform.

../../_images/rancher.png

This driver supports the main top-level interactions for handling containers, services, and stacks in a Rancher Environment.

Here are some notes around this driver:

  • Does not support user based API credentials, only Environment API credentials (one env, no cluster support)

  • Does not support images other than docker formatted images. docker: prefix is forced!

  • Images follow a standardized format. See deploy_container docstring!

  • launchConfig options for ex_deploy_service can all be defined at the top level then get slipstreamed appropriately.

  • Passing your own cert/key of any sort for SSL/TLS is not presently supported.

To enable API access, obtain an Environment API Key from your Rancher Server for the specific environment you want to control.

Instantiating the driver

from libcloud.container.types import Provider
from libcloud.container.providers import get_driver

driver = get_driver(Provider.RANCHER)

connection = driver(
    "MYRANCHERACCESSKEY",
    "MYRANCHERSECRETKEY",
    host="172.30.0.100",
    port=8080,
    secure=False,
)

connection.list_containers()

Deploying a container

from libcloud.container.types import Provider
from libcloud.container.providers import get_driver
from libcloud.container.base import ContainerImage

driver = get_driver(Provider.RANCHER)

connection = driver(
    "MYRANCHERACCESSKEY",
    "MYRANCHERSECRETKEY",
    host="172.30.0.100",
    port=8080,
    secure=False,
)

image = ContainerImage(
    "hastebin", "hastebin", "rlister/hastebin", "latest", driver=None
)

new_container = connection.deploy_container(
    name="awesomecontainer", image=image, networkMode="managed"
)

Deploying a service

from libcloud.container.types import Provider
from libcloud.container.providers import get_driver
from libcloud.container.base import ContainerImage

driver = get_driver(Provider.RANCHER)

connection = driver(
    "MYRANCHERACCESSKEY", "MYRANCHERSECRETKEY", host="17.23.66.4", port=443
)

image = ContainerImage(
    "hastebin", "hastebin", "rlister/hastebin", "latest", driver=None
)

new_service = connection.ex_deploy_service(
    name="excitingservice",
    image=image,
    environmentid="1e2",
    environment={"STORAGE_TYPE": "file"},
)

Deploying a stack

from libcloud.container.types import Provider
from libcloud.container.providers import get_driver

driver = get_driver(Provider.RANCHER)

connection = driver(
    "MYRANCHERACCESSKEY",
    "MYRANCHERSECRETKEY",
    host="172.30.0.100",
    port=8080,
    secure=False,
)

new_stack = connection.ex_deploy_stack(
    name="GhostBlog", description="Contains services for the" "ghost blog."
)

id_of_new_stack = new_stack["id"]

Searching for a container

from libcloud.container.types import Provider
from libcloud.container.providers import get_driver

driver = get_driver(Provider.RANCHER)

connection = driver(
    "MYRANCHERACCESSKEY",
    "MYRANCHERSECRETKEY",
    host="172.30.22.1",
    port=8080,
    secure=False,
)

search_results = connection.ex_search_containers(
    search_params={"imageUuid": "docker:mysql", "state": "running"}
)

id_of_first_result = search_results[0]["id"]

API Docs

class libcloud.container.drivers.rancher.RancherContainerDriver(key, secret, secure=True, host='localhost', port=443)[source]

Driver for Rancher by Rancher Labs.

This driver is capable of interacting with the Version 1 API of Rancher. It currently does NOT support the Version 2 API.

Example:

>>> from libcloud.container.providers import get_driver
>>> from libcloud.container.types import Provider
>>> driver = get_driver(Provider.RANCHER)
>>> connection = driver(key="ACCESS_KEY_HERE",
secret="SECRET_KEY_HERE", host="172.30.0.100", port=8080)
>>> image = ContainerImage("hastebin", "hastebin", "rlister/hastebin",
"latest", driver=None)
>>> newcontainer = connection.deploy_container("myawesomepastebin",
image, environment={"STORAGE_TYPE": "file"})
Variables

baseuri – The URL base path to the API.

Creates a new Rancher Container driver.

Parameters
  • key (str) – API key or username to used (required)

  • secret (str) – Secret password to be used (required)

  • secure (bool) – Whether to use HTTPS or HTTP.

  • host (str) – Override hostname used for connections. This can also be a full URL string, including scheme, port, and base path.

  • port (int) – Override port used for connections.

Returns

A newly initialized driver instance.

connectionCls

alias of RancherConnection

create_cluster(name, location=None)

Create a container cluster

Parameters
  • name (str) – The name of the cluster

  • location (ClusterLocation) – The location to create the cluster in

Return type

ContainerCluster

deploy_container(name, image, parameters=None, start=True, **config)[source]

Deploy a new container.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/container/#create

The following is the Image format used for ``ContainerImage``

For a ``imageuuid``:

  • docker:<hostname>:<port>/<namespace>/<imagename>:<version>

The following applies:

  • id = <imagename>

  • name = <imagename>

  • path = <hostname>:<port>/<namespace>/<imagename>

  • version = <version>

Any extra configuration can also be passed i.e. “environment”

Parameters
  • name (str) – The desired name of the container. (required)

  • image (libcloud.container.base.ContainerImage) – The Image object to deploy. (required)

  • parameters (str) – Container Image parameters (unused)

  • start (bool) – Whether to start the container on creation(startOnCreate)

Return type

Container

destroy_cluster(cluster)

Delete a cluster

Returns

True if the destroy was successful, otherwise False.

Return type

bool

destroy_container(container)[source]

Remove a container

Parameters

container (libcloud.container.base.Container) – The container to be destroyed

Returns

True if the destroy was successful, False otherwise.

Return type

bool

ex_activate_service(service_id)[source]

Activate a service.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/service/#activate

Parameters

service_id (str) – The service to activate services for.

Returns

True if activate was successful, False otherwise.

Return type

bool

ex_activate_stack(env_id)[source]

Activate Services for a stack.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/environment/#activateservices

Parameters

env_id (str) – The stack to activate services for.

Returns

True if activate was successful, False otherwise.

Return type

bool

ex_deactivate_service(service_id)[source]

Deactivate a service.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/service/#deactivate

Parameters

service_id (str) – The service to deactivate services for.

Returns

True if deactivate was successful, False otherwise.

Return type

bool

ex_deactivate_stack(env_id)[source]

Deactivate Services for a stack.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/environment/#deactivateservices

Parameters

env_id (str) – The stack to deactivate services for.

Returns

True if deactivate was successful, False otherwise.

Return type

bool

ex_deploy_service(name, image, environment_id, start=True, assign_service_ip_address=None, service_description=None, external_id=None, metadata=None, retain_ip=None, scale=None, scale_policy=None, secondary_launch_configs=None, selector_container=None, selector_link=None, vip=None, **launch_conf)[source]

Deploy a Rancher Service under a stack.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/service/#create

Any further configuration passed applies to the ``launchConfig``

Parameters
  • name (str) – The desired name of the service. (required)

  • image (libcloud.container.base.ContainerImage) – The Image object to deploy. (required)

  • environment_id (str) – The stack ID this service is tied to. (required)

  • start (bool) – Whether to start the service on creation.

  • assign_service_ip_address (bool) – The IP address to assign the service.

  • service_description (str) – The service description.

  • external_id (str) – The externalId for this service.

  • metadata (dict) – K/V Metadata for this service.

  • retain_ip (bool) – Whether this service should retain its IP.

  • scale (int) – The scale of containers in this service.

  • scale_policy (dict) – The scaling policy for this service.

  • secondary_launch_configs (list) – Secondary container launch configs.

  • selector_container (str) – The selectorContainer for this service.

  • selector_link (type) – The selectorLink for this service.

  • vip (str) – The VIP to assign to this service.

Returns

The newly created service.

Return type

dict

ex_deploy_stack(name, description=None, docker_compose=None, environment=None, external_id=None, rancher_compose=None, start=True)[source]

Deploy a new stack.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/environment/#create

Parameters
  • name (str) – The desired name of the stack. (required)

  • description (str) – A desired description for the stack.

  • docker_compose (str) – The Docker Compose configuration to use.

  • environment (dict) – Environment K/V specific to this stack.

  • external_id (str) – The externalId of the stack.

  • rancher_compose (str) – The Rancher Compose configuration for this env.

  • start (bool) – Whether to start this stack on creation.

Returns

The newly created stack.

Return type

dict

ex_destroy_service(service_id)[source]

Destroy a service by ID

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/service/#delete

Parameters

service_id (str) – The service to be destroyed.

Returns

True if destroy was successful, False otherwise.

Return type

bool

ex_destroy_stack(env_id)[source]

Destroy a stack by ID

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/environment/#delete

Parameters

env_id (str) – The stack to be destroyed.

Returns

True if destroy was successful, False otherwise.

Return type

bool

ex_get_service(service_id)[source]

Get a service by ID

Parameters

service_id (str) – The service_id to be obtained.

Return type

dict

ex_get_stack(env_id)[source]

Get a stack by ID

Parameters

env_id (str) – The stack to be obtained.

Return type

dict

ex_list_services()[source]

List all Rancher Services

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/service/

Return type

list of dict

ex_list_stacks()[source]

List all Rancher Stacks

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/environment/

Return type

list of dict

ex_search_containers(search_params)[source]

Search for containers matching certain filters

i.e. { "imageUuid": "docker:mysql", "state": "running"}

Parameters

search_params (dict) – A collection of search parameters to use.

Return type

list

ex_search_services(search_params)[source]

Search for services matching certain filters

i.e. { "name": "awesomesause", "environmentId": "1e2"}

Parameters

search_params (dict) – A collection of search parameters to use.

Return type

list

ex_search_stacks(search_params)[source]

Search for stacks matching certain filters

i.e. { "name": "awesomestack"}

Parameters

search_params (dict) – A collection of search parameters to use.

Return type

list

get_cluster(id)

Get a cluster by ID

Parameters

id (str) – The ID of the cluster to get

Return type

ContainerCluster

get_container(con_id)[source]

Get a container by ID

Parameters

con_id (str) – The ID of the container to get

Return type

libcloud.container.base.Container

install_image(path)

Install a container image from a remote path.

Parameters

path (str) – Path to the container image

Return type

ContainerImage

list_clusters(location=None)

Get a list of potential locations to deploy clusters into

Parameters

location (ClusterLocation) – The location to search in

Return type

list of ContainerCluster

list_containers()[source]

List the deployed containers.

http://docs.rancher.com/rancher/v1.2/en/api/api-resources/container/

Return type

list of libcloud.container.base.Container

list_images()

List the installed container images

Return type

list of ContainerImage

list_locations()

Get a list of potential locations to deploy clusters into

Return type

list of ClusterLocation

restart_container(container)

Restart a deployed container

Parameters

container (Container) – The container to restart

Return type

Container

start_container(container)[source]

Start a container

Parameters

container (libcloud.container.base.Container) – The container to be started

Returns

The container refreshed with current data

Return type

libcloud.container.base.Container

stop_container(container)[source]

Stop a container

Parameters

container (libcloud.container.base.Container) – The container to be stopped

Returns

The container refreshed with current data

Return type

libcloud.container.base.Container

supports_clusters = False

Whether the driver supports containers being deployed into clusters

Contributors

For the first version of this driver, Mario Loria of Arroyo Networks wrote most of the code. He received help from Anthony Shaw, a core libcloud contributor and Vincent Fiduccia, software architect at Rancher Labs.