docs/apidocs/cloud-api-source/source/includes/service.md

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/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/container/6f8ee454-9dc3-4387-80c3-57aac1be3cc6/",
    "/api/app/v1/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/service/adeebc1b-1b81-4af0-b8f2-cefffc69d7fb/"
  },
  "linked_from_service": [],
  "linked_to_service": [
    {
      "from_service": "/api/app/v1/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/",
      "name": "DB",
      "to_service": "/api/app/v1/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/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/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.

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/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/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/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/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/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/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/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/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/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/service/(uuid)/

Path Parameters

Parameter	Description
uuid	The UUID of the service to terminate