NAV
http go python CLI

# Introduction

Docker Cloud currently offers a HTTP REST API and a Websocket Stream API which are used by both the Web UI and the CLI. This API documentation contains all API operations currently supported in the platform and provides examples of how to execute them using our Command Line Interface (CLI), Python SDK and Go SDK.

# Authentication

In order to be able to make requests to the Docker Cloud API, you should first obtain an ApiKey for your account. For this, log into Docker Cloud, click on the menu on the upper right corner of the screen, select Account info and then select API keys.

## REST API

    import dockercloud
    dockercloud.user = "username"
    dockercloud.apikey = "apikey"

    import "github.com/docker/go-dockercloud/dockercloud"

    dockercloud.User = "username"
    dockercloud.ApiKey = "apikey"

    GET /api/app/v1/service/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    export DOCKERCLOUD_USER=username
    export DOCKERCLOUD_APIKEY=apikey

> Make sure to replace `username` with your username and `apikey` with your API key.

The Docker Cloud REST API is reachable through the following hostname:

`https://cloud.docker.com/`

All requests should be sent to this endpoint using `Basic` authentication using your API key as password:

`Authorization: Basic dXNlcm5hbWU6YXBpa2V5`

HTTP responses are given in JSON format, so the following `Accept` header is required for every API call:

`Accept: application/json`

### Namespaced endpoints

Endpoints that are labeled as “namespaced” allow the users to operate over different namespaces, for example over an individual user namespace, or the namespace of an organization the user is a member of. A namespace identifies the owner of the resource.

The namespace is optional. If left blank, it defaults to the authenticated user in the request. The namespace is set before the resource in the URL schema: `https://cloud.docker.com/api/<subsystem>/<version>/(optional_namespace/)<resource>/`

Examples:

- The user `exampleuser` wants to operate on the node cluster list endpoint in their own namespace. They can use either of the following urls:
  - https://cloud.docker.com/api/infra/v1/nodecluster/ (namespace omitted, so will use the user authenticated in the request)
  - https://cloud.docker.com/api/infra/v1/exampleuser/nodecluster/
- The user wants to operate on the node cluster list endpoint in an organization called `exampleorg` (which they have permission to see):
  - https://cloud.docker.com/api/infra/v1/exampleorg/nodecluster/

### Namespaced endpoints in the docker-cloud CLI

If you are using namespaces with the `docker-cloud` CLI, set them by changing the value of the `DOCKERCLOUD_NAMESPACE` environment variable. You can either set this globally, or specify it before each CLI command. To learn more, see the Docker Cloud CLI README.

## Stream API

    import websocket
    import base64

    header = "Authorization: Basic %s" % base64.b64encode("%s:%s" % (username, password))
    ws = websocket.WebSocketApp('wss://ws.cloud.docker.com/v1/events', header=[header])

    import "github.com/gorilla/websocket"
    import "encoding/base64"

    var StreamUrl = "wss://ws.cloud.docker.com:443/v1/events"

    sEnc := base64.StdEncoding.EncodeToString([]byte(User + ":" + ApiKey))
    header := http.Header{}
    header.Add("Authorization", fmt.Sprintf("Basic %s", sEnc))

    var Dialer websocket.Dialer
    ws, _, err := Dialer.Dial(url, header)
    if err != nil {
        log.Println(err)
    }

    GET /api/audit/v1/events HTTP/1.1
    Host: ws.cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Connection: Upgrade
    Upgrade: websocket

    export DOCKERCLOUD_USER=username
    export DOCKERCLOUD_APIKEY=apikey

> Make sure to replace `username` with your username and `apikey` with your API key.

The Docker Cloud Stream API is reachable through the following hostname:

`wss://ws.cloud.docker.com/`

The Stream API requires the same authentication mechanism as the REST API:

`Authorization: Basic dXNlcm5hbWU6YXBpa2V5`

## API roles

> The CLI and the SDKs will detect this environment variable and automatically use it

If you give an API role to a container, the environment variable `DOCKERCLOUD_AUTH` inside the container will have the contents of the `Authorization` header that you can use to authenticate against the REST or Stream APIs:

`curl -H "Authorization: $DOCKERCLOUD_AUTH" https://cloud.docker.com/api/app/v1/service/`

# Actions

## Action

> Example

    {
        "action": "Cluster Create",
        "end_date": "Wed, 17 Sep 2014 08:26:22 +0000",
        "ip": "56.78.90.12",
        "is_user_action": true,
        "can_be_canceled": false,
        "location": "New York, USA",
        "method": "POST",
        "object": "/api/infra/v1/user_namespace/cluster/eea638f4-b77a-4183-b241-22dbd7866f22/",
        "path": "/api/infra/v1/user_namespace/cluster/",
        "resource_uri": "/api/audit/v1/action/6246c558-976c-4df6-ba60-eb1a344a17af/",
        "start_date": "Wed, 17 Sep 2014 08:26:22 +0000",
        "state": "Success",
        "user": "user_namespace",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.78.2 (KHTML, like Gecko) Version/7.0.6 Safari/537.78.2",
        "uuid": "6246c558-976c-4df6-ba60-eb1a344a17af"
    }

An action represents an API call by a user. Details of the API call such as timestamp, origin IP address, and user agent are logged in the action object.

Simple API calls that do not require asynchronous execution will return immediately with the appropiate HTTP error code and an action object will be created either in `Success` or `Failed` states. API calls that do require asynchronous execution will return HTTP code `202 Accepted` immediately and create an action object in `In progress` state, which will change to `Success` or `Failed` state depending on the outcome of the operation being performed. In both cases the response will include a `X-DockerCloud-Action-URI` header with the resource URI of the created action.

### Attributes

Attribute | Description
--- | ---
resource_uri | A unique API endpoint that represents the action
uuid | A unique identifier for the action generated automatically on creation
object | The API object (resource URI) to which the action applies to
action | Name of the operation performed/being performed
method | HTTP method used to access the API
path | HTTP path of the API accessed
user | The user authenticated in the request that created the action
user_agent | The user agent provided by the client when accessing the API endpoint
start_date | Date and time when the API call was performed and the operation started processing
end_date | Date and time when the API call finished processing
state | State of the operation (see table below)
ip | IP address of the user that performed the API call
location | Geographic location of the IP address of the user that performed the API call
is_user_action | If the action has been triggered by the user
can_be_canceled | If the action can be canceled by the user in the middle of its execution
can_be_retried | If the action can be retried by the user

### Action states

State | Description
--- | ---
Pending | The action needed asynchronous execution and it is waiting for an in progress action
In progress | The action needed asynchronous execution and is being performed
Canceling | The action is being canceled by user request
Canceled | The action has been canceled
Success | The action was executed successfully
Failed | There was an issue when the action was being performed. Check the logs for more information.

## List all actions

    import dockercloud

    actions = dockercloud.Action.list()

    import "github.com/docker/go-dockercloud/dockercloud"

    actionList, err := dockercloud.ListActions()

    if err != nil {
      log.Println(err)
    }

    log.Println(actionList)

    GET /api/audit/v1/action/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud action ls

Lists all actions in chronological order. Returns a list of `Action` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/audit/v1/action/`

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID.
state | Filter by state. Possible values: `In progress`, `Success`, `Failed`
start_date | Filter by start date. Valid filtering values are `start_date__gte` (after or on the date supplied) and `start_date__lte` (before or on the date supplied)
end_date | Filter by end date. Valid filtering values are `end_date__gte` (after or on the date supplied) and `end_date__lte` (before or on the date supplied)
object | Filter by resource URI of the related object. This filter can only be combined with ‘include_related’ filter
include_related | There is a parent-child relationship between Docker Cloud objects, described in table `Relationships between Docker Cloud objects`. If set to 'true’, will include the actions of the related objects to the object specified in “object” filter parameter. Possible values: 'true’ or 'false’

## Relationships between Docker Cloud objects

Object | Relationships
--- | ---
Container | Container, service, stack (if any)
Service | All containers in the service, service, stack (if any)
Stack | All services in the stack, all containers in every service in the stack, stack
Node | Node, node cluster (if any)
Node cluster | All nodes in the cluster, node cluster

## Get an action by UUID

    import dockercloud

    action = dockercloud.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    import "github.com/docker/go-dockercloud/dockercloud"

    action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    log.Println(action)

    GET /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud action inspect 7eaf7fff

Get all the details of an specific action

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/audit/v1/action/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the action to retrieve

## Get the logs of an action

> Example log line

    {
        "type": "log",
        "log": "Log line from the action",
        "timestamp": 1433779324
    }

    import dockercloud

    def log_handler(message):
        print message

    action = dockercloud.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    action.logs(tail=300, follow=True, log_handler=log_handler)

    import "github.com/docker/go-dockercloud/dockercloud"

    c := make(chan dockercloud.Logs)
    action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
        log.Println(err)
    }

    go action.GetLogs(c)

    for {
        log.Println(<-c)
    }

    GET /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
    Host: ws.cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Connection: Upgrade
    Upgrade: websocket

    docker-cloud action logs 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Get the logs of the specified action.

### Endpoint Type

Available in Docker Cloud’s STREAM API

### HTTP Request

`GET /api/audit/v1/action/(uuid)/logs/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the action to retrieve logs

### Query Parameters

Parameter | Description
--- | ---
tail | Number of lines to show from the end of the logs (default: `300`)
follow | Whether to stream logs or close the connection immediately (default: true)

## Cancel an action

    POST /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/cancel/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    action, err = action.Cancel()

    if err != nil {
      log.Println(err)
    }

    log.Println(action)

Cancels an action in Pending or In progress state.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/audit/v1/action/(uuid)/cancel/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the action to cancel

## Retry an action

    import dockercloud

    def log_handler(message):
      print message

    action = dockercloud.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    action.logs(tail=300, follow=True, log_handler=log_handler)

    POST /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/retry/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    action, err = action.Retry()

    if err != nil {
      log.Println(err)
    }

    log.Println(action)

    docker-cloud action logs 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Retries an action in Success, Failed or Canceled state.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/audit/v1/action/(uuid)/retry/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the action to retry

# Providers

## Provider

> Example

    {
        "available": true,
        "label": "Digital Ocean",
        "name": "digitalocean",
        "regions": [
            "/api/infra/v1/region/digitalocean/ams1/",
            "/api/infra/v1/region/digitalocean/ams2/",
            "/api/infra/v1/region/digitalocean/ams3/",
            "/api/infra/v1/region/digitalocean/lon1/",
            "/api/infra/v1/region/digitalocean/nyc1/",
            "/api/infra/v1/region/digitalocean/nyc2/",
            "/api/infra/v1/region/digitalocean/nyc3/",
            "/api/infra/v1/region/digitalocean/sfo1/",
            "/api/infra/v1/region/digitalocean/sgp1/"
        ],
        "resource_uri": "/api/infra/v1/provider/digitalocean/"
    }

A provider is a representation of a cloud provider supported by Docker Cloud. Providers have one or more regions where nodes are deployed.

### Attributes

Attribute | Description
--- | ---
resource_uri | A unique API endpoint that represents the provider
name | A unique identifier for the provider
label | A user-friendly name for the provider
regions | A list of resource URIs of the regions available in this provider
available | Whether the provider is currently available for new node deployments

## List all providers

    import dockercloud

    providers = dockercloud.Provider.list()

    GET /api/infra/v1/provider/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    providerList, err := dockercloud.ListProviders()

    if err != nil {
      log.Println(err)
    }

    log.Println(providerList)

    docker-cloud nodecluster provider

Lists all supported cloud providers. Returns a list of `Provider` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/provider/`

### Query Parameters

Parameter | Description
--- | ---
name | Filter by provider name

## Get an individual provider

    import dockercloud

    provider = dockercloud.Provider.fetch("digitalocean")

    import "github.com/docker/go-dockercloud/dockercloud"

    provider, err := dockercloud.GetProvider("digitalocean")

    if err != nil {
      log.Println(err)
    }

    log.Println(provider)

    GET /api/infra/v1/provider/digitalocean/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Get all the details of a specific provider

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/provider/(name)/`

### Path Parameters

Parameter | Description
--- | ---
name | The name of the provider to retrieve

# Regions

## Region

> Example

    {
        "availability_zones": [],
        "available": true,
        "label": "Amsterdam 2",
        "name": "ams2",
        "node_types": [
            "/api/infra/v1/nodetype/digitalocean/1gb/",
            "/api/infra/v1/nodetype/digitalocean/2gb/",
            "/api/infra/v1/nodetype/digitalocean/4gb/",
            "/api/infra/v1/nodetype/digitalocean/8gb/",
            "/api/infra/v1/nodetype/digitalocean/16gb/",
            "/api/infra/v1/nodetype/digitalocean/32gb/",
            "/api/infra/v1/nodetype/digitalocean/48gb/",
            "/api/infra/v1/nodetype/digitalocean/64gb/"
        ],
        "provider": "/api/infra/v1/provider/digitalocean/",
        "resource_uri": "/api/infra/v1/region/digitalocean/ams2/"
    }

