NAV

# 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