You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by an...@apache.org on 2016/01/20 04:44:16 UTC
[28/50] libcloud git commit: Improved the documentation to better
explain the 2 types of drivers (cluster and non-cluster)
Improved the documentation to better explain the 2 types of drivers (cluster and non-cluster)
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/c188d325
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/c188d325
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/c188d325
Branch: refs/heads/trunk
Commit: c188d325ebae989cffd2241fb3170fb99e52adec
Parents: 8c01c62
Author: anthony-shaw <an...@gmail.com>
Authored: Tue Jan 5 20:49:05 2016 +1100
Committer: anthony-shaw <an...@gmail.com>
Committed: Tue Jan 5 20:49:05 2016 +1100
----------------------------------------------------------------------
docs/container/api.rst | 6 ++
docs/container/examples.rst | 8 +++
docs/container/index.rst | 33 ++++++++++-
.../examples/container/working_with_clusters.py | 24 ++++++++
libcloud/container/base.py | 58 ++++++++++----------
libcloud/container/drivers/docker.py | 38 ++++++-------
libcloud/container/drivers/ecs.py | 50 ++++++++---------
7 files changed, 141 insertions(+), 76 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/c188d325/docs/container/api.rst
----------------------------------------------------------------------
diff --git a/docs/container/api.rst b/docs/container/api.rst
index f9f7dd4..257b1a7 100644
--- a/docs/container/api.rst
+++ b/docs/container/api.rst
@@ -11,3 +11,9 @@ Container Base API
.. autoclass:: libcloud.container.base.ContainerImage
:members:
+
+.. autoclass:: libcloud.container.base.ContainerCluster
+ :members:
+
+.. autoclass:: libcloud.container.base.ClusterLocation
+ :members:
http://git-wip-us.apache.org/repos/asf/libcloud/blob/c188d325/docs/container/examples.rst
----------------------------------------------------------------------
diff --git a/docs/container/examples.rst b/docs/container/examples.rst
index 7e63b2b..a4e4316 100644
--- a/docs/container/examples.rst
+++ b/docs/container/examples.rst
@@ -12,4 +12,12 @@ This example shows how to get install a container image, deploy and start that c
This example works with Libcloud version 0.21.0 and above.
.. literalinclude:: /examples/container/install_and_deploy.py
+ :language: python
+
+Working with cluster supported providers
+----------------------------------------
+
+This example shows listing the clusters, find a specific named cluster and deploying a container to it.
+
+.. literalinclude:: /examples/container/working_with_clusters.py
:language: python
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/libcloud/blob/c188d325/docs/container/index.rst
----------------------------------------------------------------------
diff --git a/docs/container/index.rst b/docs/container/index.rst
index 8c6a271..01c9203 100644
--- a/docs/container/index.rst
+++ b/docs/container/index.rst
@@ -6,14 +6,41 @@ Container
Container API is available in Libcloud 0.21.0 and higher.
Container API allows users to install and deploy containers onto container based virtualization platforms. This is designed to target both
-on-premise installations of software like Docker and Rkt as well as interfacing with Cloud Service Providers that offer Container-as-a-Service APIs
+on-premise installations of software like Docker as well as interfacing with Cloud Service Providers that offer Container-as-a-Service APIs.
-Terminology
------------
+
+Drivers
+-------
+Container-as-a-Service providers will implement the `ContainerDriver` class to provide functionality for :
+
+* Listing deployed containers
+* Starting, stopping and restarting containers (where supported)
+* Destroying containers
+* Creating/deploying containers
+* Listing container images
+* Installing container images (pulling an image from a local copy or remote repository)
+
+Driver base API documentation is found here:
+
+* :class:`~libcloud.container.base.ContainerDriver` - A driver for interfacing to a container provider
+
+
+Simple Container Support
+------------------------
* :class:`~libcloud.container.base.ContainerImage` - Represents an image that can be deployed, like an application or an operating system
* :class:`~libcloud.container.base.Container` - Represents a deployed container image running on a container host
+Cluster Suppport
+----------------
+
+Cluster support extends on the basic driver functions, but where drivers implement the class-level attribute `supports_clusters` as True
+clusters may be listed, created and destroyed. When containers are deployed, the target cluster can be specified.
+
+* :class:`~libcloud.container.base.ContainerCluster` - Represents a deployed container image running on a container host
+* :class:`~libcloud.container.base.ClusterLocation` - Represents a location for clusters to be deployed
+
+
Supported Providers
-------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/c188d325/docs/examples/container/working_with_clusters.py
----------------------------------------------------------------------
diff --git a/docs/examples/container/working_with_clusters.py b/docs/examples/container/working_with_clusters.py
new file mode 100644
index 0000000..c63ce75
--- /dev/null
+++ b/docs/examples/container/working_with_clusters.py
@@ -0,0 +1,24 @@
+from libcloud.container.base import ContainerImage
+from libcloud.container.types import Provider
+from libcloud.container.providers import get_driver
+
+cls = get_driver(Provider.ECS)
+
+conn = cls(access_id='SDHFISJDIFJSIDFJ',
+ secret='p07jkijhHjb6sdf82yjhunvBtzGwt+I6TVkv68o4H',
+ region='ap-southeast-2')
+
+for cluster in conn.list_clusters():
+ print(cluster.name)
+ if cluster.name == 'my-cluster':
+ conn.list_containers(cluster=cluster)
+ container = conn.deploy_container(
+ name='my-simple-app',
+ image=ContainerImage(
+ id=None,
+ name='simple-app',
+ path='simple-app',
+ version=None,
+ driver=conn
+ ),
+ cluster=cluster)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/c188d325/libcloud/container/base.py
----------------------------------------------------------------------
diff --git a/libcloud/container/base.py b/libcloud/container/base.py
index 48ee573..7abe664 100644
--- a/libcloud/container/base.py
+++ b/libcloud/container/base.py
@@ -42,7 +42,7 @@ class Container(object):
:type name: ``str``
:param image: The image this container was deployed using.
- :type image: :class:`ContainerImage`
+ :type image: :class:`.ContainerImage`
:param state: The state of the container, e.g. running
:type state: :class:`libcloud.container.types.ContainerState`
@@ -51,7 +51,7 @@ class Container(object):
:type ip_addresses: ``list`` of ``str``
:param driver: ContainerDriver instance.
- :type driver: :class:`ContainerDriver`
+ :type driver: :class:`.ContainerDriver`
:param extra: (optional) Extra attributes (driver specific).
:type extra: ``dict``
@@ -103,7 +103,7 @@ class ContainerImage(object):
:type version: ``str``
:param driver: ContainerDriver instance.
- :type driver: :class:`ContainerDriver`
+ :type driver: :class:`.ContainerDriver`
:param extra: (optional) Extra attributes (driver specific).
:type extra: ``dict``
@@ -141,7 +141,7 @@ class ContainerCluster(object):
:type name: ``str``
:param driver: ContainerDriver instance.
- :type driver: :class:`ContainerDriver`
+ :type driver: :class:`.ContainerDriver`
:param extra: (optional) Extra attributes (driver specific).
:type extra: ``dict``
@@ -166,8 +166,8 @@ class ClusterLocation(object):
"""
A physical location where clusters can be.
- >>> from libcloud.container.drivers.dummy import DummyNodeDriver
- >>> driver = DummyNodeDriver(0)
+ >>> from libcloud.container.drivers.dummy import DummyContainerDriver
+ >>> driver = DummyContainerDriver(0)
>>> location = driver.list_locations()[0]
>>> location.country
'US'
@@ -185,7 +185,7 @@ class ClusterLocation(object):
:type country: ``str``
:param driver: Driver this location belongs to.
- :type driver: :class:`.NodeDriver`
+ :type driver: :class:`.ContainerDriver`
"""
self.id = str(id)
self.name = name
@@ -243,7 +243,7 @@ class ContainerDriver(BaseDriver):
:param path: Path to the container image
:type path: ``str``
- :rtype: :class:`ContainerImage`
+ :rtype: :class:`.ContainerImage`
"""
raise NotImplementedError(
'install_image not implemented for this driver')
@@ -252,7 +252,7 @@ class ContainerDriver(BaseDriver):
"""
List the installed container images
- :rtype: ``list`` of :class:`ContainerImage`
+ :rtype: ``list`` of :class:`.ContainerImage`
"""
raise NotImplementedError(
'list_images not implemented for this driver')
@@ -262,12 +262,12 @@ class ContainerDriver(BaseDriver):
List the deployed container images
:param image: Filter to containers with a certain image
- :type image: :class:`ContainerImage`
+ :type image: :class:`.ContainerImage`
:param cluster: Filter to containers in a cluster
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`.ContainerCluster`
- :rtype: ``list`` of :class:`Container`
+ :rtype: ``list`` of :class:`.Container`
"""
raise NotImplementedError(
'list_containers not implemented for this driver')
@@ -281,10 +281,10 @@ class ContainerDriver(BaseDriver):
:type name: ``str``
:param image: The container image to deploy
- :type image: :class:`ContainerImage`
+ :type image: :class:`.ContainerImage`
:param cluster: The cluster to deploy to, None is default
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`.ContainerCluster`
:param parameters: Container Image parameters
:type parameters: ``str``
@@ -292,7 +292,7 @@ class ContainerDriver(BaseDriver):
:param start: Start the container on deployment
:type start: ``bool``
- :rtype: :class:`Container`
+ :rtype: :class:`.Container`
"""
raise NotImplementedError(
'deploy_container not implemented for this driver')
@@ -304,7 +304,7 @@ class ContainerDriver(BaseDriver):
:param id: The ID of the container to get
:type id: ``str``
- :rtype: :class:`Container`
+ :rtype: :class:`.Container`
"""
raise NotImplementedError(
'get_container not implemented for this driver')
@@ -314,9 +314,9 @@ class ContainerDriver(BaseDriver):
Start a deployed container
:param container: The container to start
- :type container: :class:`Container`
+ :type container: :class:`.Container`
- :rtype: :class:`Container`
+ :rtype: :class:`.Container`
"""
raise NotImplementedError(
'start_container not implemented for this driver')
@@ -326,9 +326,9 @@ class ContainerDriver(BaseDriver):
Stop a deployed container
:param container: The container to stop
- :type container: :class:`Container`
+ :type container: :class:`.Container`
- :rtype: :class:`Container`
+ :rtype: :class:`.Container`
"""
raise NotImplementedError(
'stop_container not implemented for this driver')
@@ -338,9 +338,9 @@ class ContainerDriver(BaseDriver):
Restart a deployed container
:param container: The container to restart
- :type container: :class:`Container`
+ :type container: :class:`.Container`
- :rtype: :class:`Container`
+ :rtype: :class:`.Container`
"""
raise NotImplementedError(
'restart_container not implemented for this driver')
@@ -350,9 +350,9 @@ class ContainerDriver(BaseDriver):
Destroy a deployed container
:param container: The container to destroy
- :type container: :class:`Container`
+ :type container: :class:`.Container`
- :rtype: :class:`Container`
+ :rtype: :class:`.Container`
"""
raise NotImplementedError(
'destroy_container not implemented for this driver')
@@ -361,7 +361,7 @@ class ContainerDriver(BaseDriver):
"""
Get a list of potential locations to deploy clusters into
- :rtype: ``list`` of :class:`ClusterLocation`
+ :rtype: ``list`` of :class:`.ClusterLocation`
"""
raise NotImplementedError(
'list_locations not implemented for this driver')
@@ -374,9 +374,9 @@ class ContainerDriver(BaseDriver):
:type name: ``str``
:param location: The location to create the cluster in
- :type location: :class:`ClusterLocation`
+ :type location: :class:`.ClusterLocation`
- :rtype: :class:`ContainerCluster`
+ :rtype: :class:`.ContainerCluster`
"""
raise NotImplementedError(
'create_cluster not implemented for this driver')
@@ -396,9 +396,9 @@ class ContainerDriver(BaseDriver):
Get a list of potential locations to deploy clusters into
:param location: The location to search in
- :type location: :class:`ClusterLocation`
+ :type location: :class:`.ClusterLocation`
- :rtype: ``list`` of :class:`ContainerCluster`
+ :rtype: ``list`` of :class:`.ContainerCluster`
"""
raise NotImplementedError(
'list_clusters not implemented for this driver')
http://git-wip-us.apache.org/repos/asf/libcloud/blob/c188d325/libcloud/container/drivers/docker.py
----------------------------------------------------------------------
diff --git a/libcloud/container/drivers/docker.py b/libcloud/container/drivers/docker.py
index 981411a..d7c8419 100644
--- a/libcloud/container/drivers/docker.py
+++ b/libcloud/container/drivers/docker.py
@@ -198,7 +198,7 @@ class DockerContainerDriver(ContainerDriver):
:param path: Path to the container image
:type path: ``str``
- :rtype: :class:`ContainerImage`
+ :rtype: :class:`libcloud.container.base.ContainerImage`
"""
payload = {
}
@@ -231,7 +231,7 @@ class DockerContainerDriver(ContainerDriver):
"""
List the installed container images
- :rtype: ``list`` of :class:`ContainerImage`
+ :rtype: ``list`` of :class:`libcloud.container.base.ContainerImage`
"""
result = self.connection.request('/images/json').object
images = []
@@ -260,12 +260,12 @@ class DockerContainerDriver(ContainerDriver):
List the deployed container images
:param image: Filter to containers with a certain image
- :type image: :class:`ContainerImage`
+ :type image: :class:`libcloud.container.base.ContainerImage`
:param all: Show all container (including stopped ones)
:type all: ``bool``
- :rtype: ``list`` of :class:`Container`
+ :rtype: ``list`` of :class:`libcloud.container.base.Container`
"""
if all:
ex = '?all=1'
@@ -302,7 +302,7 @@ class DockerContainerDriver(ContainerDriver):
:type name: ``str``
:param image: The container image to deploy
- :type image: :class:`ContainerImage`
+ :type image: :class:`libcloud.container.base.ContainerImage`
:param parameters: Container Image parameters
:type parameters: ``str``
@@ -379,7 +379,7 @@ class DockerContainerDriver(ContainerDriver):
:param id: The ID of the container to get
:type id: ``str``
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
result = self.connection.request("/containers/%s/json" %
id).object
@@ -391,10 +391,10 @@ class DockerContainerDriver(ContainerDriver):
Start a container
:param container: The container to be started
- :type container: :class:`.Container`
+ :type container: :class:`libcloud.container.base.Container`
:return: The container refreshed with current data
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
payload = {
'Binds': [],
@@ -416,10 +416,10 @@ class DockerContainerDriver(ContainerDriver):
Stop a container
:param container: The container to be stopped
- :type container: :class:`.Container`
+ :type container: :class:`libcloud.container.base.Container`
:return: The container refreshed with current data
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
result = self.connection.request('/containers/%s/stop' %
(container.id),
@@ -435,10 +435,10 @@ class DockerContainerDriver(ContainerDriver):
Restart a container
:param container: The container to be stopped
- :type container: :class:`.Container`
+ :type container: :class:`libcloud.container.base.Container`
:return: The container refreshed with current data
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
data = json.dumps({'t': 10})
# number of seconds to wait before killing the container
@@ -456,7 +456,7 @@ class DockerContainerDriver(ContainerDriver):
Remove a container
:param container: The container to be destroyed
- :type container: :class:`.Container`
+ :type container: :class:`libcloud.container.base.Container`
:return: True if the destroy was successful, False otherwise.
:rtype: ``bool``
@@ -470,7 +470,7 @@ class DockerContainerDriver(ContainerDriver):
List processes running inside a container
:param container: The container to list processes for.
- :type container: :class:`.Container`
+ :type container: :class:`libcloud.container.base.Container`
:rtype: ``str``
"""
@@ -484,12 +484,12 @@ class DockerContainerDriver(ContainerDriver):
Rename a container
:param container: The container to be renamed
- :type container: :class:`.Container`
+ :type container: :class:`libcloud.container.base.Container`
:param name: The new name
:type name: ``str``
- :rtype: :class:`.Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
result = self.connection.request('/containers/%s/rename?name=%s'
% (container.id, name),
@@ -506,7 +506,7 @@ class DockerContainerDriver(ContainerDriver):
Logs are in different format of those of Version 1.10 and below
:param container: The container to list logs for
- :type container: :class:`.Container`
+ :type container: :class:`libcloud.container.base.Container`
:param stream: Stream the output
:type stream: ``bool``
@@ -542,7 +542,7 @@ class DockerContainerDriver(ContainerDriver):
:param term: The search term
:type term: ``str``
- :rtype: ``list`` of :class:`ContainerImage`
+ :rtype: ``list`` of :class:`libcloud.container.base.ContainerImage`
"""
term = term.replace(' ', '+')
@@ -573,7 +573,7 @@ class DockerContainerDriver(ContainerDriver):
Remove image from the filesystem
:param image: The image to remove
- :type image: :class:`ContainerImage`
+ :type image: :class:`libcloud.container.base.ContainerImage`
:rtype: ``bool``
"""
http://git-wip-us.apache.org/repos/asf/libcloud/blob/c188d325/libcloud/container/drivers/ecs.py
----------------------------------------------------------------------
diff --git a/libcloud/container/drivers/ecs.py b/libcloud/container/drivers/ecs.py
index d390201..9de61df 100644
--- a/libcloud/container/drivers/ecs.py
+++ b/libcloud/container/drivers/ecs.py
@@ -64,9 +64,9 @@ class ElasticContainerDriver(ContainerDriver):
Get a list of potential locations to deploy clusters into
:param location: The location to search in
- :type location: :class:`ClusterLocation`
+ :type location: :class:`libcloud.container.base.ClusterLocation`
- :rtype: ``list`` of :class:`ContainerCluster`
+ :rtype: ``list`` of :class:`libcloud.container.base.ContainerCluster`
"""
listdata = self.connection.request(
ROOT,
@@ -91,9 +91,9 @@ class ElasticContainerDriver(ContainerDriver):
:type name: ``str``
:param location: The location to create the cluster in
- :type location: :class:`ClusterLocation`
+ :type location: :class:`libcloud.container.base.ClusterLocation`
- :rtype: :class:`ContainerCluster`
+ :rtype: :class:`libcloud.container.base.ContainerCluster`
"""
request = {'clusterName': name}
response = self.connection.request(
@@ -125,12 +125,12 @@ class ElasticContainerDriver(ContainerDriver):
List the deployed container images
:param image: Filter to containers with a certain image
- :type image: :class:`ContainerImage`
+ :type image: :class:`libcloud.container.base.ContainerImage`
:param cluster: Filter to containers in a cluster
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`libcloud.container.base.ContainerCluster`
- :rtype: ``list`` of :class:`Container`
+ :rtype: ``list`` of :class:`libcloud.container.base.Container`
"""
request = {'cluster': 'default'}
if cluster is not None:
@@ -158,10 +158,10 @@ class ElasticContainerDriver(ContainerDriver):
:type name: ``str``
:param image: The container image to deploy
- :type image: :class:`ContainerImage`
+ :type image: :class:`libcloud.container.base.ContainerImage`
:param cluster: The cluster to deploy to, None is default
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`libcloud.container.base.ContainerCluster`
:param parameters: Container Image parameters
:type parameters: ``str``
@@ -169,7 +169,7 @@ class ElasticContainerDriver(ContainerDriver):
:param start: Start the container on deployment
:type start: ``bool``
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
data = {}
if ex_container_port is None and ex_host_port is None:
@@ -225,7 +225,7 @@ class ElasticContainerDriver(ContainerDriver):
:param id: The ID of the container to get
:type id: ``str``
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
containers = self.ex_list_containers_for_task([id])
return containers[0]
@@ -235,12 +235,12 @@ class ElasticContainerDriver(ContainerDriver):
Start a deployed task
:param container: The container to start
- :type container: :class:`Container`
+ :type container: :class:`libcloud.container.base.Container`
:param count: Number of containers to start
:type count: ``int``
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
return self.ex_start_task(container.extra['taskDefinitionArn'], count)
@@ -249,9 +249,9 @@ class ElasticContainerDriver(ContainerDriver):
Stop a deployed container
:param container: The container to stop
- :type container: :class:`Container`
+ :type container: :class:`libcloud.container.base.Container`
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
request = {'task': container.extra['taskArn']}
response = self.connection.request(
@@ -271,9 +271,9 @@ class ElasticContainerDriver(ContainerDriver):
Restart a deployed container
:param container: The container to restart
- :type container: :class:`Container`
+ :type container: :class:`libcloud.container.base.Container`
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
self.stop_container(container)
return self.start_container(container)
@@ -283,9 +283,9 @@ class ElasticContainerDriver(ContainerDriver):
Destroy a deployed container
:param container: The container to destroy
- :type container: :class:`Container`
+ :type container: :class:`libcloud.container.base.Container`
- :rtype: :class:`Container`
+ :rtype: :class:`libcloud.container.base.Container`
"""
return self.stop_container(container)
@@ -299,7 +299,7 @@ class ElasticContainerDriver(ContainerDriver):
:param count: The number of containers to start
:type count: ``int``
- :rtype: ``list`` of :class:`Container`
+ :rtype: ``list`` of :class:`libcloud.container.base.Container`
"""
request = None
request = {'count': count,
@@ -322,7 +322,7 @@ class ElasticContainerDriver(ContainerDriver):
:param task_arns: The list of ARNs
:type task_arns: ``list`` of ``str``
- :rtype: ``list`` of :class:`Container`
+ :rtype: ``list`` of :class:`libcloud.container.base.Container`
"""
describe_request = {'tasks': task_arns}
descripe_response = self.connection.request(
@@ -349,7 +349,7 @@ class ElasticContainerDriver(ContainerDriver):
:type name: ``str``
:param cluster: The cluster to run the service on
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`libcloud.container.base.ContainerCluster`
:param task_definition: The task definition name or ARN for the
service
@@ -379,7 +379,7 @@ class ElasticContainerDriver(ContainerDriver):
List the services
:param cluster: The cluster hosting the services
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`libcloud.container.base.ContainerCluster`
:rtype: ``list`` of ``str``
"""
@@ -399,7 +399,7 @@ class ElasticContainerDriver(ContainerDriver):
Get the details of a service
:param cluster: The hosting cluster
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`libcloud.container.base.ContainerCluster`
:param service_arn: The service ARN to describe
:type service_arn: ``str``
@@ -423,7 +423,7 @@ class ElasticContainerDriver(ContainerDriver):
Deletes a service
:param cluster: The target cluster
- :type cluster: :class:`ContainerCluster`
+ :type cluster: :class:`libcloud.container.base.ContainerCluster`
:param service_arn: The service ARN to destroy
:type service_arn: ``str``