A region is a representation of an entire or a subset of a data center of a cloud provider. It can contain availability zones (depending on the provider) and one or more node types.

### Attributes

Attribute | Description
--- | ---
resource_uri | A unique API endpoint that represents the region
name | An identifier for the region
label | A user-friendly name for the region
node_types | A list of resource URIs of the node types available in the region
availability_zones | A list of resource URIs of the availability zones available in the region
provider | The resource URI of the provider of the region
available | Whether the region is currently available for new node deployments

## List all regions

    import dockercloud

    regions = dockercloud.Region.list()

    GET /api/infra/v1/region/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    regionList, err := dockercloud.ListRegions()

    if err != nil {
      log.Println(err)
    }

    log.Println(regionList)

    docker-cloud nodecluster region

Lists all regions of all supported cloud providers. Returns a list of `Region` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/region/`

### Query Parameters

Parameter | Description
--- | ---
name | Filter by region name
provider | Filter by resource URI of the target provider

## Get an individual region

    import dockercloud

    region = dockercloud.Region.fetch("digitalocean/lon1")

    import "github.com/docker/go-dockercloud/dockercloud"

    region, err := dockercloud.GetRegion("digitalocean","lon1")

    if err != nil {
      log.Println(err)
    }

    log.Println(region)

    GET /api/infra/v1/region/digitalocean/lon1/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Get all the details of a specific region

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/region/(provider.name)/(name)/`

### Path Parameters

Parameter | Description
--- | ---
name | The name of the region to retrieve
provider.name | The name of the provider of the region

# Availability Zones

## Availability Zone

> Example

    {
        "available": true,
        "name": "ap-northeast-1a",
        "region": "/api/infra/v1/region/az/ap-northeast-1/",
        "resource_uri": "/api/infra/v1/az/aws/ap-northeast-1/ap-northeast-1a/"
    }

An Availability Zone is an isolated location inside a region. Providers that support availability zones: AWS

### Attributes

Attribute | Description
--- | ---
available | Whether the availability zone is currently available for new node deployments
name | An identifier for the availability zone
region | The resource URI of the region where the availability zone is allocated
resource_uri | A unique API endpoint that represents the zone

## List all availability zones

    import dockercloud

    az = dockercloud.AZ.list()

    GET /api/infra/v1/az/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    az, err := dockercloud.ListAZ()
    if err != nil {
        log.Println(err)
    }

    log.Println(az)

    docker-cloud nodecluster az

Lists all availability zones from all regions of all supported cloud providers. Returns a list of `Availability Zone` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/az/`

### Query Parameters

Parameter | Description
--- | ---
name | Filter by availability zone name
region | Filter by resource URI of the target region

## Get an individual availability zone

    import dockercloud

    az = dockercloud.AZ.fetch("aws/sa-east-1/sa-east-1a")

    import "github.com/docker/go-dockercloud/dockercloud"

    az, err := dockercloud.GetAZ("aws/sa-east-1/sa-east-1a")
    if err != nil {
        log.Println(err)
    }

    log.Println(az)

    GET /api/infra/v1/az/aws/sa-east-1/sa-east-1a/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Get all the details of a specific availability zone

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/az/(provider.name)/(region.name)/(name)/`

### Path Parameters

Parameter | Description
--- | ---
name | The name of the availability zone to retrieve
provider | The name of the provider
region | The name of the region

# Node Types

## Node Type

> Example

    {
        "availability_zones": [],
        "available": true,
        "label": "1GB",
        "name": "1gb",
        "provider": "/api/infra/v1/provider/digitalocean/",
        "regions": [
            "/api/infra/v1/region/digitalocean/ams1/",
            "/api/infra/v1/region/digitalocean/sfo1/",
            "/api/infra/v1/region/digitalocean/nyc2/",
            "/api/infra/v1/region/digitalocean/ams2/",
            "/api/infra/v1/region/digitalocean/sgp1/",
            "/api/infra/v1/region/digitalocean/lon1/",
            "/api/infra/v1/region/digitalocean/nyc3/",
            "/api/infra/v1/region/digitalocean/nyc1/"
        ],
        "resource_uri": "/api/infra/v1/nodetype/digitalocean/1gb/"
    }

A node type is a representation of an instance size supported by a certain cloud provider in a certain region and/or availability zone.

### Attributes

Attribute | Description
--- | ---
resource_uri | A unique API endpoint that represents the node type
name | An identifier for the node type
label | A user-friendly name for the node type
regions | A list of resource URIs of the regions to which this node type can be deployed to
availability_zones | A list of resource URIs of the availability zones to which this node type can be deployed to
provider | The resource URI of the provider of the node type
available | Whether the node type is currently available for new node deployments

## List all node types

    import dockercloud

    nodetypes = dockercloud.NodeType.list()

    import "github.com/docker/go-dockercloud/dockercloud"

    nodetypeList, err := dockercloud.ListNodeTypes()

    if err != nil {
      log.Println(err)
    }

    log.Println(nodetypeList)

    GET /api/infra/v1/nodetype/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud nodecluster nodetype

Lists all node types of all supported cloud providers. Returns a list of `NodeType` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/nodetype/`

### Query Parameters

Parameter | Description
--- | ---
name | Filter by node type name
regions | Filter by resource URI of the target regions
availability_zones | Filter by resource URI of the target availability zones

## Get an individual node type

    import dockercloud

    nodetype = dockercloud.NodeType.fetch("digitalocean/1gb")

    import "github.com/docker/go-dockercloud/dockercloud"

    nodetype, err := dockercloud.GetNodeType("digitalocean","1gb")

    if err != nil {
      log.Println(err)
    }

    log.Println(nodetype)

    GET /api/infra/v1/nodetype/digitalocean/1gb/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Get all the details of a specific node type

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/nodetype/(provider.name)/(name)/`

### Path Parameters

Parameter | Description
--- | ---
name | The name of the node type to retrieve
provider.name | The name of the provider of the node type

# Node Clusters

## Node Cluster

> Example

    {
        "current_num_nodes": 1,
        "deployed_datetime": "Tue, 16 Sep 2014 17:01:15 +0000",
        "destroyed_datetime": null,
        "disk": 60,
        "nickname": "my test cluster",
        "name": "TestCluster",
        "node_type": "/api/infra/v1/nodetype/aws/t2.micro/",
        "nodes": [
            "/api/infra/v1/user_namespace/node/75d20367-0948-4f10-8ba4-ffb4d16ed3c6/"
        ],
        "region": "/api/infra/v1/region/aws/us-east-1/",
        "resource_uri": "/api/infra/v1/user_namespace/nodecluster/5516df0b-721e-4470-b350-741ff22e63a0/",
        "state": "Deployed",
        "tags": [
            {"name": "tag_one"},
            {"name": "tag-two"},
            {"name": "tagthree3"}
        ],
        "target_num_nodes": 2,
        "uuid": "5516df0b-721e-4470-b350-741ff22e63a0",
        "provider_options": {
            "vpc": {
                "id": "vpc-aa1c70d4",
                "subnets": ["subnet-aaa7d94f", "subnet-aa15fa64"],
                "security_groups": ["sg-aa1c70d4"]
            },
            "iam": {
                "instance_profile_name": "my_instance_profile"
            }
        }
    }

A node cluster is a group of nodes that share the same provider, region and/or availability zone, and node type. They are on the same private network.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
uuid | A unique identifier for the node cluster generated automatically on creation
resource_uri | A unique API endpoint that represents the node cluster
name | A user provided name for the node cluster
state | The state of the node cluster. See the below table for a list of possible states.
node_type | The resource URI of the node type used for the node cluster
disk | The size of the disk where images and containers are stored (in GB)
nodes | A list of resource URIs of the `Node` objects on the node cluster
region | The resource URI of the `Region` object where the node cluster is deployed
target_num_nodes | The desired number of nodes for the node cluster
current_num_nodes | The actual number of nodes in the node cluster. This may differ from `target_num_nodes` if the node cluster is being deployed or scaled
deployed_datetime | The date and time when this node cluster was deployed
destroyed_datetime | The date and time when this node cluster was terminated (if applicable)
tags | List of tags to identify the node cluster nodes when deploying services (see Tags for more information)
provider_options | Provider-specific extra options for the deployment of the node (see `Provider options` table below for more information)
nickname | A user-friendly name for the node cluster (`name` by default)

### Node Cluster states

State | Description
--- | ---
Init | The node cluster has been created and has no deployed containers yet. Possible actions in this state: `deploy`, `terminate`.
Deploying | All nodes in the cluster are either deployed or being deployed. No actions allowed in this state.
Deployed | All nodes in the cluster are deployed and provisioned. Possible actions in this state: `terminate`.
Partly deployed | One or more nodes of the cluster are deployed and running. Possible actions in this state: `terminate`.
Scaling | The cluster is either deploying new nodes or terminating existing ones responding to a scaling request. No actions allowed in this state.
Terminating | All nodes in the cluster are either being terminated or already terminated. No actions allowed in this state.
Terminated | The node cluster and all its nodes have been terminated. No actions allowed in this state.
Empty cluster | There are no nodes deployed in this cluster. Possible actions in this state: `terminate`.

### Provider options

You can specify the following options when using the Amazon Web Services provider:

- `vpc`: VPC-related options (optional)
  - `id`: AWS VPC identifier of the target VPC where the nodes of the cluster will be deployed (required)
  - `subnets`: a list of target subnet indentifiers inside selected VPC. If you specify more than one subnet, Docker Cloud will balance among all of them following a high-availability schema (optional)
  - `security_groups`: the security group that will be applied to every node of the cluster (optional)
- `iam`: IAM-related options (optional)
  - `instance_profile_name`: name of the instance profile (container for instance an IAM role) to attach to every node of the cluster (required)

## List all node clusters

    import dockercloud

    nodeclusters = dockercloud.NodeCluster.list()

    import "github.com/docker/go-dockercloud/dockercloud"

    nodeclusters, err := dockercloud.ListNodeClusters()

    if err != nil {
      log.Println(err)
    }

    log.Println(nodeclusters)

    GET /api/infra/v1/nodecluster/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud nodecluster ls

Lists all current and recently terminated node clusters. Returns a list of `NodeCluster` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/[optional_namespace/]nodecluster/`

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID
state | Filter by state. Possible values: `Init`, `Deploying`, `Deployed`, `Partly deployed`, `Scaling`, `Terminating`, `Terminated`, `Empty cluster`
name | Filter by node cluster name
region | Filter by resource URI of the target region
node_type | Filter by resource URI of the target node type

## Create a new node cluster

    import dockercloud

    region = dockercloud.Region.fetch("digitalocean/lon1")
    node_type = dockercloud.NodeType.fetch("digitalocean/1gb")
    nodecluster = dockercloud.NodeCluster.create(name="my_cluster", node_type=node_type, region=region, disk=60)
    nodecluster.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    nodecluster, err := dockercloud.CreateNodeCluster(dockercloud.NodeCreateRequest{Name: "my_cluster", Region: "/api/infra/v1/region/digitalocean/lon1/", NodeType: "/api/infra/v1/nodetype/digitalocean/1gb/", Target_num_nodes: 2})

    if err != nil {
      log.Println(err)
    }

    log.Println(nodecluster)

    POST /api/infra/v1/nodecluster/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {"name": "my_cluster", "region": "/api/infra/v1/region/digitalocean/lon1/", "node_type": "/api/infra/v1/nodetype/digitalocean/1gb/", "disk": 60}

    docker-cloud nodecluster create my_cluster digitalocean lon1 1gb

Creates a new node cluster without deploying it.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/infra/v1/[optional_namespace/]nodecluster/`

### JSON Parameters

Parameter | Description
--- | ---
name | (required) A user provided name for the node cluster
node_type | (required) The resource URI of the node type to be used for the node cluster
region | (required) The resource URI of the region where the node cluster is to be deployed
disk | (optional) The size of the volume to create where images and containers will be stored, in GB (default: `60`). Not available for Digital Ocean. To create Softlayer nodes you must select one of the following sizes (in GBs): 10, 20, 25, 30, 40, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 500, 750, 1000, 1500 or 2000
nickname | (optional) A user-friendly name for the node cluster (`name` by default)
target_num_nodes | (optional) The desired number of nodes for the node cluster (default: `1`)
tags | (optional) List of tags of the node cluster to be used when deploying services see Tags for more information) (default: `[]`)
provider_options | Provider-specific extra options for the deployment of the node (see table `Provider options` above for more information)

