Rancher Container Service Documentation¶

Rancher is a container orchestration platform.

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.base import ContainerImage
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,
)

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.base import ContainerImage
from libcloud.container.types import Provider
from libcloud.container.providers import get_driver

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: str, location: ClusterLocation | None = None) → ContainerCluster¶

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: ContainerCluster) → bool¶

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: str) → ContainerCluster¶

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: str) → ContainerImage¶

Install a container image from a remote path.

Parameters:: path (str) – Path to the container image
Return type:: ContainerImage

list_clusters(location: ClusterLocation | None = None) → List[ContainerCluster]¶

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[ContainerImage]¶

List the installed container images

Return type:: list of ContainerImage

list_locations() → List[ClusterLocation]¶

Get a list of potential locations to deploy clusters into

Return type:: list of ClusterLocation

restart_container(container: 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.