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 <[email protected]> Authored: Tue Jan 5 20:49:05 2016 +1100 Committer: anthony-shaw <[email protected]> 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``