## Get an existing node cluster

    import dockercloud

    service = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    import "github.com/docker/go-dockercloud/dockercloud"

    nodecluster, err := dockercloud.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    log.Println(nodecluster)

    GET /api/infra/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud nodecluster inspect 7eaf7fff

Get all the details of an specific node cluster

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/[optional_namespace/]nodecluster/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node cluster to retrieve

## Deploy a node cluster

    import dockercloud

    nodecluster = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    nodecluster.deploy()

    import "github.com/docker/go-dockercloud/dockercloud"

    nodecluster, err := dockercloud.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = nodecluster.Deploy(); err != nil {
       log.Println(err)
    }

    POST /api/infra/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/deploy/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Deploys and provisions a recently created node cluster in the specified region and cloud provider.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/infra/v1/[optional_namespace/]nodecluster/(uuid)/deploy/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node cluster to deploy

## Update an existing node cluster

    import dockercloud

    nodecluster = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    nodecluster.target_num_nodes = 3
    nodecluster.tags.add("tag-1")
    nodecluster.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    nodecluster, err := dockercloud.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = nodecluster.Update(dockercloud.NodeCreateRequest{Target_num_nodes: 4}); err != nil {
       log.Println(err)
    }

    PATCH /api/infra/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {"target_num_nodes": 3, "tags": [{"name": "tag-1"}]}

    docker-cloud nodecluster scale 7eaf7fff 3
    docker-cloud tag add -t tag-1 7eaf7fff
    docker-cloud tag set -t tag-2 7eaf7fff

Updates the node cluster details and applies the changes automatically.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`PATCH /api/infra/v1/[optional_namespace/]nodecluster/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node cluster to update

### JSON Parameters

Parameter | Description
--- | ---
target_num_nodes | (optional) The number of nodes to scale this node cluster to
tags | (optional) List of tags the node cluster (and nodes within the node cluster) will have. This operation replaces the user tag list.

## Terminate a node cluster

    import dockercloud

    nodecluster = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    nodecluster.delete()

    import "github.com/docker/go-dockercloud/dockercloud"

    nodecluster, err := dockercloud.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = nodecluster.Terminate(); err != nil {
       log.Println(err)
    }

    DELETE /api/infra/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    dockercloud nodecluster rm 7eaf7fff

Terminates all the nodes in a node cluster and the node cluster itself. This is not reversible.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`DELETE /api/infra/v1/[optional_namespace/]nodecluster/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node cluster to terminate

# Nodes

## Node

> Example

    {
        "availability_zone": "/api/infra/v1/az/testing-provider/testing-region/testing-az/",
        "cpu": 1,
        "current_num_containers": 4,
        "deployed_datetime": "Tue, 16 Sep 2014 17:01:15 +0000",
        "destroyed_datetime": null,
        "disk": 60,
        "docker_execdriver": "native-0.2",
        "docker_graphdriver": "aufs",
        "docker_version": "1.5.0",
        "external_fqdn": "fc1a5bb9-user.node.dockerapp.io",
        "last_seen": "Thu, 25 Sep 2014 13:14:44 +0000",
        "memory": 1792,
        "nickname": "fc1a5bb9-user.node.dockerapp.io",
        "node_cluster": "/api/infra/v1/user_namespace/nodecluster/d787a4b7-d525-4061-97a0-f423e8f1d229/",
        "node_type": "/api/infra/v1/user_namespace/nodetype/testing-provider/testing-type/",
        "public_ip": "10.45.2.11",
        "region": "/api/infra/v1/region/testing-provider/testing-region/",
        "resource_uri": "/api/infra/v1/user_namespace/node/fc1a5bb9-17f5-4819-b667-8c7cd819e949/",
        "state": "Deployed",
        "tags": [
            {"name": "tag_one"},
            {"name": "tag-two"}
        ],
        "tunnel": "https://tunnel01.cloud.docker.com:12345",
        "uuid": "fc1a5bb9-17f5-4819-b667-8c7cd819e949"
    }

A node is a virtual machine provided by a cloud provider where containers can be deployed.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
availability_zone | The resource URI of the availability zone where the node is deployed, if any
uuid | A unique identifier for the node generated automatically on creation
resource_uri | A unique API endpoint that represents the node
external_fqdn | An automatically generated FQDN for the node. Containers deployed on this node will inherit this FQDN.
state | The state of the node. See the below table for a list of possible states.
node_cluster | The resource URI of the node cluster to which this node belongs to (if applicable)
node_type | The resource URI of the node type used for the node
region | The resource URI of the region where the node is deployed
docker_execdriver | Docker’s execution driver used in the node
docker_graphdriver | Docker’s storage driver used in the node
docker_version | Docker’s version used in the node
cpu | Node number of CPUs
disk | Node storage size in GB
memory | Node memory in MB
current_num_containers | The actual number of containers deployed in this node
last_seen | Date and time of the last time the node was contacted by Docker Cloud
public_ip | The public IP allocated to the node
tunnel | If the node does not accept incoming connections to port 2375, the address of the reverse tunnel to access the docker daemon, or `null` otherwise
deployed_datetime | The date and time when this node cluster was deployed
destroyed_datetime | The date and time when this node cluster was terminated (if applicable)
tags | List of tags to identify the node when deploying services (see Tags for more information)
nickname | A user-friendly name for the node (`external_fqdn` by default)

### Node states

State | Description
--- | ---
Deploying | The node is being deployed in the cloud provider. No actions allowed in this state.
Deployed | The node is deployed and provisioned and is ready to deploy containers. Possible actions in this state: `terminate`, `docker-upgrade`.
Unreachable | The node is deployed but Docker Cloud cannot connect to the docker daemon. Possible actions in this state: `health-check` and `terminate`.
Upgrading | The node docker daemon is being upgraded. No actions allowed in this state.
Terminating | The node is being terminated in the cloud provider. No actions allowed in this state.
Terminated | The node has been terminated and is no longer present in the cloud provider. No actions allowed in this state.

## List all nodes

    import dockercloud

    nodes = dockercloud.Node.list()

    import "github.com/docker/go-dockercloud/dockercloud"

    nodeList, err := dockercloud.ListNodes()

    if err != nil {
      log.Println(err)
    }

    log.Println(nodeList)

    GET /api/infra/v1/node/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud node ls

Lists all current and recently terminated nodes. Returns a list of `Node` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/[optional_namespace/]node/`

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID
state | Filter by state. Possible values: `Deploying`, `Deployed`, `Unreachable`, `Upgrading`, `Terminating`, `Terminated`
node_cluster | Filter by resource URI of the target node cluster
node_type | Filter by resource URI of the target node type
region | Filter by resource URI of the target region
docker_version | Filter by Docker engine version running in the nodes

## Get an existing node

    import dockercloud

    node = dockercloud.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    import "github.com/docker/go-dockercloud/dockercloud"

    node, err := dockercloud.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    log.Println(node)

    GET /api/infra/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud node inspect 7eaf7fff

Get all the details of an specific node

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/infra/v1/[optional_namespace/]node/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node to retrieve

## Update a node

    import dockercloud

    node = dockercloud.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    node.tags.add(["tag-1"])
    node.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    node, err := dockercloud.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
        log.Println(err)
    }

    if err = node.Update(dockercloud.Node{Tags: []string{{Name: "tag-1"}}}); err != nil {
                log.Println(err)
    }

    PATCH /api/infra/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    {"tags": [{"name": "tag-1"}], "nickname": "dev node"}

    docker-cloud tag add -t tag-1 7eaf7fff
    docker-cloud tag set -t tag-2 7eaf7fff

Names the node with a user-friendly name and/or replaces the old tags for the new list provided.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`PATCH /api/infra/v1/[optional_namespace/]node/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node to retrieve

### JSON Parameters

Parameter | Description
--- | ---
nickname | (optional) A user-friendly name for the node (`external_fqdn` by default)
tags | (optional) List of tags the node will have. This operation replaces the user tag list.

## Upgrade Docker Daemon

    import dockercloud

    node = dockercloud.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    node.upgrade_docker()

    import "github.com/docker/go-dockercloud/dockercloud"

    node, err := dockercloud.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = node.Upgrade(); err != nil {
           log.Println(err)
       }

    POST /api/infra/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/docker-upgrade/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud node upgrade 7eaf7fff

Upgrades the docker daemon of the node. This will restart your containers on that node. See Docker upgrade for more information.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/infra/v1/[optional_namespace/]node/(uuid)/docker-upgrade/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node to upgrade

## Perform a health check of a node

    POST /api/infra/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/health-check/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Tests connectivity between Docker Cloud and the node. Updates the node status to `Deployed` if the check was successful, or to `Unreachable` otherwise.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/infra/v1/[optional_namespace/]node/(uuid)/health-check/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node to perform the health check to

## Terminate a node

    import dockercloud

    node = dockercloud.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    node.delete()

    DELETE /api/infra/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    node, err := dockercloud.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = node.Terminate(); err != nil {
       log.Println(err)
    }

    docker-cloud node rm 7eaf7fff

Terminates the specified node.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`DELETE /api/infra/v1/[optional_namespace/]node/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the node to terminate

# Registries

## Registry

> Example

    {
      "host": "registry-1.docker.io",
      "is_docker_registry": true,
      "is_ssl": true,
      "name": "Docker Hub",
      "port": 443,
      "resource_uri": "/api/repo/v1/user_namespace/registry/registry-1.docker.io/"
    }

Represents a registry where repositories are hosted.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
resource_uri | A unique API endpoint that represents the registry
name | Human-readable name of the registry
host | FQDN of the registry, i.e. `registry-1.docker.io`
is_docker_registry | Whether this registry is run by Docker
is_ssl | Whether this registry has SSL activated or not
port | The port number where the registry is listening to

## List all registries

    GET /api/repo/v1/registry/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Lists all current registries. Returns a list of `Registry` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/repo/v1/[optional_namespace/]registry/`

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID
name | Filter by registry name
host | Filter by registry host
is_docker_registry | Filter by whether the registry is run by Docker or not. Possible values: ‘true’ or 'false’

## Get an existing registry

    GET /api/repo/v1/registry/registry-1.docker.io/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Gets all the details of an specific registry

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/v1/[optional_namespace/]registry/(host)/`

### Path Parameters

Parameter | Description
--- | ---
host | The host of the registry to retrieve

# External Repositories

## External Repository

> Example

    {
      "in_use": false,
      "name": "my.registry.com/myrepo",
      "registry": "/api/repo/v1/user_namespace/registry/my.registry.com/",
      "resource_uri": "/api/repo/v1/user_namespace/repository/my.registry.com/myrepo/",
    }

The `repository` endpoint is used to add and remove existing repositories on third party registries to be used in deployments and builds.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
resource_uri | A unique API endpoint that represents the repository
name | Name of the repository, i.e. `my.registry.com/myrepo`
in_use | If the image is being used by any of your services
registry | Resource URI of the registry where this image is hosted

## List all external repositories

    import dockercloud

    repositories = dockercloud.Repository.list()

    GET /api/repo/v1/repository/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    repositoriesList, err := dockercloud.ListRepositories()

    if err != nil {
        log.Println(err)
    }

    log.Pringln(repositoriesList)

    docker-cloud repository ls

Lists all added repositories from third party registries. Returns a list of `Repository` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/repo/v1/[optional_namespace/]repository/`

### Query Parameters

Parameter | Description
--- | ---
name | Filter by image name
registry | Filter by resource URI of the target repository registry

## Add a new external repository

    import dockercloud

    repository = dockercloud.Repository.create(name="registry.local/user1/image1", username=username, password=password)
    repository.save()

    POST /api/repo/v1/repository/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {"name": "registry.local/user1/image1", "username": "username", "password": "password"}

    import "github.com/docker/go-dockercloud/dockercloud"

    image, err := dockercloud.CreateImage(dockercloud.ImageCreateRequest{
      Name: "registry.local/user1/image1",
      Username: "username",
      Password: "password"
    })

    docker-cloud repository register -u username -p password registry.local/user1/image1

Adds an existing repository on a third party registry.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/repo/v1/[optional_namespace/]repository/`

### JSON Parameters

Parameter | Description
--- | ---
name | Name of the repository, i.e. ‘my.registry.com/myrepo’
username | Username to authenticate with the third party registry
password | Password to authenticate with the third party registry

## Get an external repository details

    import dockercloud

    repository = dockercloud.Repository.fetch("registry.local/user1/image1")

    GET /api/repo/v1/repository/registry.local/user1/image1/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    repository, err = dockercloud.GetRepository("registry.local/user1/image1")

    if err != nil {
        log.Println(err)
    }

    log.Println(repository)

    docker-cloud repository inspect registry.local/user1/image1

Gets all the details of an specific repository

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/repo/v1/[optional_namespace/]repository/(name)/`

