docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docs/cluster/aws.md

403 lines
15 KiB
Markdown
Raw Blame History

---
description: Get started with Docker Cluster on AWS
keywords: documentation, docs, docker, cluster, infrastructure, automation, AWS
title: Get started with Docker Cluster on AWS
---
This topic discusses working with docker clusters in AWS, including how to:
- [Create a cluster](#create-a-cluster)
- [View cluster information](#view-cluster-information)
- [Use context](#use-context)
- [Scale a cluster](#scale-a-cluster)
- [Back up a cluster](#back-up-a-cluster)
- [Upgrade a cluster](#upgrade-a-cluster)
- [Destroy a cluster](#destroy-a-cluster)
## Prerequisites
- Completed installation of [Docker Desktop Enterprise](/ee/desktop/admin/install).
- [Access keys](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) to an AWS subscription. You can provide these credentials in many ways, but the recommended way is to create an `~/.aws/credentials` file. Refer to [AWS CLI configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) for details on creating one.
## Create a cluster
When you create a docker cluster in AWS, the created cluster has:
- 3 UCP Managers
- 3 Workers
- 3 DTR Replicas
Create a `cluster.yml` file with the following information:
```yaml
variable:
domain: "YOUR DOMAIN, e.g. docker.com"
subdomain: "A SUBDOMAIN, e.g. cluster"
region: "THE AWS REGION TO DEPLOY, e.g. us-east-1"
email: "YOUR.EMAIL@COMPANY.COM"
ucp_password:
type: prompt
provider:
acme:
email: ${email}
server_url: https://acme-staging-v02.api.letsencrypt.org/directory
aws:
region: ${region}
cluster:
dtr:
version: docker/dtr:2.6.5
engine:
version: ee-stable-18.09.5
ucp:
username: admin
password: ${ucp_password}
version: docker/ucp:3.1.6
resource:
aws_instance:
managers:
instance_type: t2.xlarge
os: Ubuntu 16.04
quantity: 3
registry:
instance_type: t2.xlarge
os: Ubuntu 16.04
quantity: 3
workers:
instance_type: t2.xlarge
os: Ubuntu 16.04
quantity: 3
aws_lb:
apps:
domain: ${subdomain}.${domain}
instances:
- workers
ports:
- 80:8080
- 443:8443
dtr:
domain: ${subdomain}.${domain}
instances:
- registry
ports:
- 443:443
ucp:
domain: ${subdomain}.${domain}
instances:
- managers
ports:
- 443:443
- 6443:6443
aws_route53_zone:
dns:
domain: ${domain}
subdomain: ${subdomain}
```
In this example, the cluster takes on the following topology:
![Docker Cluster Topology](./images/docker_cluster_aws.png)
Provide values for the variable section. For example:
domain: "docker.notreal"
subdomain: "quickstart"
region: "us-east-1"
email: "cluster@docker.com"
The values are substituted in the cluster definition, which makes it
easy to define a re-usable cluster definition and then change the variables
to create multiple instances of a cluster.
Run `docker cluster create --file cluster.yml --name quickstart`
$ docker cluster create --file cluster.yml --name quickstart
Please provide a value for ucp_password
Docker Enterprise Platform 3.0
Preparing quickstart [OK]
Planning cluster on aws [OK]
Creating: [=========================== ] 44%
After approximately 10 minutes, resources are provisioned Docker Enterprise installation is started:
$ docker cluster create --file cluster.yml --name quickstart
Please provide a value for ucp_password
Docker Enterprise Platform 3.0
Preparing quickstart [OK]
Planning cluster on aws [OK]
Creating: [==============================================================] 100%
Installing Docker Enterprise Platform Requirements [OK]
docker-ee : Ensure old versions of Docker are not installed. [-]
After approximately 20 minutes, Docker Enterprise installation completes:
$ docker cluster create -f examples/docs.yml -n quickstart
Please provide a value for ucp_password
Docker Enterprise Platform 3.0
Preparing quickstart [OK]
Planning cluster on aws [OK]
Creating: [==============================================================] 100%
Installing Docker Enterprise Platform Requirements [OK]
Installing Docker Enterprise Engine [OK]
Installing Docker Universal Control Plane [OK]
Installing Docker Trusted Registry [OK]
Successfully created context "quickstart"
Connect to quickstart at:
https://ucp.quickstart.docker.notreal
911c882340b2
After all operations complete succesfully, the cluster ID is the last statement
to print. You can now log in to the URL and begin interacting with the cluster.
## View cluster information
To view an inventory of the clusters you created, run `docker cluster ls`:
$ docker cluster ls
ID NAME PROVIDER ENGINE UCP DTR STATE
911c882340b2 quickstart acme, aws ee-stable-18.09.5 docker/ucp:3.1.6 docker/dtr:2.6.5 running
For detailed information about the cluster, run `docker cluster inspect quickstart`
$ docker cluster inspect quickstart
```yaml
name: quickstart
shortid: 911c882340b2
variable:
domain: docker.notreal
email: cluster@docker.com
region: us-east-1
subdomain: quickstart
provider:
acme:
server_url: https://acme-staging-v02.api.letsencrypt.org/directory
aws:
region: us-east-1
version: ~> 1.0
cluster:
dtr:
version: docker/dtr:2.6.5
engine:
storage_volume: /dev/xvdb
version: ee-stable-18.09.5
registry:
url: https://index.docker.io/v1/
username: user
ucp:
username: admin
version: docker/ucp:3.1.6
resource:
aws_instance:
managers:
instance_type: t2.xlarge
os: Ubuntu 16.04
quantity: 3
role: manager
registry:
instance_type: t2.xlarge
os: Ubuntu 16.04
quantity: 3
role: dtr
workers:
instance_type: t2.xlarge
os: Ubuntu 16.04
quantity: 3
role: worker
aws_lb:
apps:
domain: quickstart.docker.notreal
path: /data/ssl-certs/
ports:
- 80:8080
- 443:8443
dtr:
domain: quickstart.docker.notreal
path: /data/ssl-certs/
ports:
- 443:443
ucp:
domain: quickstart.docker.notreal
path: /data/ssl-certs/
ports:
- 443:443
- 6443:6443
aws_route53_zone:
dns:
domain: docker.notreal
subdomain: quickstart
```
The information displayed by `docker cluster inspect` can be used as a cluster definition to clone the cluster.
## Use context
`docker cluster` creates a context on your local machine. To use this context and interact with the cluster, run `docker context use quickstart`:
$ docker context use quickstart
quickstart
Current context is now "quickstart"
To verify that the client is connected to the cluster, run `docker version`:
$ docker version
Client: Docker Engine - Enterprise
Version: 19.03.0-beta1
API version: 1.39 (downgraded from 1.40)
Go version: go1.12.1
Git commit: 90dbc83
Built: Fri Apr 5 23:35:58 2019
OS/Arch: darwin/amd64
Experimental: false
Server: Docker Enterprise 2.1
Engine:
Version: 18.09.5
API version: 1.39 (minimum version 1.12)
Go version: go1.10.8
Git commit: be4553c
Built: Thu Apr 11 06:19:48 2019
OS/Arch: linux/amd64
Experimental: false
Universal Control Plane:
Version: 3.1.6
ApiVersion: 1.39
Arch: amd64
BuildTime: Wed Apr 10 22:35:22 UTC 2019
GitCommit: 944388b
GoVersion: go1.10.6
MinApiVersion: 1.20
Os: linux
Kubernetes:
Version: 1.11+
buildDate: 2019-03-26T02:54:43Z
compiler: gc
gitCommit: 2d582ce995b1ff65b89ad851e8b09b6bc1a84c85
gitTreeState: clean
gitVersion: v1.11.9-docker-1
goVersion: go1.10.8
major: 1
minor: 11+
platform: linux/amd64
Calico:
Version: v3.5.3
cni: v3.5.3
kube-controllers: v3.5.3
node: v3.5.3
To change the context back to your local machine, run `docker context use default`:
$ docker context use default
default
Current context is now "default"
## Scale a cluster
Open `cluster.yml`. Change the number of workers to 6:
```yaml
workers:
instance_type: t2.xlarge
os: Ubuntu 16.04
quantity: 6
```
Since the cluster is already created, the next step is to `update` the cluster's
desired state. Run `docker cluster update quickstart --file cluster.yml`:
$ docker cluster update quickstart --file cluster.yml
Docker Enterprise Platform 3.0
Preparing quickstart [OK]
Planning cluster on aws [OK]
Updating: [================== ] 30%
After approximately 10 minutes, use the `update` operation to add the new nodes and join them to the cluster:
$ docker cluster update quickstart --file examples/docs.yml
Please provide a value for ucp_password
Docker Enterprise Platform 3.0
Preparing quickstart [OK]
Planning cluster on aws [OK]
Updating: [==============================================================] 100%
Installing Docker Enterprise Platform Requirements [OK]
Installing Docker Enterprise Engine [OK]
Installing Docker Universal Control Plane [OK]
Installing Docker Trusted Registry [OK]
911c882340b2
To view the new nodes in the cluster:
$ docker --context quickstart node ls
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
mpyk5jxkvgnh75cqmfdzddp7g ip-172-31-0-116.us-east-2.compute.internal Ready Active 18.09.5
s0pd7kqjg8ufelwa9ndkbf1k5 ip-172-31-6-9.us-east-2.compute.internal Ready Active Leader 18.09.5
ddnvnasq8wibtz9kedlvnxru0 ip-172-31-7-9.us-east-2.compute.internal Ready Active 18.09.5
vzta920dhpke9nf4vipqtkuuw ip-172-31-15-210.us-east-2.compute.internal Ready Active 18.09.5
tk98g0tfsb9kzri4slqdh2d2x ip-172-31-18-95.us-east-2.compute.internal Ready Active 18.09.5
g1kwut63oule9v0x245ms7wsw ip-172-31-21-212.us-east-2.compute.internal Ready Active 18.09.5
04jgx94jwscgnac2afdzcd9hp * ip-172-31-25-45.us-east-2.compute.internal Ready Active Reachable 18.09.5
5ubqk4mojz198sr72m9zegeew ip-172-31-29-201.us-east-2.compute.internal Ready Active 18.09.5
32rthfhjpm9gaz7n5608k5coj ip-172-31-33-183.us-east-2.compute.internal Ready Active 18.09.5
zqg81yv81auy7eot3a1kson2g ip-172-31-42-49.us-east-2.compute.internal Ready Active 18.09.5
qu84bv2zytv5nubcuntkzwbu5 ip-172-31-43-6.us-east-2.compute.internal Ready Active 18.09.5
j6kzzog8a2yv4ragpx826juyv ip-172-31-43-108.us-east-2.compute.internal Ready Active Reachable 18.09.5
## Back up a cluster
Before performing operations on the cluster, perform a full backup of the running cluster by running `docker cluster backup quickstart --file "backup-$(date '+%Y-%m-%d').tar.gz" `.
Provide a passphrase to encrypt the UCP backup.
$ docker cluster backup quickstart --file "backup-$(date '+%Y-%m-%d').tar.gz"
Passphrase for UCP backup:
Docker Enterprise Platform 3.0
Create archive file. [OK]
Backup of 911c882340b2 saved to backup-2019-05-07.tar.gz
Save the backup on external storage for disaster recovery.
To restore a cluster, run `docker cluster restore quickstart --file backup-2019-05-07.tar.gz`.
Provide the passphrase from the backup step to decrypt the UCP backup.
## Upgrade a cluster
Open `cluster.yml`. Change the cluster versions:
```yaml
cluster:
dtr:
version: docker/dtr:2.7.0
engine:
version: ee-stable-19.03
ucp:
version: docker/ucp:3.2.0
```
Run `docker cluster update quickstart --file cluster.yml `:
$ docker cluster update quickstart --file examples/docs.yml
Please provide a value for ucp_password
Docker Enterprise Platform 3.0
Preparing quickstart [OK]
Planning cluster on aws [OK]
Updating: [==============================================================] 100%
Installing Docker Enterprise Platform Requirements [OK]
Upgrading Docker Enterprise Engine [OK]
Upgrading Docker Universal Control Plane [OK]
Upgrading Docker Trusted Registry [OK]
911c882340b2
## Destroy a cluster
When the cluster has reached end-of-life, run `docker cluster rm quickstart`:
$ docker cluster rm quickstart
Removing quickstart [OK]
Removing: [==============================================================] 100%
quickstart
911c882340b2
All provisioned resources are destroyed and the context for the cluster is removed.
## Where to go next
- View the quick start guide for [Azure](azure.md) or [vSphere](vsphere.md)
- [Explore the full list of Cluster commands](/engine/reference/commandline/cluster/)
- [Cluster configuration file reference](./cluster-file/index.md)
Reference in New Issue View Git Blame Copy Permalink