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

[WIP] Docker Cluster (#1126) 

Co-Authored-By: Chris Girard <chris.girard@docker.com>
This commit is contained in:
Joe Abbey 2019-06-06 08:17:28 -04:00 committed by paigehargrave
parent e845a24cc7
commit 2ec4f7f180
14 changed files with 1257 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

402
cluster/aws.md Normal file
View File

@ -0,0 +1,402 @@
---
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](./reference/index.md)
- [Cluster configuration file reference](./cluster-file/index.md)

527
cluster/cluster-file/index.md Normal file
View File

@ -0,0 +1,527 @@
---
description: Cluster file reference and guidelines
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: Cluster file version 1 reference
toc_max: 5
toc_min: 1
---
This topic describes version 1 of the Cluster file format.
## Cluster file structure and examples
```
<div class="panel panel-default">
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
Example Cluster file version 1
<i class="chevron fa fa-fw"></i></div>
<div class="collapse block" id="collapseSample1">
<pre><code>
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}
</code></pre>
</div>
</div>
```
The topics on this reference page are organized alphabetically by top-level keys
to reflect the structure of the Cluster file. Top-level keys that define
a section in the configuration file, such as `cluster`, `provider`, and `resource`,
are listed with the options that support them as sub-topics. This information
maps to the indent structure of the Cluster file.
### cluster
Specifies components to install and configure for a cluster.
The following components are available:
- `subscription`: (Optional) A string value representing the subscription ID.
- `license`: (Optional) A path to the cluster's license file.
- `cloudstor`: (Optional) Configuration options for Docker CloudStor
- `dtr`: (Optional) Configuration options for Docker Trusted Registry
- `engine`: (Optional) Configuration options for Docker Engine
- `ucp`: (Optional) Configuration options for Docker Universal Control Plane
- `registry`: (Optional) Configuration options for authenticating nodes with a registry to pull Docker images.
#### cloudstor
Customizes the installation of Docker Cloudstor.
- `version`: (Optional) The version of Cloudstor to install. Default is `1.0`
- `use_efs`: (Optional) Specifies whether an Elastic File System should be provisioned. Defaults to `false`.
#### dtr
Customizes the installation of Docker Trusted Registry.
```yaml
cluster:
dtr:
version: "docker/dtr:2.6.5"
install_options:
- "--debug"
- "--enable-pprof"
```
The following optional elements can be specified:
- `version`: (Optional) The version of DTR to install. Defaults to `docker/dtr:2.6.5`.
- `ca`: (Optional) The path to a root CA public certificate.
- `key`: (Optional) The path to a TLS private key.
- `cert`: (Optional) The path to a public key certificate.
- `install_options`: (Optional) Additional [DTR install options](https://docs.docker.com/reference/dtr/2.6/cli/install/)
#### engine
Customizes the installation of Docker Enterprise Engine.
```yaml
cluster:
engine:
channel: "stable"
edition: "ee"
version: "19.03"
```
The following optional elements can be specified:
- `version`: (Optional) The version of the Docker Engine to install. Defaults to `19.03`.
- `edition`: (Optional) The family of Docker Engine to install. Defaults to `ee` for Enterprise edition.
- `channel`: (Optional) The channel on the repository to pull updated packages. Defaults to `stable`.
- `url`: (Optional) Defaults to "https://storebits.docker.com/ee".
- `storage_driver`: (Optional) The storage driver to use for the storage volume. Default
value is dependent on the operating system.
- Amazon Linux 2 is `overlay2`.
- Centos is `overlay2`.
- Oracle Linux is `overlay2`.
- RedHat is `overlay2`.
- SLES is `btrfs`.
- Ubuntu is `overlay2`.
- `storage_fstype`: (Optional) File system to use for storage volume. Default value is dependent on the operating system.
- Amazon Linux 2 is `xfs`.
- Centos is `xfs`.
- Oracle Linux is `xfs`.
- RedHat is `xfs`.
- SLES is `btrfs`.
- Ubuntu is `ext4`.
- `storage_volume`: (Optional) Docker storage volume path for `/var/lib/docker` Default value is provider dependent.
- AWS
- non-NVME is `/dev/xvdb`.
- NVME disks are one of `/dev/nvme[0-26]n1`.
- Azure is `/dev/disk/azure/scsi1/lun0`.
- `daemon`: (Optional) Provides docker daemon options. Defaults to "".
- `ca`: (dev) Defaults to "".
- `key`: (dev) Defaults to "".
- `enable_remote_tcp`: (dev) Enables direct access to docker engine. Defaults to `false`.
*dev indicates that the functionality is only for development and testing.
#### kubernetes
Enables provider-specific options for Kubernetes support.
##### AWS Kubernetes options
- `cloud_provider`: (Optional)Enable cloud provider support for Kubernetes. Defaults to `false`.
- `ebs_persistent_volumes`: (Optional) Enable persistent volume support with EBS volumes. Defaults to `false`.
- `efs_persistent_volumes`: (Optional) Enable persistent volume support with EFS. Defaults to `false`.
- `load_balancer`: (Optional) Enable Kubernetes pods to instantiate a load-balancer. Defaults to `false`.
- `nfs_storage`: (Optional) Install additional packages on node for NFS support. Defaults to `false`.
- `lifecycle`: (Optional) Defaults to `owned`.
#### registry
Customizes the registry from which the installation should pull images. By default, Docker Hub and credentials to access Docker Hub are used.
```yaml
cluster:
registry:
password: ${base64decode("TVJYeTNDQWpTSk5HTW1ZRzJQcE1kM0tVRlQ=")}
url: https://index.docker.io/v1/
username: user
```
The following optional elements can be specified:
- `username`: The username for logging in to the registry on each node. Default value is the current docker user.
- `url`: The registry to use for pulling Docker images. Defaults to "https://index.docker.io/v1/".
- `password`: The password for logging in to the registry on each node. Default value is the current docker user's password base64 encoded and wrapped in a call to base64decode.
#### ucp
- `version`: Specifies the version of UCP to install. Defaults to `docker/ucp:3.1.6`.
- `username`: Specifies the username of the first user to create in UCP. Defaults to `admin`.
- `password`: Specifies the password of the first user to create in UCP. Defaults to `dockerdocker`.
- `ca`: Specifies a path to a root CA public certificate.
- `key`: Specifies a path to a TLS private key.
- `cert`: Specifies a path to a public key certificate.
- `install_options`: Lists additional [UCP install options](https://docs.docker.com/reference/ucp/3.1/cli/install/)
##### Additional UCP configuration options:
Docker Cluster also accepts all UCP configuration options and creates the initial UCP config on
installation. The following list provides supported options:
- `anonymize_tracking`: Anonymizes analytic data. Specify 'true' to hide the license ID. Defaults to 'false'.
- `audit_level`: Specifies the audit logging level. Leave empty for disabling audit logs (default).
Other valid values are 'metadata' and 'request'.
- `auto_refresh`: Specify 'true' to enable attempted automatic license renewal when the license
nears expiration. If disabled, you must manually upload renewed license after expiration. Defaults to 'true'.
- `azure_ip_count`: Sets the IP count for azure allocator to allocate IPs per Azure virtual machine.
- `backend`: Specifie the name of the authorization backend to use, either 'managed' or 'ldap'. Defaults to 'managed'.
- `calico_mtu`: Specifies the MTU (maximum transmission unit) size for the Calico plugin. Defaults to '1480'.
- `cloud_provider`: Specifies the cloud provider for the kubernetes cluster.
- `cluster_label`: Specifies a label to be included with analytics/.
- `cni_installer_url`: Specifies the URL of a Kubernetes YAML file to be used for installing a CNI plugin.
Only applies during initial installation. If empty, the default CNI plugin is used.
- `controller_port`: Configures the port that the 'ucp-controller' listens to. Defaults to '443'.
- `custom_header_name`: Specifies the name of the custom header with 'name' = '*X-Custom-Header-Name*'.
- `custom_header_value`: Specifies the value of the custom header with 'value' = '*Custom Header Value*'.
- `default_new_user_role`: Specifies the role that new users get for their private resource sets.
Values are 'admin', 'viewonly', 'scheduler', 'restrictedcontrol', or 'fullcontrol'. Defaults to 'restrictedcontrol'.
- `default_node_orchestrator`: Specifies the type of orchestrator to use for new nodes that are
joined to the cluster. Can be 'swarm' or 'kubernetes'. Defaults to 'swarm'.
- `disable_tracking`: Specify 'true' to disable analytics of API call information. Defaults to 'false'.
- `disable_usageinfo`: Specify 'true' to disable analytics of usage information. Defaults to 'false'.
- `dns`: Specifies a CSV list of IP addresses to add as nameservers.
- `dns_opt`: Specifies a CSV list of options used by DNS resolvers.
- `dns_search`: Specifies a CSV list of domain names to search when a bare unqualified hostname is
used inside of a container.
- `enable_admin_ucp_scheduling`: Specify 'true' to allow admins to schedule on containers on manager nodes.
Defaults to 'false'.
- `external_service_lb`: Specifies an optional external load balancer for default links to services with
exposed ports in the web interface.
- `host_address`: Specifies the address for connecting to the DTR instance tied to this UCP cluster.
- `log_host`: Specifies a remote syslog server to send UCP controller logs to. If omitted, controller
logs are sent through the default docker daemon logging driver from the 'ucp-controller' container.
- `idpMetadataURL`: Specifies the Identity Provider Metadata URL.
- `image_repository`: Specifies the repository to use for UCP images.
- `install_args`: Specifies additional arguments to pass to the UCP installer.
- `ipip_mtu`: Specifies the IPIP MTU size for the calico IPIP tunnel interface.
- `kube_apiserver_port`: Configures the port to which the Kubernetes API server listens.
- `kv_snapshot_count`: Sets the key-value store snapshot count setting. Defaults to '20000'.
- `kv_timeout`: Sets the key-value store timeout setting, in milliseconds. Defaults to '5000'.
- `lifetime_minutes`: Specifies the initial session lifetime, in minutes. Defaults to `4320`, which is 72 hours.
- `local_volume_collection_mapping`: Stores data about collections for volumes in UCP's local KV store
instead of on the volume labels. This is used for enforcing access control on volumes.
- `log_level`: Specifies the logging level for UCP components. Values are syslog priority
levels (https://linux.die.net/man/5/syslog.conf): 'debug', 'info', 'notice', 'warning', 'err', 'crit', 'alert',
and 'emerg'.
- `managedPasswordDisabled`: Indicates if managed password is disabled. Defaults to false.
- `managedPasswordFallbackUser`: The fallback user when the managed password authentication is disabled. Defaults to "".
- `manager_kube_reserved_resources`: Specifies reserve resources for Docker UCP and Kubernetes components
that are running on manager nodes.
- `metrics_disk_usage_interval`: Specifies the interval for how frequently storage metrics are gathered.
This operation can impact performance when large volumes are present.
- `metrics_retention_time`: Adjusts the metrics retention time.
- `metrics_scrape_interval`: Specifies the interval for how frequently managers gather metrics from nodes in the cluster.
- `nodeport_range`: Specifies the port range that for Kubernetes services of type NodePort can be exposed in.
Defaults to '32768-35535'.
- `per_user_limit`: Specifies the maximum number of sessions that a user can have active simultaneously. If
the creation of a new session would put a user over this limit, the least recently used session is deleted.
A value of zero disables limiting the number of sessions that users can have. Defaults to `5`.
- `pod_cidr`: Specifies the subnet pool from which the IP for the Pod should be allocated from the CNI ipam plugin.
- `profiling_enabled`: Specify 'true' to enable specialized debugging endpoints for profiling UCP performance.
Defaults to 'false'.
- `log_protocol`: Specifies the protocol to use for remote logging. Values are 'tcp' and 'udp'. Defaults to 'tcp'.
- `renewal_threshold_minutes`: Specifies the length of time, in minutes, before the expiration of a
session. When used, a session is extended by the current configured lifetime from that point in time. A zero value disables session extension. Defaults to `1440`, which is 24 hours.
- `require_content_trust`: Specify 'true' to require images be signed by content trust. Defaults to 'false'.
- `require_signature_from`: Specifies a csv list of users or teams required to sign images.
- `rethinkdb_cache_size`: Sets the size of the cache used by UCP's RethinkDB servers. TDefaults to 1GB,
but leaving this field empty or specifying `auto` instructs RethinkDB to determine a cache size automatically.
- `rootCerts`: Defaults to empty.
- `samlEnabled`: Indicates if saml is used.
- `samlLoginText`: Specifies the customized SAML login button text.
- `service_id`: Specifies the DTR instance's OpenID Connect Client ID, as registered with the Docker
authentication provider.
- `spHost`: Specifies the Service Provider Host.
- `storage_driver`: Specifies the UCP storage driver to install.
- `support_dump_include_audit_logs`: When set to `true`, support dumps include audit logs in the logs
of the 'ucp-controller' container of each manager node. Defaults to 'false'.
- `swarm_port`: Configures the port that the 'ucp-swarm-manager' listens to. Defaults to '2376'.
- `swarm_strategy`: Configures placement strategy for container scheduling.
This doesn't affect swarm-mode services. Values are 'spread', 'binpack', and 'random'.
- `tlsSkipVerify`: Specifies TLS Skip verify for IdP Metadata.
- `unmanaged_cni`: Defaults to 'false'.
- `worker_kube_reserved_resources`: Reserves resources for Docker UCP and Kubernetes components
that are running on worker nodes.
- `custom_kube_api_server_flags`: Specifies the configuration options for the Kubernetes API server. (dev)
- `custom_kube_controller_manager_flags`: Specifies the configuration options for the Kubernetes controller manager. (dev)
- `custom_kube_scheduler_flags`: Specifies the configuration options for the Kubernetes scheduler. (dev)
- `custom_kubelet_flags`: Specifies the configuration options for Kubelets. (dev)
*dev indicates that the functionality is only for development and testing. Arbitrary Kubernetes configuration parameters are not tested and supported under the Docker Enterprise Software Support Agreement.
### provider
Defines where the cluster's resources are provisioned, as well as provider-specific configuration such as tags.
```yaml
provider:
acme:
email: ${email}
server_url: https://acme-staging-v02.api.letsencrypt.org/directory
aws:
region: ${region}
```
#### acme
The Automated Certificate Management Environment (ACME) is an evolving standard for the automation of a domain-validated certificate authority. Docker Cluster uses the ACME provider to create SSL certificates that are signed by [Let's Encrypt](https://letsencrypt.org/).
The ACME provider Configuration for the ACME provider supports arguments that closely align with the [Terraform ACME provider](https://www.terraform.io/docs/providers/acme/index.html):
The following elements can be specified:
- `email`: (Required) The email to associate the certificates with.
- `server_url`: (Optional) The URL to the ACME endpoint's directory. Default is "https://acme-v02.api.letsencrypt.org/directory"
#### aws
Configuration for the AWS provider supports arguments that closely align with the [Terraform AWS provider](https://www.terraform.io/docs/providers/aws/index.html).
```yaml
aws:
region: "us-east-1"
tags:
Owner: "Infra"
Environment: "Test"
```
The following elements can be specified:
- `region` - (Required) This is the AWS region. It can be sourced from the `AWS_DEFAULT_REGION` environment variables, or
via a shared credentials file if `profile` is specified.
- `tags` - (Optional) Additional name value pairs to assign to every resource (which
supports tagging) in the cluster.
- `access_key` - (Required) This is the AWS access key. It can be sourced from
the `AWS_ACCESS_KEY_ID` environment variable, or via
a shared credentials file if `profile` is specified.
- `secret_key` - (Required) This is the AWS secret key. It can be sourced from
the `AWS_SECRET_ACCESS_KEY` environment variable, or
via a shared credentials file if `profile` is specified.
- `profile` - (Optional) This is the AWS profile name as set in the shared credentials
file.
- `assume_role` - (Optional) An `assume_role` block (documented below). Only one
`assume_role` block can be in the configuration.
- `endpoints` - (Optional) Configuration block for customizing service endpoints. See the
[Custom Service Endpoints Guide](/docs/providers/aws/guides/custom-service-endpoints.html)
for more information about connecting to alternate AWS endpoints or AWS compatible solutions.
- `shared_credentials_file` = (Optional) This is the path to the shared
credentials file. If this is not set and a profile is specified,
`~/.aws/credentials` is used.
- `token` - (Optional) Session token for validating temporary credentials.
Typically provided after successful identity federation or Multi-Factor
Authentication (MFA) login. With MFA login, this is the session token
provided afterwards, not the 6 digit MFA code used to get temporary
credentials. It can also be sourced from the `AWS_SESSION_TOKEN`
environment variable.
- `max_retries` - (Optional) This is the maximum number of times an API
call is retried, in the case where requests are being throttled or
experiencing transient failures. The delay between the subsequent API
calls increases exponentially.
- `allowed_account_ids` - (Optional) List of allowed, white listed, AWS
account IDs to prevent you from mistakenly using an incorrect one (and
potentially end up destroying a live environment). Conflicts with
`forbidden_account_ids`.
- `forbidden_account_ids` - (Optional) List of forbidden, blacklisted,
AWS account IDs to prevent you mistakenly using a wrong one (and
potentially end up destroying a live environment). Conflicts with
`allowed_account_ids`.
- `insecure` - (Optional) Explicitly allows the provider to
perform "insecure" SSL requests. If omitted, defaults to `false`.
- `skip_credentials_validation` - (Optional) Skips the credentials
validation via the STS API. Useful for AWS API implementations that do
not have STS available or implemented.
- `skip_get_ec2_platforms` - (Optional) Skips getting the supported EC2
platforms. Used by users that don't have `ec2:DescribeAccountAttributes`
permissions.
- `skip_region_validation` - (Optional) Skips validation of provided region name.
Useful for AWS-like implementations that use their own region names
or to bypass the validation for regions that aren't publicly available yet.
### resource
Resources to provision for a cluster. Resources are organized as shown in the following example:
```yaml
resource:
type:
name:
parameters
```
For a given `type`, there may be more one or more named resources to provision.
For a given `name`, a resource may have one or more parameters.
#### aws_instance
```yaml
resource:
aws_instance:
workers:
instance_type: t2.xlarge
price: 0.25
os: Ubuntu 16.04
```
- `quantity`: (Required) The number of instances to create.
- `os`: An alias that is expanded by `docker cluster` to the AMI owner and AMI name to install.
The following aliases are supported by `docker cluster`:
- `CentOS 7`
- `RHEL 7.1`
- `RHEL 7.2`
- `RHEL 7.3`
- `RHEL 7.4`
- `RHEL 7.5`
- `RHEL 7.6`
- `Oracle Linux 7.3`
- `Oracle Linux 7.4`
- `Oracle Linux 7.5`
- `SLES 12.2`
- `SLES 12.3`
- `SLES 15`
- `Ubuntu 14.04`
- `Ubuntu 16.04`
- `Ubuntu 18.04`
- `Windows Server 2016`
- `Windows Server 1709`
- `Windows Server 1803`
- `Windows Server 2019`
> Note: Make sure the OS you select is [compatible](https://success.docker.com/article/compatibility-matrix)
with the product you're installing. Docker Cluster validates the support during installation.
- `instance_type`: Specifies the [AWS instance type](https://aws.amazon.com/ec2/instance-types/) to provision.
- `key_name`: By default, Docker Cluster creates an [AWS EC2 Key Pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) and registers it with AWS for the cluster.
To use an existing AWS EC2 Key Pair, set this value to the name of the AWS EC2 Key Pair.
- `ssh_private_key`: By default, Docker Cluster creates an [AWS EC2 Key Pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) and registers it with AWS for the cluster. To use an existing AWS EC2 Key Pair, set this value to the path of the private SSH key.
- `username`: Specifies the username for the node with Administrative privileges. By default, the `os` option
sets this to the well-known username for the AMIs (which can change by distribution):
- Amazon Linux 2 is `ec2-user`.
- Centos is `centos`.
- Oracle Linux is `ec2-user`.
- RedHat is `ec2-user`.
- SLES is `ec2-user`.
- Ubuntu is `ubuntu`.
- Windows is `Administrator`.
- `password`: This value is only used by Windows nodes. By default, Windows nodes have a random password generated.
- `ami`: Specifies a custom AMI, or one that's not currently available as an OS. Specify either the id or
the owner/name to query for the latest.
- `id`: Specifies the ID of the AMI. For example, `ami-0510c89f1a2691cf2`.
- `owner`: Specifies the AWS account ID of the image owner. For example, `099720109477`.
- `name`: Specifies the name of the AMI that was provided during image creation. For example, `ubuntu/images/hvm-ssd/ubuntu-xenial-16.04-amd64-server-*`.
- `platform`: Specify `windows` for Windows instances.
- `tags`: (Optional) Specifies additional name value pairs to assign to every instance.
- `swarm_labels`: (Optional) Specifies additional key value pairs that represent swarm labels to apply to every node.
#### aws_spot_instance_request
Provisions a spot instance request in AWS to dramatically reduce the cost of instances. Spot instance
availability is not guaranteed. Therefore, it is recommended to use `aws_spot_instance_request` for
additional worker nodes and not for mission-critical nodes like managers and registry.
```yaml
resource:
aws_spot_instance_request:
workers:
instance_type: t2.xlarge
price: 0.25
os: Ubuntu 16.04
quantity: 3
```
Supports the same set of parameters as [aws_instance](index.md#aws_instance), with the addition of an optional price to limit the max bid for a spot instance.
- `price`: (Optional) Specifies a maximum price to bid on the spot instance.
#### aws_lb
Provisions an AWS Load Balancer.
```yaml
resource:
aws_lb:
ucp:
domain: "example.com"
instances:
- managers
ports:
- 443:443
- 6443:6443
```
The following options are supported:
- `instances`: (Required) Specifies a list of `aws_instance` and `aws_spot_instance_request` names to
attach to the load balancer.
- `ports`: (Required) Specifies a list of `listening port[/protocol]:target port[/protocol]` mappings
to define how the load balancer should route traffic. By default, the protocol is `tcp`.
- `domain`: Specifies the domain in which to create DNS records for this load balancer. The record is named the
same as this resource, appended by the domain. For example, if the resource is `ucp` and the domain is `example.com`,
the `A` record is `ucp.example.com`.
- `internal`: (Optional) Defaults to `false`.
- `type`: (Optional) Defaults to `network`.
- `enable_cross_zone_load_balancing`: (Optional) Defaults to `false`.
#### aws_route53_zone
Creates a subdomain in an AWS route53 zone. The following example creates a public zone for `testing.example.com`:
```yaml
resource:
aws_route53_zone:
dns:
domain: example.com
subdomain: testing
```
The following elements are required:
- `domain`: (Required) Specifies the name of the hosted zone.
- `subdomain`: (Required) Specifies the subdomain to create in the `domain` hosted zone.
### variable
Docker cluster supports basic parameterization. The variable section defines a make of keys and values. A key can have a sub-key named `type`, which changes the behavior of the variable.
```yaml
variable:
region: "us-east-1"
password:
type: prompt
```
Variables are referenced in the cluster definition as `${variable_name}`. For example, `${region}` is substituted as `us-east-2` through the cluster definition.
The type defines how the variable behaves. This is currently limited in scope to:
- `prompt`: Requests the value from the user and does not echo characters as the value is entered.

BIN
cluster/images/docker_cluster_aws.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

60
cluster/overview.md Normal file
View File

@ -0,0 +1,60 @@
---
description: Introduction and Overview of Docker Cluster
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: Overview of Docker Cluster
---
Docker Cluster is a tool for lifecycle management of Docker clusters.
With Cluster, you use a YAML file to configure your provider's resources.
Then, with a single command, you provision and install all the resources
from your configuration.
Using Docker Cluster is a three-step process:
1. Ensure you have the credentials necessary to provision a cluster.
2. Define the resources that make up your cluster in `cluster.yml`
3. Run `docker cluster create` to have Cluster provision resources and install Docker Enterprise on the resources.
A `cluster.yml` file resembles the following example:
variable:
region: us-east-2
ucp_password:
type: prompt
provider:
aws:
region: ${region}
cluster:
engine:
version: "ee-stable-18.09.5"
ucp:
version: "docker/ucp:3.1.6"
username: "admin"
password: ${ucp_password}
resource:
aws_instance:
managers:
quantity: 1
For more information about Cluster files, refer to the
[Cluster file reference](cluster-file/index.md).
Docker Cluster has commands for managing the whole lifecycle of your cluster:
* Create and destroy clusters
* Scale up or Scale down clusters
* Upgrade clusters
* View the status of clusters
* Backup and Restore clusters
## Cluster documentation
- [Get started with Docker Cluster on AWS](aws.md)
- [Command line reference](./reference/index.md)
- [Cluster file reference](./cluster-file/index.md)

21
cluster/reference/backup.md Normal file
View File

@ -0,0 +1,21 @@
---
description: Back up a running cluster
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: docker cluster backup
notoc: true
---
## Usage
```
docker cluster backup [OPTIONS] cluster
```
Use the following options as needed to back up a running cluster:
- `--dry-run`: Skips resource provisioning.
- `--file string`: Specifies a cluster backup filename. Defaults to `backup.tar.gz`.
- `--log-level string`: Specifies the logging level. Valid values include: `trace`,`debug`,`info`,`warn`,`error`, and `fatal`.
Defaults to `warn`.
- `--passphrase string`: Specifies a cluster backup passphrase.
The backup command performs a full Docker Cluster backup following the steps found in [Backup and Restore Best Practices](https://success.docker.com/article/backup-restore-best-practices).

73
cluster/reference/envvars.md Normal file
View File

@ -0,0 +1,73 @@
---
description: Cluster CLI environment variables
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: Cluster CLI environment variables
---
Use the following environment variables as needed to configure the Docker Cluster command-line behavior.
## AWS\_ACCESS\_KEY\_ID
Represents your AWS Access Key. Overrides the use of `AWS_SHARED_CREDENTIALS_FILE` and `AWS_PROFILE`.
```bash
export AWS_ACCESS_KEY_ID="AKIFAKEAWSACCESSKEYNLQ"
```
## AWS\_SECRET\_ACCESS\_KEY
Represents your AWS Secret Key. Overrides the use of `AWS_SHARED_CREDENTIALS_FILE` and `AWS_PROFILE`.
```bash
export AWS_SECRET_ACCESS_KEY="3SZYfAkeS3cr3TKey+L0ok5/rEalBu71sFak3vmy"
```
## AWS\_DEFAULT\_REGION
Specifies the AWS region to provision resources.
```bash
export AWS_DEFAULT_REGION="us-east-1"
```
## AWS\_PROFILE
Specifies the AWS profile name as set in the shared credentials file.
```bash
export AWS_PROFILE="default"
```
## AWS\_SESSION\_TOKEN
Specifies the session token used for validating temporary credentials. This is typically provided after
successful identity federation or Multi-Factor Authentication (MFA) login. With MFA login, this is the
session token provided afterwards, not the 6 digit MFA code used to get temporary credentials.
```bash
export AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of security token>
```
## AWS\_SHARED\_CREDENTIALS\_FILE
Specifies the path to the shared credentials file. If this is not set and a profile is specified, `~/.aws/credentials`
is used.
```bash
export AWS_SHARED_CREDENTIALS_FILE="~/.production/credentials"
```
## CLUSTER\_ORGANIZATION
Specifies the Docker Hub organization to pull the `cluster` container.
```bash
export CLUSTER_ORGANIZATION="docker"
```
## CLUSTER\_TAG
Specifies the tag of the `cluster` container to pull.
```bash
export CLUSTER_TAG="latest"
```
## DOCKER\_PASSWORD
Overrides docker password lookup from `~/.docker/config.json`.
```bash
export DOCKER_PASSWORD="il0v3U3000!"
```
## DOCKER\_USERNAME
Overrides docker username lookup from `~/.docker/config.json`.
```bash
export DOCKER_USERNAME="ironman"
```

24
cluster/reference/index.md Normal file
View File

@ -0,0 +1,24 @@
---
description: Cluster CLI reference
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: Cluster command-line reference
notoc: true
---
The following pages describe the usage information for the [docker cluster](overview) subcommands. You can also view this information by running `docker cluster [subcommand] --help` from the command line.
* [docker cluster](overview)
* [backup](backup)
* [create](create)
* [inspect](inspect)
* [logs](logs)
* [ls](ls)
* [restore](restore)
* [rm](rm)
* [update](update)
* [version](version)
## Where to go next
* [CLI environment variables](envvars)
* [docker cluster command](overview)

16
cluster/reference/inspect.md Normal file
View File

@ -0,0 +1,16 @@
---
description: Inspect clusters
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: docker cluster inspect
notoc: true
---
## Usage
```
docker cluster inspect [OPTIONS] cluster
```
Use the following options as needed to display detailed information about a cluster:
- `-a, --all`: Displays complete information about the cluster.
- `--dry-run`: Skips resource provisioning.
- `--log-level string`: Specifies the logging level. Valid values include: `trace`,`debug`,`info`,`warn`,`error`, and `fatal`. Defaults to `warn`.

16
cluster/reference/ls.md Normal file
View File

@ -0,0 +1,16 @@
---
description: List all available clusters
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: docker cluster ls
notoc: true
---
## Usage
```
docker cluster ls [OPTIONS]
```
Use the following options as needed to list all available clusters:
- `--dry-run`: Skips resource provisioning.
- `--log-level string`: Specifies the logging level. Valid values include: `trace`,`debug`,`info`,`warn`,`error`, and `fatal`. Defaults to `warn`.
- `-q`, `--quiet`: Displays only numeric IDs.

49
cluster/reference/overview.md Normal file
View File

@ -0,0 +1,49 @@
---
description: Overview of docker cluster CLI
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: Overview of docker cluster CLI
---
This page provides usage information for the `docker cluster` CLI plugin command options.
You can also view this information by running `docker cluster --help` from the
command line.
## Usage
```
docker cluster [Options] [Commands]
```
Options:
- `--dry-run`: Skips resource provisioning.
- `--log-level string`: Specifies the logging level. Valid values include: `trace`,`debug`,`info`,`warn`,`error`, and `fatal`. Defaults to `warn`.
Commands:
- `backup`: Backs up a running cluster.
- `begin`: Creates an example cluster declaration.
- `create`: Creates a new Docker cluster.
- `inspect`: Provides detailed information about a cluster.
- `logs`:TODO: Fetches cluster logs.
- `ls`: Lists all available clusters.
- `restore`: Restores a cluster from a backup.
- `rm`: Removes a cluster.
- `update`: Updates a running cluster's desired state.
- `version`: Displays Version, Commit, and Build type.
Run 'docker cluster [Command] --help' for more information about a command.
```
## Specify name and path of one or more cluster files
Use the `-f` flag to specify the location of a cluster configuration file.
## Set up environment variables
You can set [environment variables](envvars) for various
`docker cluster` options, including the `-f` and `-p` flags.
## Where to go next
* [CLI environment variables](envvars)

20
cluster/reference/restore.md Normal file
View File

@ -0,0 +1,20 @@
---
description: Restore to a running cluster
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: docker cluster restore
notoc: true
---
## Usage
```
docker cluster restore [OPTIONS] cluster
```
Use the following options as needed to restore a cluster from a backup:
- `--dry-run`: Skips resource provisioning.
- `--file string`: Specifies a cluster backup filename. Defaults to `backup.tar.gz`.
- `--log-level string`: Specifies the logging level. Valid values include:
`trace`,`debug`,`info`,`warn`,`error`, and `fatal`. Defaults to `warn`.
- `--passphrase string`: Specifies a cluster backup passphrase.
The restore command performs a full Docker Cluster restore following the steps found in [Backup and Restore Best Practices](https://success.docker.com/article/backup-restore-best-practices).

16
cluster/reference/rm.md Normal file
View File

@ -0,0 +1,16 @@
---
description: Remove a cluster
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: docker cluster rm
notoc: true
---
## Usage
```
docker cluster rm [OPTIONS] cluster
```
Use the following options as needed when removing a cluster:
- `--dry-run`: Skips resource provisioning.
- `-f`, `--force`: Forces removal of the cluster files.
- `--log-level string`: Specifies the logging level. Valid values include: `trace`,`debug`,`info`,`warn`,`error`, and `fatal`. Defaults to `warn`.

18
cluster/reference/update.md Normal file
View File

@ -0,0 +1,18 @@
---
description: Update a cluster
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: docker cluster update
notoc: true
---
## Usage
```
docker cluster update [Options] cluster
```
Use the following options as needed to update a running cluster's desired state:
Options:
- `--dry-run`: Skips resource provisioning.
- `-f`, `--file string`: Specfies cluster definition.
- `--log-level string`: Specifies the logging level. Valid values include: `trace`,`debug`,`info`,`warn`,`error`, and `fatal`. Defaults to `warn`.

15
cluster/reference/version.md Normal file
View File

@ -0,0 +1,15 @@
---
description: Print Version
keywords: documentation, docs, docker, cluster, infrastructure, automation
title: docker cluster version
notoc: true
---
## Usage
```
docker cluster version
```
Use the following options as needed for printing Version, Commit, and Build type:
- `--dry-run`: Skips resource provisioning.
- `--log-level string`: Specifies the logging level. Valid values include: `trace`,`debug`,`info`,`warn`,`error`, and `fatal`. Defaults to `warn`.