### Path Parameters

Parameter | Description
--- | ---
name | The name of the repository to retrieve

## Update credentials of an external repository

    import dockercloud

    repository = dockercloud.Repository.fetch("registry.local/user1/image1")
    repository.username = "new username"
    repository.password = "new password"
    repository.save()

    PATCH /api/repo/v1/repository/registry.local/user1/image1/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {"username": "username", "password": "password"}

    docker-cloud repository update -n "new username" -p "new password" registry.local/user1/image1

Updates the external repository credentials.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`PATCH /api/repo/v1/[optional_namespace/]repository/(name)/`

### Path Parameters

Parameter | Description
--- | ---
name | The name of the repository to update

### JSON Parameters

Parameter | Description
--- | ---
username | Username to authenticate with the private registry
password | Password to authenticate with the private registry

## Remove an external repository

    import dockercloud

    repository = dockercloud.Repository.fetch("registry.local/user1/image1")
    repository.delete()

    DELETE /api/repo/v1/repository/registry.local/user1/image1/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    repository, err = dockercloud.GetRepository("registry.local/user1/image1")

    if err != nil {
        log.Println(err)
    }

    repository.Remove()

    docker-cloud repository rm registry.local/user1/image1

Removes the external repository from Docker Cloud. It won’t remove the repository from the third party registry where it’s stored.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`DELETE /api/repo/v1/[optional_namespace/]repository/`

### Path Parameters

Parameter | Description
--- | ---
name | The name of the external repository to remove

# Stacks

## Stack

> Example

    {
      "deployed_datetime": "Mon, 13 Oct 2014 11:01:43 +0000",
      "destroyed_datetime": null,
      "nickname": "deployment stack",
      "name": "dockercloud-app",
      "resource_uri": "/api/app/v1/user_namespace/stack/7fe7ec85-58be-4904-81da-de2219098d7c/",
      "services": [
        "/api/app/v1/user_namespace/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/"
      ],
      "state": "Running",
      "synchronized": true,
      "uuid": "09cbcf8d-a727-40d9-b420-c8e18b7fa55b"
    }

A stack is a logical grouping of closely related services, that may be linked with one another.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
uuid | A unique identifier for the stack generated automatically on creation
resource_uri | A unique API endpoint that represents the stack
name | A user provided name for the stack.
state | The state of the stack (see table `Stack states` below)
synchronized | Flag indicating if the current stack definition is synchronized with their services.
services | List of service resource URIs belonging to the stack
deployed_datetime | The date and time of the last deployment of the stack (if applicable, `null` otherwise)
destroyed_datetime | The date and time of the `terminate` operation on the stack (if applicable, `null` otherwise)
nickname | A user-friendly name for the stack (`name` by default)

### Stack states

State | Description
--- | ---
Not Running | The stack has been created and has no deployed services yet. Possible actions in this state: `start`, `terminate`.
Starting | All services for the stack are either starting or already running. No actions allowed in this state.
Running | All services for the service are deployed and running. Possible actions in this state: `redeploy`, `terminate`.
Partly running | One or more services of the stack are deployed and running. Possible actions in this state: `redeploy`, `terminate`.
Stopping | All services for the stack are either stopping or already stopped. No actions allowed in this state.
Stopped | All services for the service are stopped. Possible actions in this state: `start`, `redeploy`, `terminate`.
Redeploying | The stack is redeploying all its services with the updated configuration. No actions allowed in this state.
Terminating | All services for the stack are either being terminated or already terminated. No actions allowed in this state.
Terminated | The stack and all its services have been terminated. No actions allowed in this state.

## List all stacks

    import dockercloud

    stacks = dockercloud.Stack.list()

    import "github.com/docker/go-dockercloud/dockercloud"

    stackList, err := dockercloud.ListStacks()

    if err != nil {
      log.Println(err)
    }

    log.Println(stackList)

    GET /api/app/v1/stack/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack ls

Lists all current and recently terminated stacks. Returns a list of `Stack` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]stack/`

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID
name | Filter by stack name

## Create a new stack

    import dockercloud

    stack = dockercloud.Stack.create(name="my-new-stack", services=[{"name": "hello-word", "image": "tutum/hello-world", "target_num_containers": 2}])
    stack.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.CreateStack(dockercloud.StackCreateRequest{Name: "my-new-stack", Services: []dockercloud.ServiceCreateRequest{{Image: "tutum/hello-world", Name: "test", Target_num_containers: 2}}})

    if err != nil {
      log.Println(err)
    }

    log.Println(stack)

    POST /api/app/v1/stack/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {
        "name": "my-new-stack",
        "services": [
            {
                "name": "hello-word",
                "image": "tutum/hello-world",
                "target_num_containers": 2,
                "linked_to_service": [
                    {
                        "to_service": "database",
                        "name": "DB"
                    }
                ]
            },
            {
                "name": "database",
                "image": "tutum/mysql"
            }
        ]
    }

    docker-cloud stack create --name hello-world -f docker-compose.yml

Creates a new stack without starting it. Note that the JSON syntax is abstracted by both, the Docker Cloud CLI and our UI, in order to use Stack YAML files.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]stack/`

### JSON Parameters

Parameter | Description
--- | ---
name | (required) A human-readable name for the stack, i.e. `my-hello-world-stack`
nickname | (optional) A user-friendly name for the stack (`name` by default)
services | (optional) List of services belonging to the stack. Each service accepts the same parameters as a Create new service operation (default: `[]`) plus the ability to refer “links” and “volumes-from” by the name of another service in the stack (see example).

## Export an existing stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.export()

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    if err != nil {
      log.Println(err)
    }

    if err = stack.Export(); err != nil {
       log.Println(err)
    }

    GET /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/export/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack export 46aca402

Get a JSON representation of the stack following the Stack YAML representation.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]stack/(uuid)/export/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to retrieve

## Get an existing stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    if err != nil {
      log.Println(err)
    }

    log.Println(stack)

    GET /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack inspect 46aca402-2109-4a70-a378-760cfed43816

Get all the details of an specific stack

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]stack/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to retrieve

## Update an existing stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.services = {"services": [{"name": "hello-word", "image": "tutum/hello-world", "target_num_containers": 2}]}
    stack.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    if err != nil {
      log.Println(err)
    }

    if err = stack.Update(dockercloud.StackCreateRequest{Services: []dockercloud.ServiceCreateRequest{{Name: "hello-world", Image: "tutum/hello-world", Target_num_containers: 2}}}); err != nil {
       log.Println(err)
    }

    PATCH /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {
        "services": [
            {
                "name": "hello-word",
                "image": "tutum/hello-world",
                "target_num_containers": 3,
                "linked_to_service": [
                    {
                        "to_service": "database",
                        "name": "DB"
                    }
                ]
            },
            {
                "name": "database",
                "image": "tutum/mysql"
            }
        ]
    }

    docker-cloud stack update -f docker-compose.yml 46aca402

Updates the details of every service in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`PATCH /api/app/v1/[optional_namespace/]stack/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to update

### JSON Parameters

Parameter | Description
--- | ---
services | (optional) List of services belonging to the stack. Each service accepts the same parameters as a Update an existing service operation (default: `[]`) plus the ability to refer “links” and “volumes-from” by the name of another service in the stack (see example).

## Stop a stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.stop()

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    if err != nil {
      log.Println(err)
    }

    if err = stack.Stop(); err != nil {
       log.Println(err)
    }

    POST /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/stop/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack stop 46aca402-2109-4a70-a378-760cfed43816

Stops the services in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]stack/(uuid)/stop/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to stop

## Start a stack

    import dockercloud

    stack = dockercloud.Stack.fetch()
    stack.start()

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    if err != nil {
      log.Println(err)
    }

    if err = stack.Start(); err != nil {
       log.Println(err)
    }

    POST /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/start/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack start 46aca402

Starts the services in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]stack/(uuid)/start/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to start

## Redeploy a stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.redeploy()

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    if err != nil {
      log.Println(err)
    }

    //Redeploy(dockercloud.ReuseVolumesOption{Reuse: true}) to reuse the existing volumes
    //Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}) to not reuse the existing volumes
    if err = stack.Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}); err != nil {
       log.Println(err)
    }

    POST /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/redeploy/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack redeploy 46aca402

Redeploys all the services in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]stack/(uuid)/redeploy/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to redeploy

### Query Parameters

Parameter | Description
--- | ---
reuse_volumes | Wheather to reuse container volumes for this redeploy operation or not (default: `true`).

## Terminate a stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.delete()

    import "github.com/docker/go-dockercloud/dockercloud"

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    if err != nil {
      log.Println(err)
    }

    if err = stack.Terminate(); err != nil {
       log.Println(err)
    }

    DELETE /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack terminate 46aca402

Terminate all the services in a the stack and the stack itself.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`DELETE /api/app/v1/[optional_namespace/]stack/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to terminate

# Services

## Service

