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

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