mirror of https://github.com/docker/docs.git
413 lines
12 KiB
Markdown
413 lines
12 KiB
Markdown
# Node Clusters
|
|
|
|
## Node Cluster
|
|
|
|
> Example
|
|
|
|
```json
|
|
{
|
|
"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](#namespaced-endpoints).
|
|
|
|
|
|
### 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](/docker-cloud/apps/deploy-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
|
|
|
|
```python
|
|
import dockercloud
|
|
|
|
nodeclusters = dockercloud.NodeCluster.list()
|
|
```
|
|
|
|
```go
|
|
import "github.com/docker/go-dockercloud/dockercloud"
|
|
|
|
nodeclusters, err := dockercloud.ListNodeClusters()
|
|
|
|
if err != nil {
|
|
log.Println(err)
|
|
}
|
|
|
|
log.Println(nodeclusters)
|
|
```
|
|
|
|
```http
|
|
GET /api/infra/v1/nodecluster/ HTTP/1.1
|
|
Host: cloud.docker.com
|
|
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
|
|
Accept: application/json
|
|
```
|
|
|
|
```shell
|
|
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
|
|
|
|
```python
|
|
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()
|
|
```
|
|
|
|
```go
|
|
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)
|
|
```
|
|
|
|
```http
|
|
POST /api/infra/v1/nodecluster/ HTTP/1.1
|
|
Host: cloud.docker.com
|
|
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
```shell
|
|
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](/docker-cloud/apps/deploy-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
|
|
|
|
```python
|
|
import dockercloud
|
|
|
|
service = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
|
|
```
|
|
|
|
```go
|
|
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)
|
|
```
|
|
|
|
```http
|
|
GET /api/infra/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
|
|
Host: cloud.docker.com
|
|
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
|
|
Accept: application/json
|
|
```
|
|
|
|
```shell
|
|
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
|
|
|
|
```python
|
|
import dockercloud
|
|
|
|
nodecluster = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
|
|
nodecluster.deploy()
|
|
```
|
|
|
|
```go
|
|
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)
|
|
}
|
|
```
|
|
|
|
```http
|
|
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
|
|
|
|
```python
|
|
import dockercloud
|
|
|
|
nodecluster = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
|
|
nodecluster.target_num_nodes = 3
|
|
nodecluster.tags.add("tag-1")
|
|
nodecluster.save()
|
|
```
|
|
|
|
```go
|
|
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)
|
|
}
|
|
```
|
|
|
|
```http
|
|
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
|
|
|
|
```
|
|
|
|
```shell
|
|
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
|
|
|
|
```python
|
|
import dockercloud
|
|
|
|
nodecluster = dockercloud.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
|
|
nodecluster.delete()
|
|
```
|
|
|
|
```go
|
|
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)
|
|
}
|
|
```
|
|
|
|
```http
|
|
DELETE /api/infra/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
|
|
Host: cloud.docker.com
|
|
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
|
|
Accept: application/json
|
|
```
|
|
|
|
```shell
|
|
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
|