> Example

    {
      "autodestroy": "OFF",
      "autoredeploy": false,
      "autorestart": "ON_FAILURE",
      "bindings": [
        {
            "host_path": null,
            "container_path": "/tmp",
            "rewritable": true,
            "volumes_from": null
        },
        {
            "host_path": "/etc",
            "container_path": "/etc",
            "rewritable": true,
            "volumes_from": null
        },
        {
            "host_path": null,
            "container_path": null,
            "rewritable": true,
            "volumes_from": "/api/app/v1/user_namespace/service/2f4f54e5-9d3b-4ac1-85ad-a2d4ff25a179/"
        }
      ],
      "cap_add": [
        "ALL"
      ],
      "cap_drop": [
        "NET_ADMIN",
        "SYS_ADMIN"
      ],
      "container_envvars": [
        {
          "key": "DB_PASS",
          "value": "test"
        }
      ],
      "container_ports": [
        {
          "endpoint_uri": "http://wordpress-stackable.admin.srv.dockerapp.io:80/",
          "inner_port": 80,
          "outer_port": 80,
          "port_name": "http",
          "protocol": "tcp",
          "published": true
        }
      ],
      "containers": [
        "/api/app/v1/user_namespace/container/6f8ee454-9dc3-4387-80c3-57aac1be3cc6/",
        "/api/app/v1/user_namespace/container/fdf9c116-7c08-4a60-b0ce-c54ca72c2f25/"
      ],
      "cpu_shares": 100,
      "cpuset": "0,1",
      "cgroup_parent": "m-executor-abcd",
      "current_num_containers": 2,
      "deployed_datetime": "Mon, 13 Oct 2014 11:01:43 +0000",
      "deployment_strategy": "EMPTIEST_NODE",
      "destroyed_datetime": null,
      "devices": [
        "/dev/ttyUSB0:/dev/ttyUSB0"
      ],
      "dns": [
        "8.8.8.8"
      ],
      "dns_search": [
        "example.com"
      ],
      "domainname": "domainname",
      "entrypoint": "",
      "extra_hosts": [
        "onehost:50.31.209.229"
      ],
      "hostname": "hostname",
      "image_name": "tutum/wordpress-stackable:latest",
      "nickname": "wordpress-stackable",
      "labels": {
        "com.example.description": "Accounting webapp",
        "com.example.department": "Finance",
        "com.example.label-with-empty-value": ""
      },
      "link_variables": {
        "WORDPRESS_STACKABLE_1_ENV_DB_HOST": "**LinkMe**",
        "WORDPRESS_STACKABLE_1_ENV_DB_NAME": "wordpress",
        "WORDPRESS_STACKABLE_1_ENV_DB_PASS": "szVaPz925B7I",
        "WORDPRESS_STACKABLE_1_ENV_DB_PORT": "**LinkMe**",
        "WORDPRESS_STACKABLE_1_ENV_DB_USER": "admin",
        "WORDPRESS_STACKABLE_1_ENV_DEBIAN_FRONTEND": "noninteractive",
        "WORDPRESS_STACKABLE_1_ENV_HOME": "/",
        "WORDPRESS_STACKABLE_1_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "WORDPRESS_STACKABLE_1_PORT": "tcp://wordpress-stackable-1.admin.cont.dockerapp.io:49153",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP": "tcp://wordpress-stackable-1.admin.cont.dockerapp.io:49153",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_ADDR": "wordpress-stackable-1.admin.cont.dockerapp.io",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_PORT": "49153",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_PROTO": "tcp",
        "WORDPRESS_STACKABLE_2_ENV_DB_HOST": "**LinkMe**",
        "WORDPRESS_STACKABLE_2_ENV_DB_NAME": "wordpress",
        "WORDPRESS_STACKABLE_2_ENV_DB_PASS": "szVaPz925B7I",
        "WORDPRESS_STACKABLE_2_ENV_DB_PORT": "**LinkMe**",
        "WORDPRESS_STACKABLE_2_ENV_DB_USER": "admin",
        "WORDPRESS_STACKABLE_2_ENV_DEBIAN_FRONTEND": "noninteractive",
        "WORDPRESS_STACKABLE_2_ENV_HOME": "/",
        "WORDPRESS_STACKABLE_2_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "WORDPRESS_STACKABLE_2_PORT": "tcp://wordpress-stackable-2.admin.cont.dockerapp.io:49154",
        "WORDPRESS_STACKABLE_2_PORT_80_TCP": "tcp://wordpress-stackable-2.admin.cont.dockerapp.io:49154",
        "WORDPRESS_STACKABLE_2_PORT_80_TCP_ADDR": "wordpress-stackable-2.admin.cont.dockerapp.io",
        "WORDPRESS_STACKABLE_2_PORT_80_TCP_PORT": "49154",
        "WORDPRESS_STACKABLE_2_PORT_80_TCP_PROTO": "tcp",
        "WORDPRESS_STACKABLE_ENV_DB_HOST": "**LinkMe**",
        "WORDPRESS_STACKABLE_ENV_DB_NAME": "wordpress",
        "WORDPRESS_STACKABLE_ENV_DB_PASS": "szVaPz925B7I",
        "WORDPRESS_STACKABLE_ENV_DB_PORT": "**LinkMe**",
        "WORDPRESS_STACKABLE_ENV_DB_USER": "admin",
        "WORDPRESS_STACKABLE_ENV_DEBIAN_FRONTEND": "noninteractive",
        "WORDPRESS_STACKABLE_ENV_HOME": "/",
        "WORDPRESS_STACKABLE_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "WORDPRESS_STACKABLE_PORT": "tcp://wordpress-stackable-1.admin.cont.dockerapp.io:49153",
        "WORDPRESS_STACKABLE_PORT_80_TCP": "tcp://wordpress-stackable-1.admin.cont.dockerapp.io:49153",
        "WORDPRESS_STACKABLE_PORT_80_TCP_ADDR": "wordpress-stackable-1.admin.cont.dockerapp.io",
        "WORDPRESS_STACKABLE_PORT_80_TCP_PORT": "49153",
        "WORDPRESS_STACKABLE_PORT_80_TCP_PROTO": "tcp",
        "WORDPRESS_STACKABLE_DOCKERCLOUD_API_URL": "https://cloud.docker.com/api/app/v1/user_namespace/service/adeebc1b-1b81-4af0-b8f2-cefffc69d7fb/"
      },
      "linked_from_service": [],
      "linked_to_service": [
        {
          "from_service": "/api/app/v1/user_namespace/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/",
          "name": "DB",
          "to_service": "/api/app/v1/user_namespace/service/72f175bd-390b-46e3-9463-830aca32ce3e/"
        }
      ],
      "mac_address": "02:42:ac:11:65:43",
      "memory": 2048,
      "memory_swap": 8192,
      "name": "wordpress-stackable",
      "net": "bridge",
      "privileged": false,
      "public_dns": "wordpress-stackable.admin.svc.dockerapp.io",
      "read_only": true,
      "resource_uri": "/api/app/v1/user_namespace/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/",
      "roles": ["global"],
      "run_command": "/run-wordpress.sh",
      "running_num_containers": 1,
      "security_opt": [
      ],
      "sequential_deployment": false,
      "started_datetime": "Mon, 13 Oct 2014 11:01:43 +0000",
      "state": "Partly running",
      "stack": "/api/app/v1/user_namespace/stack/46aca402-2109-4a70-a378-760cfed43816/",
      "stdin_open": false,
      "stopped_datetime": null,
      "stopped_num_containers": 0,
      "synchronized": true,
      "tags": [
            {"name": "tag_one"},
            {"name": "tag-two"},
            {"name": "tagthree3"}
      ],
      "target_num_containers": 2,
      "tty": false,
      "user": "root",
      "uuid": "09cbcf8d-a727-40d9-b420-c8e18b7fa55b",
      "working_dir": "/app"
    }

A service is a template used to deploy one or more containers.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
uuid | A unique identifier for the service generated automatically on creation
resource_uri | A unique API endpoint that represents the service
image_name | The Docker image name and tag used for the service containers
name | A user provided name for the service. This name will be inherited by the service containers and will be used in endpoint URLs, environment variable names, etc.
public_dns | An external FQDN that resolves to all IPs of the nodes where the service containers are running on (as an `A` record with multiple IP entries which will be used by clients in a round-robin fashion). If the service is not publishing any ports, this FQDN will fail to resolve.
state | The state of the service (see table `Service states` below)
net | Network mode to set on the containers (see table `Network Modes` below, more information ../../docker-cloud/apps/service-links/)
pid | Set the PID (Process) Namespace mode for the containers (more information ../../reference/run/#pid-settings-pid)
synchronized | Flag indicating if the current service definition is synchronized with the current containers.
deployed_datetime | The date and time of the last deployment of the service (if applicable, `null` otherwise)
started_datetime | The date and time of the last `start` operation on the service (if applicable, `null` otherwise)
stopped_datetime | The date and time of the last `stop` operation on the service (if applicable, `null` otherwise)
destroyed_datetime | The date and time of the `terminate` operation on the service (if applicable, `null` otherwise)
target_num_containers | The requested number of containers to deploy for the service
current_num_containers | The actual number of containers deployed for the service
running_num_containers | The actual number of containers deployed for the service in `Running` state
stopped_num_containers | The actual number of containers deployed for the service in `Stopped` state
stack | Resource URIs of the stack that the service belongs to
containers | List of resource URIs of the containers launched as part of the service
container_ports | List of ports to be published on the containers of this service (see table `Service Port attributes` below)
container_envvars | List of user-defined environment variables to set on the containers of the service, which will override the image environment variables (see table `Service Environment Variable attributes` below)
labels | Metadata in form of dictionary used for every container of this service
working_dir | Working directory for running binaries within a container of this service
user | Set the user used on containers of this service (`root` by default)
hostname | Set the hostname used on containers of this service
domainname | Set the domainname used on containers of this service
mac_address | Ethernet device’s MAC address used on containers of this service
cgroup_name | Optional parent cgroup used on containers of this service.
tty | If the containers of this service have the tty enable (`false` by default)
stdin_open | If the containers of this service have stdin opened (`false` by default)
dns | Custom DNS servers for containers of this service
dns_search | Custom DNS search domain for containers of this service
cap_add | Added capabilities for containers of this service
cap_drop | Dropped capabilities for containers of this service
devices | List of device mappings for containers of this service
extra_hosts | List of hostname mappings for containers of this service
secuirty_opt | Labeling scheme for containers of this service
entrypoint | Entrypoint to be set on the containers launched as part of the service, which will override the image entrypoint
run_command | Run command to be set on the containers launched as part of the service, which will override the image run command
sequential_deployment | Whether the containers for this service should be deployed in sequence, linking each of them to the previous containers (see Service scaling for more information)
cpu_shares | The relative CPU priority of the containers of the service (see Runtime Constraints on CPU and Memory for more information)
cpuset | CPUs in which to allow execution
memory | The memory limit of the containers of the service in MB (see Runtime Constraints on CPU and Memory for more information)
memory_swap | Total memory limit (memory + swap) of the containers of the service in MB
linked_from_service | A list of services that are linked to this one (see table `Related services attributes` below)
linked_to_service | A list of services that the service is linked to (see table `Related services attributes` below)
bindings | A list of volume bindings that the service has mounted (see table `Service binding attributes` below)
autorestart | Whether to restart the containers of the service automatically if they stop (see Crash recovery for more information)
autodestroy | Whether to terminate the containers of the service automatically if they stop (see Autodestroy for more information)
roles | List of Docker Cloud roles assigned to this service (see Service links for more information)
link_variables | List of environment variables that would be exposed in the containers if they are linked to this service
privileged | Whether to start the containers with Docker’s `privileged` flag set or not, which allows containers to access all devices on the host among other things (see Runtime privilege for more information)
read_only | Whether the filesystem of every service container is read-only or not (`false` by default)
deployment_strategy | Container distribution among nodes (see table `Deployment strategies` below and Deployment strategies for more information)
tags | List of tags to be used to deploy the service (see Tags for more information)
autoredeploy | Whether to redeploy the containers of the service when its image is updated in Docker Cloud registry (see Docker Cloud’s private registry for more information)
nickname | A user-friendly name for the service (`name` by default)

### Service binding attributes

Attribute | Description
--- | ---
host_path | The host path of the volume
container_path | The container path where the volume is mounted
rewritable | `true` is the volume has writable permissions
volumes_from | The resource URI of the service

### Service Port attributes

Attribute | Description
--- | ---
protocol | The protocol of the port, either `tcp` or `udp`
inner_port | The published port number inside the container
outer_port | The published port number in the node public network interface
port_name | Name of the service associated to this port
endpoint_uri | The URI of the service endpoint for this port
published | Whether the port has been published in the host public network interface or not. Non-published ports can only be accessed via links.

### Service Environment Variable attributes

Attribute | Description
--- | ---
key | The name of the environment variable
value | The value of the environment variable

### Related services attributes

Attribute | Description
--- | ---
name | The link name
from_service | The resource URI of the origin of the link
to_service | The resource URI of the target of the link

### Service states

State | Description
--- | ---
Not running | The service has been created and has no deployed containers yet. Possible actions in this state: `start`, `terminate`.
Starting | All containers for the service are either starting or already running. No actions allowed in this state.
Running | All containers for the service are deployed and running. Possible actions in this state: `stop`, `redeploy`, `terminate`.
Partly running | One or more containers of the service are deployed and running. Possible actions in this state: `stop`, `redeploy`, `terminate`.
Scaling | The service is either deploying new containers or destroying existing ones responding to a scaling request. No actions allowed in this state.
Redeploying | The service is redeploying all its containers with the updated configuration. No actions allowed in this state.
Stopping | All containers for the service are either stopping or already stopped. No actions allowed in this state.
Stopped | All containers for the service are stopped. Possible actions in this state: `start`, `redeploy`, `terminate`.
Terminating | All containers for the service are either being terminated or already terminated. No actions allowed in this state.
Terminated | The service and all its containers have been terminated. No actions allowed in this state.

### Deployment strategies

Strategy | Description
--- | ---
EMPTIEST_NODE | It will deploy containers to the node with the lower total amount of running containers (default).
HIGH_AVAILABILITY | It will deploy containers to the node with the lower amount of running containers of the same service.
EVERY_NODE | It will deploy one container on every node. The service won’t be able to scale manually. New containers will be deployed to new nodes automatically.

### Network Modes

Strategy | Description
--- | ---
bridge | Creates a new network stack for the container on the docker bridge.
host | Uses the host network stack inside the container.

## List all services

    import dockercloud

    services = dockercloud.Service.list()

    import "github.com/docker/go-dockercloud/dockercloud"

    serviceList, err := dockercloud.ListServices()

    if err != nil {
      log.Println(err)
    }

    log.Println(serviceList)

    GET /api/app/v1/service/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud service ps

Lists all current and recently terminated services. Returns a list of `Service` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]service/`

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID
state | Filter by state. Possible values: `Not running`, `Starting`, `Running`, `Partly running`, `Scaling`, `Redeploying`, `Stopping`, `Stopped`, `Terminating`, `Terminated`
name | Filter by service name
stack | Filter by resource URI of the target stack.

## Create a new service

    import dockercloud

    service = dockercloud.Service.create(image="tutum/hello-world", name="my-new-app", target_num_containers=2)
    service.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.CreateService(dockercloud.ServiceCreateRequest{Image: "tutum/hello-world",  Name: "my-new-app", Target_num_containers: 2})

    if err != nil {
      log.Println(err)
    }

    log.Println(service)

    POST /api/app/v1/service/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {"image": "tutum/hello-world", "name": "my-new-app", "target_num_containers": 2}

    docker-cloud service create -t 2 --name my-new-app tutum/hello-world

Creates a new service without starting it.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]service/`

### JSON Parameters

Parameter | Description
--- | ---
image | (required) The image used to deploy this service in docker format, i.e. `tutum/hello-world`
name | (optional) A human-readable name for the service, i.e. `my-hello-world-app` (default: `image` without namespace)
target_num_containers | (optional) The number of containers to run for this service initially (default: 1)
run_command | (optional) The command used to start the containers of this service, overriding the value specified in the image, i.e. `/run.sh` (default: `null`)
entrypoint | (optional) The command prefix used to start the containers of this service, overriding the value specified in the image, i.e. `/usr/sbin/sshd` (default: `null`)
container_ports | (optional) An array of objects with port information to be published in the containers for this service, which will be added to the image port information, i.e. `[{"protocol": "tcp", "inner_port": 80, "outer_port": 80}]` (default: `[]`) (See table `Service Port attributes` below)
container_envvars | (optional) An array of objects with environment variables to be added in the service containers on launch (overriding any image-defined environment variables), i.e. `[{"key": "DB_PASSWORD", "value": "mypass"}]` (default: `[]`) (See table `Service Environment Variable attributes` below)
linked_to_service | (optional) An array of service resource URIs to link this service to, including the link name, i.e. `[{"to_service": "/api/app/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "name": "db"}]` (default: `[]`) (See table `Related services attributes` below)
bindings | (optional) An array of bindings this service has to mount, i.e. `[{"volumes_from": "/api/app/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "rewritable": true}]` (default: `[]`) (See table `Related bindings attributes` below)
autorestart | (optional) Whether the containers for this service should be restarted if they stop, i.e. `ALWAYS` (default: `OFF`, possible values: `OFF`, `ON_FAILURE`, `ALWAYS`) (see Crash recovery for more information)
autodestroy | (optional) Whether the containers should be terminated if they stop, i.e. `OFF` (default: `OFF`, possible values: `OFF`, `ON_SUCCESS`, `ALWAYS`) (see Autodestroy for more information)
sequential_deployment | (optional) Whether the containers should be launched and scaled in sequence, i.e. `true` (default: `false`) (see Service scaling for more information)
roles | (optional) A list of Docker Cloud API roles to grant the service, i.e. `["global"]` (default: `[]`, possible values: `global`) (see Service links for more information)
privileged | (optional) Whether to start the containers with Docker’s `privileged` flag set or not, i.e. `false` (default: `false`) (see Runtime privilege for more information)
deployment_strategy | (optional) Container distribution among nodes (default: `EMPTIEST_NODE`, see table `Deployment strategies` above and Deployment strategies for more information)
tags | (optional) A list of tags to be used to deploy the service (see Tags for more information) (default: `[]`)
autoredeploy | (optional) Whether to redeploy the containers of the service when its image is updated in Docker Cloud registry (default: `false`) (see Docker Cloud’s private registry for more information)
net | (optional) Set the network mode to the containers (default: `bridge`, possible values: `bridge`, `host`)
pid | (optional) Set the PID (Process) Namespace mode for the containers (default: `none` value, possible values: `none`, `host`)
working_dir | (optional) Working directory for running binaries within a container of this service (default: `/`)
nickname | (optional) A user-friendly name for the service (`name` by default)

### Related bindings attributes

Attribute | Description
--- | ---
host_path | (optional) The host path of the volume
container_path | (required if `volumes_from` is omitted) The container path where the volume is mounted
rewritable | (optional) `true` is the volume has writable permissions (default: `true`)
volumes_from | (required if `container_path` is omitted) The resource URI of the service

### Service Port attributes

Attribute | Description
--- | ---
protocol | (required) The protocol of the port, either `tcp` or `udp`
inner_port | (required) The port number inside the container to be published
outer_port | (optional) The port number in the node public network interface to be published (default: dynamic allocation if `published` is `true`)
published | (optional) Whether to publish the port in the host public network interface or not. Non-published ports can only be accessed via links. (default: `false`)

### Service Environment Variable attributes

Attribute | Description
--- | ---
key | (required) The name of the environment variable
value | (required) The value of the environment variable

### Related services attributes

Attribute | Description
--- | ---
to_service | (required) The resource URI of the target of the link
name | (optional) The link name

## Get an existing service

    import dockercloud

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    log.Println(service)

    GET /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud service inspect 7eaf7fff

Get all the details of an specific service

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]service/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to retrieve

## Get the logs of a service

> Example log line

    {
        "type": "log",
        "source": "wordpress-stackable-1",
        "log": "Log line from the container indicated by 'source'",
        "streamType": "stdout",
        "timestamp": 1433779324
    }

    import dockercloud

    def log_handler(message):
        print message

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    service.logs(tail=300, follow=True, log_handler=log_handler)

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    c := make(chan Logs)

    go service.Logs(c)
        for {
            s := <-c
            log.Println(s)
        }

    GET /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
    Host: ws.cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Connection: Upgrade
    Upgrade: websocket

    docker-cloud service logs 7eaf7fff

Get the aggregated logs of all the containers of the service.

### Endpoint Type

Available in Docker Cloud’s STREAM API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]service/(uuid)/logs/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to retrieve logs

### Query Parameters

Parameter | Description
--- | ---
tail | Number of lines to show from the end of the logs (default: `300`)
follow | Whether to stream logs or close the connection immediately (default: true)

## Update an existing service

    import dockercloud

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    service.target_num_containers = 3
    service.tags.append({"name":"tag-1"})
    service.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = service.Update(dockercloud.ServiceCreateRequest{Target_num_containers: 3}); err != nil {
       log.Println(err)
    }

    PATCH /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {"autorestart": "ON_FAILURE", "autodestroy": "OFF", "container_envvars": [{"key": "DB_PASSWORD", "value": "mypass"}],
    "container_ports": [{"protocol": "tcp", "inner_port": 80, "outer_port": 80}], "cpu_shares": 512,
    "entrypoint": "/usr/sbin/sshd", "image": "tutum/hello-world",
    "linked_to_service": [{"to_service": "/api/app/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "name": "db"}],
    "memory": 2048, "privileged": True, "roles": ["global"], "run_command": "/run.sh", "sequential_deployment": False,
    "tags": [{"name": "tag-1"}], "target_num_containers": 3, "autoredeploy": False}

    docker-cloud service scale 7eaf7fff 3
    docker-cloud tag add -t tag-1 7eaf7fff
    docker-cloud tag set -t tag-2 7eaf7fff

Updates the service details.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`PATCH /api/app/v1/[optional_namespace/]service/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to update

### JSON Parameters

Parameter | Description
--- | ---
autorestart | (optional) Whether the containers for this service should be restarted if they stop, i.e. `ALWAYS` (possible values: `OFF`, `ON_FAILURE`, `ALWAYS`) (see Crash recovery for more information)
autodestroy | (optional) Whether the containers should be terminated if they stop, i.e. `OFF` (possible values: `OFF`, `ON_SUCCESS`, `ALWAYS`) (see Autodestroy for more information)
container_envvars | (optional) An array of objects with environment variables to be added in the service containers on launch (overriding any image-defined environment variables), i.e. `[{"key": "DB_PASSWORD", "value": "mypass"}]` (See table `Service Environment Variable attributes`)
container_ports | (optional) An array of objects with port information to be published in the containers for this service, which will be added to the image port information, i.e. `[{"protocol": "tcp", "inner_port": 80, "outer_port": 80}]` (See table `Service Port attributes`)
cpu_shares | (optional) The relative CPU priority of the containers the service describes (see Runtime Constraints on CPU and Memory for more information)
entrypoint | (optional) The command prefix used to start the containers of this service, overriding the value specified in the image, i.e. `/usr/sbin/sshd`
image | (optional) The image used to deploy this service in docker format, i.e. `tutum/hello-world`, `tutum/ubuntu:5.6`. If no tag is indicated, it will be set to `latest` by default
linked_to_service | (optional) An array of service resource URIs to link this service to, including the link name, i.e. `[{"to_service": "/api/app/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "name": "db"}]` (See table `Related services attributes` below)
memory | (optional) The memory limit of the containers of the service in MB (see Runtime Constraints on CPU and Memory for more information)
privileged | (optional) Whether to start the containers with Docker’s `privileged` flag set or not, i.e. `false` (see Runtime privilege for more information)
roles | (optional) A list of Docker Cloud API roles to grant the service, i.e. `["global"]` (possible values: `global`) (see Service links for more information)
run_command | (optional) The command used to start the containers of this service, overriding the value specified in the image, i.e. `/run.sh`
sequential_deployment | (optional) Whether the containers should be launched and scaled in sequence, i.e. `true` (see Service scaling for more information)
tags | (optional) List of new tags the service will have. This operation replaces the tag list
target_num_containers | (optional) The number of containers to scale this service to
deployment_strategy | (optional) Container distribution among nodes. A service cannot be updated to or from a deployment strategy of `EVERY_NODE`. (See table `Deployment strategies` above and Deployment strategies for more information)
autoredeploy | Whether to redeploy the containers of the service when its image is updated in Docker Cloud registry (see Docker Cloud’s private registry for more information)
net | (optional) Set the network mode to the containers (default: `bridge`, possible values: `bridge`, `host`)
pid | (optional) Set the PID (Process) Namespace mode for the containers (default: `none` value, possible values: `none`, `host`)
working_dir | (optional) Working directory for running binaries within a container of this service (default: `/`)
nickname | (optional) A user-friendly name for the service (`name` by default)

## Start a service

    import dockercloud

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    service.start()

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = service.Start(); err != nil {
       log.Println(err)
    }

    POST /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud service start 7eaf7fff

Starts all containers in a stopped or partly running service.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]service/(uuid)/start/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to start

## Stop a service

    import dockercloud

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    service.stop()

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = service.Stop(); err != nil {
       log.Println(err)
    }

    POST /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/stop/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud service stop 7eaf7fff

Stops all containers in a running or partly running service.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]service/(uuid)/stop/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to stop

## Scale a service

    import dockercloud

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    service.target_num_containers = 3
    service.save()
    service.scale()

    POST /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/scale/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud service scale 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce 3

Scales the service to its current `target_num_containers` field.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]service/(uuid)/scale/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to scale

## Redeploy a service

    import dockercloud

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    service.redeploy()

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    //Redeploy(dockercloud.ReuseVolumesOption{Reuse: true}) to reuse the existing volumes
    //Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}) to not reuse the existing volumes
    if err = service.Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}); err != nil {
       log.Println(err)
    }

    POST /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/redeploy/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud service redeploy 7eaf7fff

Redeploys all containers in the service with the current service configuration.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]service/(uuid)/redeploy/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to redeploy

### Query Parameters

Parameter | Description
--- | ---
reuse_volumes | Wheather to reuse container volumes for this redeploy operation or not (default: `true`).

## Terminate a service

    import dockercloud

    service = dockercloud.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    service.delete()

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    if err = service.Terminate(); err != nil {
       log.Println(err)
    }

    DELETE /api/app/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud service terminate 7eaf7fff

Terminate all the containers in a service and the service itself. This is not reversible. All the data stored in all containers of the service will be permanently deleted.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`DELETE /api/app/v1/[optional_namespace/]service/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service to terminate

# Containers

## Container

> Example

    {
        "autodestroy": "OFF",
        "autorestart": "OFF",
        "bindings": [
            {
                "volume": "/api/infra/v1/user_namespace/volume/1863e34d-6a7d-4945-aefc-8f27a4ab1a9e/",
                "host_path": null,
                "container_path": "/data",
                "rewritable": true
            },
            {
                "volume": null,
                "host_path": "/etc",
                "container_path": "/etc",
                "rewritable": true
            }
        ],
        "cap_add": [
            "ALL"
        ],
        "cap_drop": [
            "NET_ADMIN",
            "SYS_ADMIN"
        ],
        "container_envvars": [
            {
                "key": "DB_1_ENV_DEBIAN_FRONTEND",
                "value": "noninteractive"
            },
            {
                "key": "DB_1_ENV_MYSQL_PASS",
                "value": "**Random**"
            },
            {
                "key": "DB_1_ENV_MYSQL_USER",
                "value": "admin"
            },
            {
                "key": "DB_1_ENV_PATH",
                "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
            },
            {
                "key": "DB_1_ENV_REPLICATION_MASTER",
                "value": "**False**"
            },
            {
                "key": "DB_1_ENV_REPLICATION_PASS",
                "value": "replica"
            },
            {
                "key": "DB_1_ENV_REPLICATION_SLAVE",
                "value": "**False**"
            },
            {
                "key": "DB_1_ENV_REPLICATION_USER",
                "value": "replica"
            },
            {
                "key": "DB_1_PORT",
                "value": "tcp://172.16.0.3:3306"
            },
            {
                "key": "DB_1_PORT_3306_TCP",
                "value": "tcp://172.16.0.3:3306"
            },
            {
                "key": "DB_1_PORT_3306_TCP_ADDR",
                "value": "172.16.0.3"
            },
            {
                "key": "DB_1_PORT_3306_TCP_PORT",
                "value": "3306"
            },
            {
                "key": "DB_1_PORT_3306_TCP_PROTO",
                "value": "tcp"
            },
            {
                "key": "DB_ENV_DEBIAN_FRONTEND",
                "value": "noninteractive"
            },
            {
                "key": "DB_ENV_MYSQL_PASS",
                "value": "**Random**"
            },
            {
                "key": "DB_ENV_MYSQL_USER",
                "value": "admin"
            },
            {
                "key": "DB_ENV_PATH",
                "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
            },
            {
                "key": "DB_ENV_REPLICATION_MASTER",
                "value": "**False**"
            },
            {
                "key": "DB_ENV_REPLICATION_PASS",
                "value": "replica"
            },
            {
                "key": "DB_ENV_REPLICATION_SLAVE",
                "value": "**False**"
            },
            {
                "key": "DB_ENV_REPLICATION_USER",
                "value": "replica"
            },
            {
                "key": "DB_PASS",
                "value": "szVaPz925B7I"
            },
            {
                "key": "DB_PORT",
                "value": "tcp://172.16.0.3:3306"
            },
            {
                "key": "DB_PORT_3306_TCP",
                "value": "tcp://172.16.0.3:3306"
            },
            {
                "key": "DB_PORT_3306_TCP_ADDR",
                "value": "172.16.0.3"
            },
            {
                "key": "DB_PORT_3306_TCP_PORT",
                "value": "3306"
            },
            {
                "key": "DB_PORT_3306_TCP_PROTO",
                "value": "tcp"
            },
            {
                "key": "DB_DOCKERCLOUD_API_URL",
                "value": "https://cloud.docker.com/api/app/v1/user_namespace/service/c0fed1dc-c528-40c9-aa4c-dc00672ebcbf/"
            }
        ],
        "container_ports": [
            {
                "endpoint_uri": "http://wordpress-stackable-1.admin.cont.dockerapp.io:49153/",
                "inner_port": 80,
                "outer_port": 49153,
                "port_name": "http",
                "protocol": "tcp",
                "published": true,
                "uri_protocol": "http"
            }
        ],
        "cpu_shares": 100,
        "cpuset": "0,1",
        "cgroup_parent": "m-executor-abcd",
        "deployed_datetime": "Thu, 16 Oct 2014 12:04:08 +0000",
        "destroyed_datetime": null,
        "devices": [
            "/dev/ttyUSB0:/dev/ttyUSB0"
        ],
        "dns": [
            "8.8.8.8"
        ],
        "dns_search": [
            "example.com",
            "c1dd4e1e-1356-411c-8613-e15146633640.local.dockerapp.io"
        ],
        "domainname": "domainname",
        "entrypoint": "",
        "exit_code": null,
        "exit_code_msg": null,
        "extra_hosts": [
            "onehost:50.31.209.229"
        ],
        "hostname": "hostname",
        "image_name": "tutum/wordpress-stackable:latest",
        "labels": {
            "com.example.description": "Accounting webapp",
            "com.example.department": "Finance",
            "com.example.label-with-empty-value": ""
        },
        "linked_to_container": [
            {
                "endpoints": {
                    "3306/tcp": "tcp://172.16.0.3:3306"
                },
                "from_container": "/api/app/v1/user_namespace/container/c1dd4e1e-1356-411c-8613-e15146633640/",
                "name": "DB_1",
                "to_container": "/api/app/v1/user_namespace/container/ba434e1e-1234-411c-8613-e15146633640/"
            }
        ],
        "link_variables": {
            "WORDPRESS_STACKABLE_1_ENV_DB_HOST": "**LinkMe**",
            "WORDPRESS_STACKABLE_1_ENV_DB_NAME": "wordpress",
            "WORDPRESS_STACKABLE_1_ENV_DB_PASS": "szVaPz925B7I",
            "WORDPRESS_STACKABLE_1_ENV_DB_PORT": "**LinkMe**",
            "WORDPRESS_STACKABLE_1_ENV_DB_USER": "admin",
            "WORDPRESS_STACKABLE_1_ENV_DEBIAN_FRONTEND": "noninteractive",
            "WORDPRESS_STACKABLE_1_ENV_HOME": "/",
            "WORDPRESS_STACKABLE_1_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
            "WORDPRESS_STACKABLE_1_PORT": "tcp://172.16.0.2:80",
            "WORDPRESS_STACKABLE_1_PORT_80_TCP": "tcp://172.16.0.2:80",
            "WORDPRESS_STACKABLE_1_PORT_80_TCP_ADDR": "172.16.0.2",
            "WORDPRESS_STACKABLE_1_PORT_80_TCP_PORT": "80",
            "WORDPRESS_STACKABLE_1_PORT_80_TCP_PROTO": "tcp",
            "WORDPRESS_STACKABLE_ENV_DB_HOST": "**LinkMe**",
            "WORDPRESS_STACKABLE_ENV_DB_NAME": "wordpress",
            "WORDPRESS_STACKABLE_ENV_DB_PASS": "szVaPz925B7I",
            "WORDPRESS_STACKABLE_ENV_DB_PORT": "**LinkMe**",
            "WORDPRESS_STACKABLE_ENV_DB_USER": "admin",
            "WORDPRESS_STACKABLE_ENV_DEBIAN_FRONTEND": "noninteractive",
            "WORDPRESS_STACKABLE_ENV_HOME": "/",
            "WORDPRESS_STACKABLE_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
            "WORDPRESS_STACKABLE_PORT": "tcp://172.16.0.2:80",
            "WORDPRESS_STACKABLE_PORT_80_TCP": "tcp://172.16.0.2:80",
            "WORDPRESS_STACKABLE_PORT_80_TCP_ADDR": "172.16.0.2",
            "WORDPRESS_STACKABLE_PORT_80_TCP_PORT": "80",
            "WORDPRESS_STACKABLE_PORT_80_TCP_PROTO": "tcp"
        },
        "mac_address": "02:42:ac:11:65:43",
        "memory": 1024,
        "memory_swap": 4096,
        "name": "wordpress-stackable",
        "net": "bridge",
        "node": "/api/infra/v1/user_namespace/node/9691c44e-3155-4ca2-958d-c9571aac0a14/",
        "pid": "none",
        "private_ip": "10.7.0.1",
        "privileged": false,
        "public_dns": "wordpress-stackable-1.admin.cont.dockerapp.io",
        "read_only": true,
        "resource_uri": "/api/app/v1/user_namespace/container/c1dd4e1e-1356-411c-8613-e15146633640/",
        "roles": ["global"],
        "run_command": "/run-wordpress.sh",
        "security_opt": [
            "label:user:USER",
            "label:role:ROLE"
        ],
        "service": "/api/app/v1/user_namespace/service/adeebc1b-1b81-4af0-b8f2-cefffc69d7fb/",
        "started_datetime": "Thu, 16 Oct 2014 12:04:08 +0000",
        "state": "Running",
        "stdin_open": false,
        "stopped_datetime": null,
        "synchronized": true,
        "tty": false,
        "user": "root",
        "uuid": "c1dd4e1e-1356-411c-8613-e15146633640",
        "working_dir": "/app"
    }

A container is a representation of a Docker container in a node.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
uuid | A unique identifier for the container generated automatically on creation
resource_uri | A unique API endpoint that represents the container
image_name | The Docker image name and tag of the container
bindings | A list of volume bindings that the container has mounted (see table `Container Binding attributes` below)
name | A user provided name for the container (inherited from the service)
node | The resource URI of the node where this container is running
service | The resource URI of the service which this container is part of
public_dns | The external FQDN of the container
state | The state of the container (see table `Container states` below)
synchronized | Flag indicating if the container is synchronized with the current service definition.
exit_code | The numeric exit code of the container (if applicable, `null` otherwise)
exit_code_msg | A string representation of the exit code of the container (if applicable, `null` otherwise)
deployed_datetime | The date and time of the last deployment of the container (if applicable, `null` otherwise)
started_datetime | The date and time of the last `start` operation on the container (if applicable, `null` otherwise)
stopped_datetime | The date and time of the last `stop` operation on the container (if applicable, `null` otherwise)
destroyed_datetime | The date and time of the `terminate` operation on the container (if applicable, `null` otherwise)
container_ports | List of published ports of this container (see table `Container Port attributes` below)
container_envvars | List of user-defined environment variables set on the containers of the service, which will override the container environment variables (see table `Container Environment Variable attributes` below)
labels | Container metadata in form of dictionary
working_dir | Working directory for running binaries within a container
user | User used on the container on launch
hostname | Hostname used on the container on launch
domainname | Domainname used on the container on launch
mac_address | Ethernet device’s MAC address used on the container on launch
cgroup_name | Optional parent cgroup for the container.
tty | If the container has the tty enable
stdin_open | If the container has stdin opened
dns | Container custom DNS servers
dns_search | Container custom DNS search domain
cap_add | Container added capabilities
cap_drop | Container dropped capabilities
devices | List of container device mappings
extra_hosts | List of container hostname mappings
secuirty_opt | Labeling scheme of this container
entrypoint | Entrypoint used on the container on launch
run_command | Run command used on the container on launch
cpu_shares | The relative CPU priority of the container (see Runtime Constraints on CPU and Memory for more information)
cpuset | CPUs in which execution is allowed
memory | The memory limit of the container in MB (see Runtime Constraints on CPU and Memory for more information)
memory_swap | Total memory limit (memory + swap) of the container in MB
autorestart | Whether to restart the container automatically if it stops (see Crash recovery for more information)
autodestroy | Whether to terminate the container automatically if it stops (see Autodestroy for more information)
roles | List of Docker Cloud roles asigned to this container (see API roles for more information))
linked_to_container | List of IP addresses of the linked containers (see table `Container Link attributes` below and Service links for more information)
link_variables | List of environment variables that would be exposed in any container that is linked to this one
privileged | Whether the container has Docker’s `privileged` flag set or not (see Runtime privilege for more information)
read_only | Whether the container filesystem is read-only or not
private_ip | IP address of the container on the overlay network. This IP will be reachable from any other container.
net | Network mode set on the container (see table `Network Modes` below, more information ../../reference/run/#network-settings)
pid | PID (Process) Namespace mode for the container (more information ../../reference/run/#pid-settings-pid)

### Container Binding attributes

Attribute | Description
--- | ---
host_path | The host path of the volume
container_path | The container path where the volume is mounted
rewritable | `true` is the volume has writable permissions
volume | The resource URI of the volume

### Container Port attributes

Attribute | Description
--- | ---
protocol | The protocol of the port, either `tcp` or `udp`
inner_port | The published port number inside the container
outer_port | The published port number in the node public network interface
port_name | Name of the service associated to this port
uri_protocol | The protocol to be used in the endpoint for this port (i.e. `http`)
endpoint_uri | The URI of the endpoint for this port
published | Whether the port has been published in the host public network interface or not. Non-published ports can only be accessed via links.

### Container Environment Variable attributes

Attribute | Description
--- | ---
key | The name of the environment variable
value | The value of the environment variable

### Container States

State | Description
--- | ---
Starting | The container is being deployed or started (from Stopped). No actions allowed in this state.
Running | The container is deployed and running. Possible actions in this state: `stop`, `terminate`.
Stopping | The container is being stopped. No actions allowed in this state.
Stopped | The container is stopped. Possible actions in this state: `start`, `terminate`.
Terminating | The container is being deleted. No actions allowed in this state.
Terminated | The container has been deleted. No actions allowed in this state.

### Network Modes

Strategy | Description
--- | ---
bridge | Creates a new network stack for the container on the docker bridge.
host | Uses the host network stack inside the container.

### Container Link attributes

Attribute | Description
--- | ---
name | The name given to the link
from_container | The resource URI of the “client” container
to_container | The resource URI of the “server” container being linked
endpoints | A dictionary with the endpoints (protocol, IP and port) to be used to reach each of the “server” container exposed ports

## List all containers

    import dockercloud

    containers = dockercloud.Container.list()

    import "github.com/docker/go-dockercloud/dockercloud"

    containerList, err := dockercloud.ListContainers()

    if err != nil {
      log.Println(err)
    }

    log.Println(containerList)

    GET /api/app/v1/container/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud container ps

Lists all current and recently terminated containers. Returns a list of `Container` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/`

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID
state | Filter by state. Possible values: `Starting`, `Running`, `Stopping`, `Stopped`, `Terminating`, `Terminated`
name | Filter by container name
service | Filter by resource URI of the target service.
node | Filter by resource URI of the target node.

## Get an existing container

    import dockercloud

    container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    import "github.com/docker/go-dockercloud/dockercloud"

    container, err := dockerckoud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    log.Println(container)

    GET /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud container inspect 7eaf7fff

Get all the details of an specific container

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the container to retrieve

## Get the logs of a container

> Example log line

    {
        "type": "log",
        "log": "Log line from the container",
        "streamType": "stdout",
        "timestamp": 1433779324
    }

    import dockercloud

    def log_handler(message):
        print message

    container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    container.logs(tail=300, follow=True, log_handler=log_handler)

    import "github.com/docker/go-dockercloud/dockercloud"

    container, err := dockercloud.GetContainer("447ecddc-2890-4ea2-849b-99392e0dd7a6")

    if err != nil {
        log.Fatal(err)
    }
    c := make(chan dockercloud.Logs)

    go container.Logs(c)
        for {
            s := <-c
            log.Println(s)
        }

    GET /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
    Host: ws.cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Connection: Upgrade
    Upgrade: websocket

    docker-cloud container logs 7eaf7fff

Get the logs of the specified container.

### Endpoint Type

Available in Docker Cloud’s STREAM API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/(uuid)/logs/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the container to retrieve logs

### Query Parameters

Parameter | Description
--- | ---
tail | Number of lines to show from the end of the logs (default: `300`)
follow | Whether to stream logs or close the connection immediately (default: true)
service | Filter by service (resource URI)

## Start a container

    import dockercloud

    container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    container.start()

    import "github.com/docker/go-dockercloud/dockercloud"

    container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
        log.Println(err)
    }

    if err = container.Start(); err != nil {
      log.Println(err)
    }

    POST /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud container start 7eaf7fff

Starts a stopped container.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]container/(uuid)/start/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the container to start

## Stop a container

    import dockercloud

    container = dockerlcoud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    container.stop()

    import "github.com/docker/go-dockercloud/dockercloud"

    container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
        log.Println(err)
    }

    if err = container.Stop(); err != nil {
           log.Println(err)
       }

    POST /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/stop/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud container stop 7eaf7fff

Stops a running container.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]container/(uuid)/stop/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the container to stop

## Redeploy a container

    import dockercloud

    container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    container.redeploy()

    import "github.com/docker/go-dockercloud/dockercloud"

    container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
        log.Println(err)
    }
    //Redeploy(dockercloud.ReuseVolumesOption{Reuse: true) to reuse the existing volumes
    //Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}) to not reuse the existing volumes
    if err = container.Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}); err != nil {
      log.Println(err)
    }

    POST /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud container redeploy 7eaf7fff

Redeploys a container.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]container/(uuid)/redeploy/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the container to redeploy

### Query Parameters

Parameter | Description
--- | ---
reuse_volumes | Wheather to reuse container volumes for this redeploy operation or not (default: `true`).

## Terminate a container

    import dockercloud

    container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    container.delete()

    import "github.com/docker/go-dockercloud/dockercloud"

    container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
        log.Println(err)
    }

    if err = container.Terminate(); err != nil {
           log.Println(err)
       }

    DELETE /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud container terminate 7eaf7fff

Terminates the specified container. This is not reversible. All data stored in the container will be permanently deleted.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`DELETE /api/app/v1/[optional_namespace/]container/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the container to terminate

## Execute command inside a container

    import dockercloud

    def msg_handler(message):
        print message

    container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
    container.execute("ls", handler=msg_handler)

    import "github.com/docker/go-dockercloud/dockercloud"

    container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    c := make(chan dockercloud.Exec)

    container.Exec("ls", c)

    GET /api/app/v1/container/(uuid)/exec/ HTTP/1.1
    Host: ws.cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Connection: Upgrade
    Upgrade: websocket

    docker-cloud exec 7eaf7fff ls

Executes a command inside the specified running container, creating a bi-directional stream for the process’ standard input and output. This endpoint can be connected to using a bi-directional Secure Web Socket `wss://ws.cloud.docker.com/api/app/v1/container/(uuid)/exec/`

### Endpoint Type

Available in Docker Cloud’s STREAM API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/(uuid)/exec/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the container where the command will be executed

### Query Parameters

Parameter | Description
--- | ---
command | Command to be executed (default: `sh`)

# Triggers

## Service triggers

> Example

    {
      "url": "/api/app/v1/user_namespace/service/82d4a246-52d8-468d-903d-9da9ef05ff28/trigger/0224815a-c156-44e4-92d7-997c69354438/call/",
      "operation": "REDEPLOY",
      "name": "docker_trigger",
      "resource_uri": "/api/app/v1/user_namespace/service/82d4a246-52d8-468d-903d-9da9ef05ff28/trigger/0224815a-c156-44e4-92d7-997c69354438/"
    }

Triggers are URLs that will start a redeploy of the service whenever a `POST` request is sent to them. They require no authorization headers, so they should be treated as access tokens. Triggers can be revoked if they are leaked or no longer used for security purposes. See Triggers for more information.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
url | Address to be used to call the trigger with a `POST` request
name | A user provided name for the trigger
operation | The operation that the trigger call performs (see table `Operations` below)
resource_uri | A unique API endpoint that represents the trigger

### Operations

Operation | Description
--- | ---
REDEPLOY | Performs a `redeploy` service operation.
SCALEUP | Performs a `scale up` service operation.

## List all triggers

    import dockercloud

    service = dockercloud.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
    trigger = dockercloud.Trigger.fetch(service)
    trigger.list()

    GET /api/app/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

        if err != nil {
            log.Println(err)
        }

    trigger, err := service.ListTriggers()

      if err != nil {
        log.Println(err)
      }

        log.Println(trigger)

    docker-cloud trigger list 61a29874-9134-48f9-b460-f37d4bec4826

Lists all current triggers the service has associated to. Returns a list of `Service Trigger` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]service/(uuid)/trigger/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service the triggers are associated to

## Create a new trigger

    import dockercloud

    service = dockercloud.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
    trigger = dockercloud.Trigger.fetch(service)
    trigger.add(name="mytrigger_name", operation="REDEPLOY")
    trigger.save()

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

    if err != nil {
      log.Println(err)
    }

    trigger, err := service.CreateTrigger(dockercloud.TriggerCreateRequest{Name: "test-trigger", Operation: "REDEPLOY"})

    if err != nil {
      log.Println(err)
    }

    log.Println(trigger)

    POST /api/app/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {"name": "mytrigger_name", "operation": "REDEPLOY"}

    docker-cloud trigger create --name mytrigger_name --operation REDEPLOY 61a29874-9134-48f9-b460-f37d4bec4826

Creates a new service trigger.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]service/(uuid)/trigger/`

### JSON Parameters

Parameter | Description
--- | ---
name | (optional) A user provided name for the trigger
operation | (optional) The operation to be performed by the trigger (default: “REDEPLOY”)

## Get an existing trigger

    import dockercloud

    service = dockercloud.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
    trigger = dockercloud.Trigger.fetch(service)

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

    if err != nil {
      log.Println(err)
    }

    trigger, err := service.GetTrigger("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    if err != nil {
      log.Println(err)
    }

    log.Println(trigger)

    GET /api/app/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

Get all the details of an specific trigger

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`GET /api/app/v1/[optional_namespace/]service/(uuid)/trigger/(trigger_uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the service the triggers are associated to
trigger_uuid | The UUID of the trigger to retrieve

## Delete a trigger

    import dockercloud

    service = dockercloud.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
    trigger = dockercloud.Trigger.fetch(service)
    trigger.delete("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

    if err != nil {
      log.Println(err)
    }

    service.DeleteTrigger("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    DELETE /api/app/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud trigger rm 61a29874-9134-48f9-b460-f37d4bec4826 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Deletes specific trigger. It will be no longer available to be called.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`DELETE /api/app/v1/[optional_namespace/]service/(uuid)/trigger/(trigger_uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the associated service
trigger_uuid | The UUID of the trigger to delete

## Call a trigger

    import dockercloud

    service = dockercloud.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
    trigger = dockercloud.Trigger.fetch(service)
    trigger.call("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    import "github.com/docker/go-dockercloud/dockercloud"

    service, err := dockercloud.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

    if err != nil {
      log.Println(err)
    }

    service.CallTrigger("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

    POST /api/app/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/call/ HTTP/1.1
    Host: cloud.docker.com
    Accept: application/json

Executes the trigger. For `SCALEUP` triggers, the number of containers to scale up can be passed at the end of the trigger call url, for example `/api/app/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/call/3/`.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]service/(uuid)/trigger/(trigger_uuid)/call/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the associated service
trigger_uuid | The UUID of the trigger to call

# Docker Cloud Events

## Docker Cloud Event

> Example

    {
        "type": "action",
        "action": "update",
        "parents": [
            "/api/app/v1/user_namespace/container/0b0e3538-88df-4f07-9aed-3a3cc4175076/"
        ],
        "resource_uri": "/api/app/v1/user_namespace/action/49f0efe8-a704-4a10-b02f-f96344fabadd/",
        "state": "Success",
        "uuid": "093ba3bb-08dd-48f0-8f12-4d3b85ef85b3",
        "datetime": "2016-02-01T16:47:28Z"
    }

Docker Cloud events are generated every time any of the following objects is created or changes state:

- Stack
- Service
- Container
- Node Cluster
- Node
- Action

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
type | Type of object that was created or updated. For possible values, check the events types table below.
action | Type of action that was executed on the object. Posible values: `create`, `update` or `delete`
parents | List of resource URIs (REST API) of the parents of the object, according to the “Parent-child hierarchy” table below
resource_uri | Resource URI (REST API) of the object that was created or updated. You can do a `GET` operation on this URL to fetch its details
state | The current state of the object
uuid | Unique identifier for the event
datetime | Date and time of the event in ISO 8601 format

### Event types

Type | Description
--- | ---
stack | Whenever a `Stack` is created or updated
service | Whenever a `Service` is created or updated
container | Whenever a `Container` is created or updated
nodecluster | Whenever a `Node Cluster` is created or updated
node | Whenever a `Node` is created or updated
action | Whenever a `Action` is created or updated
error | Sent when an error occurs on the websocket connection or as part of the authentication process

### Parent-child hierarchy

Object type | Parent types
--- | ---
Stack | (None)
Service | Stack
Container | Service, Stack, Node, Node Cluster
Node Cluster | (None)
Node | Node Cluster
Action | (object to which the action applies to)

## Listen to new Docker Cloud Events

    import dockercloud

    def process_event(event):
        print event

    events = dockercloud.Events()
    events.on_message(process_event)
    events.run_forever()

    import "github.com/docker/go-dockercloud/dockercloud"

    // Listens for container events only
    myFilter := dockercloud.NewStreamFilter(&dockercloud.EventFilter{Type: "container"})

    stream := dockercloud.NewStream(myFilter)

    if err := stream.Connect(); err == nil {
        go stream.RunForever()
    } else {
        log.Print("Connect err: " + err.Error())
    }

    for {
        select {
        case event := <-stream.MessageChan:
            log.Println(event)
        case err := <-stream.ErrorChan:
            log.Println(err)
        }
    }

    GET /api/audit/v1/events/ HTTP/1.1
    Host: ws.cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Connection: Upgrade
    Upgrade: websocket

    docker-cloud event

Listens for new Docker Cloud Events

### Endpoint Type

Available in Docker Cloud’s STREAM API

### HTTP Request

`GET /api/audit/v1/[optional_namespace/]events/`

### Query Parameters

Parameter | Description
--- | ---
type | Filter by type
object | Filter by object resource URI
parent | Filter by object parents

# Errors

> API response structure

    {
        "error": "Descriptive error message"
    }

The Docker Cloud API uses the following error codes:

Error Code | Meaning
--- | ---
400 | Bad Request – There’s a problem in the content of your request. Retrying the same request will fail.
401 | Unauthorized – Your API key is wrong or your account has been deactivated.
402 | Payment Required – You need to provide billing information to perform this request.
403 | Forbidden – Quota limit exceeded. Please contact support to request a quota increase.
404 | Not Found – The requested object cannot be found.
405 | Method Not Allowed – The endpoint requested does not implement the method sent.
409 | Conflict – The object cannot be created or updated because another object exists with the same unique fields
415 | Unsupported Media Type – Make sure you are using `Accept` and `Content-Type` headers as `application/json` and that the data your are `POST`-ing or `PATCH`-ing is in valid JSON format.
429 | Too Many Requests – You are being throttled because of too many requests in a short period of time.
500 | Internal Server Error – There was a server error while processing your request. Try again later, or contact support.
503 | Service Unavailable – We’re temporarily offline for maintenance. Please try again later.
504 | Gateway Timeout – Our API servers are at full capacity. Please try again later.

http go python CLI