Docker¶

The minidcos docker CLI allows you to create, manage and destroy open source DC/OS and DC/OS Enterprise clusters on Docker nodes.

A typical CLI workflow for open source DC/OS may look like the following. Install the CLI (see Installation), then create and manage a cluster:

Fix issues shown by minidcos docker doctor
minidcos docker doctor
minidcos docker download-installer
minidcos docker create ./dcos_generate_config.sh --agents 0
default
minidcos docker wait
minidcos docker run --test-env --sync-dir /path/to/dcos/checkout pytest -k test_tls
...
Get onto a node
minidcos docker run bash
[master-0]# exit
minidcos docker destroy

Each of these and more are described in detail below.

Requirements
Creating a Cluster
- Using a custom Docker network
- DC/OS Enterprise
Cluster IDs
Running commands on Cluster Nodes
Getting on to a Cluster Node
Destroying Clusters
Running Integration Tests
Viewing the Web UI
- macOS
Using a Custom CA Certificate
Using a Loopback Sidecar
Limitations
- SELinux
- Storage
- Reboot
- Resources UI
- Marathon-LB
CLI Reference
- minidcos docker
  - clean
  - create
  - create-loopback-sidecar
  - destroy
  - destroy-list
  - destroy-loopback-sidecar
  - destroy-mac-network
  - doctor
  - download-installer
  - inspect
  - install
  - list
  - list-loopback-sidecars
  - provision
  - run
  - send-file
  - setup-mac-network
  - sync
  - upgrade
  - wait
  - web

Requirements ¶

Docker 17.06+¶

Docker version 17.06 or later must be installed.

Plenty of memory must be given to Docker. On Docker for Mac, this can be done from Docker > Preferences > Advanced. This backend has been tested with a four node cluster with 9 GB memory given to Docker.

IP Routing Set Up for Docker ¶

On macOS, hosts cannot connect to containers IP addresses by default. This is required, for example, to access the web UI, to SSH to nodes and to use the DC/OS CLI.

Once the CLI is installed, run setup-mac-network to set up IP routing.

Without this, it is still possible to use some features. Specify the --transport docker-exec and --skip-http-checks options where available.

`ssh`¶

The ssh command must be available to use the ssh transport options.

Operating System ¶

This tool has been tested on macOS with Docker for Mac and on Linux.

It has also been tested on Windows on Vagrant.

Windows ¶

The only supported way to use the Docker backend on Windows is using Vagrant and VirtualBox.

Ensure Virtualization and VT-X support is enabled in your PC’s BIOS. Disable Hyper-V virtualization. See https://www.howtogeek.com/213795/how-to-enable-intel-vt-x-in-your-computers-bios-or-uefi-firmware/.
Install VirtualBox and VirtualBox Extension Pack.
Install Vagrant.
Install the Vagrant plugin for persistent disks:

vagrant plugin install vagrant-persistent-storage

Optionally install the Vagrant plugins to cache package downloads and keep guest additions updates:

vagrant plugin install vagrant-cachier
vagrant plugin install vagrant-vbguest

Start Powershell and download the miniDC/OS Vagrantfile to a directory containing a DC/OS installer file:

((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/|github-owner|/|github-repository|/master/vagrant/Vagrantfile')) | Set-Content -LiteralPath Vagrantfile

By default, the Vagrantfile installs miniDC/OS from the most recent release at the time it is downloaded. To use a different release, or any Git reference, set the environment variable DCOS_E2E_REF:

$env:DCOS_E2E_REF = "master"

Start the virtual machine and login:

vagrant up
vagrant ssh

You can now run Docker commands.

To connect to the cluster nodes from the Windows host (e.g. to use the DC/OS web interface), in PowerShell Run as Administrator, and add the Virtual Machine as a gateway:

route add 172.17.0.0 MASK 255.255.0.0 192.168.18.2

To shutdown, logout of the virtual machine shell, and destroy the virtual machine and disk:

vagrant destroy

The route will be removed on reboot. You can manually remove the route in PowerShell Run as Administrator using:

route delete 172.17.0.0

`doctor` command ¶

minidcos docker comes with the doctor command. Run this command to check your system for common causes of problems.

Creating a Cluster ¶

To create a cluster you first need to download a DC/OS installer.

This can be done via the releases page or with the download-installer command.

DC/OS Enterprise is also supported. Ask your sales representative for installers.

Creating a cluster is possible with the create command. This command allows you to customize the cluster in many ways.

The command returns when the DC/OS installation process has started. To wait until DC/OS has finished installing, use the wait command.

To use this cluster, it is useful to find details using the inspect command.

Using a custom Docker network ¶

By default DC/OS clusters are launched on the docker0 network.

To launch a DC/OS cluster on a custom Docker network the network must first be created using the standard Docker CLI. During create the command line option --network then takes the name of the Docker network as a parameter.

DC/OS nodes utilize an environment-specific ip-detect script to detect their current private IP address. The default ip-detect script used by minidcos docker does only account for the docker0 network case. Therefore, in order for DC/OS to operate on a custom network a custom ip-detect script needs to be provided and put into the genconf directory before installing DC/OS.

The following IP detect script works for any custom Docker network:

!/bin/bash -e
if [ -f /sbin/ip ]; then
   IP_CMD=/sbin/ip
else
   IP_CMD=/bin/ip
fi
IP_CMD -4 -o addr show dev eth1 | awk '{split($4,a,"/");print a[1]}'

The create command supports overwriting the default genconf directory with the contents of the directory supplied through the command line option --genconf-dir.

Create ip-detect as mentioned above
docker network create custom-bridge
mkdir custom-genconf
mv ip-detect custom-genconf/ip-detect
minidcos docker create /path/to/dcos_generate_config.sh \
    --network custom-bridge \
    --genconf-dir ./custom-genconf

The custom Docker network is not cleaned up by the minidcos docker CLI.

DC/OS Enterprise ¶

There are multiple DC/OS Enterprise-only features available in create.

The only extra requirement is to give a valid license key, for DC/OS 1.11+. See create for details on how to provide a license key.

Ask your sales representative for DC/OS Enterprise installers.

For, example, run the following to create a DC/OS Enterprise cluster in strict mode:

minidcos docker create /path/to/dcos_generate_config.ee.sh \
     --license-key /path/to/license.txt \
     --security-mode strict

The command returns when the DC/OS installation process has started. To wait until DC/OS has finished installing, use the wait command.

See create for details on this command and its options.

Cluster IDs ¶

Clusters have unique IDs. Multiple commands take --cluster-id options. Specify a cluster ID in create, and then use it in other commands. Any command which takes a --cluster-id option defaults to using “default” if no cluster ID is given.

Running commands on Cluster Nodes ¶

It is possible to run commands on a cluster node in multiple ways. These include using run, docker exec and ssh.

Running commands on a cluster node using run ¶

It is possible to run the following to run a command on an arbitrary master node.

minidcos docker run systemctl list-units

See run for more information on this command. In particular see the --node option to choose a particular node to run the command on.

Running commands on a cluster node using `docker exec`¶

Each cluster node is a Docker container. This means that you can use tools such as docker exec to run commands on nodes. To do this, first choose the container ID of a node. Use inspect to see all node container IDs.

Running commands on a cluster node using `ssh`¶

One SSH key allows access to all nodes in the cluster. See this SSH key’s path and the IP addresses of nodes using inspect. The available SSH user is root.

Getting on to a Cluster Node ¶

Sometimes it is useful to get onto a cluster node. To do this, you can use any of the ways of Running commands on Cluster Nodes.

For example, to use run to run bash to get on to an arbitrary master node:

minidcos docker run example bash

or, similarly, to use docker exec to get on to a specific node:

eval $(minidcos docker inspect --env)
docker exec -it $MASTER_0 bash

See Running commands on Cluster Nodes for details on how to choose particular nodes.

Destroying Clusters ¶

There are two commands which can be used to destroy clusters. These are destroy and destroy-list.

Either destroy a cluster with destroy:

minidcos docker destroy
default
minidcos docker destroy --cluster-id pr_4033_strict
pr_4033_strict

or use destroy-list to destroy multiple clusters:

minidcos docker destroy-list pr_4033_strict pr_4019_permissive
pr_4033_strict
pr_4019_permissive

To destroy all clusters, run the following command:

minidcos docker destroy-list $(minidcos docker list)
pr_4033_strict
pr_4019_permissive

Running Integration Tests ¶

The run command is useful for running integration tests.

To run integration tests which are developed in the a DC/OS checkout at /path/to/dcos, you can use the following workflow:

minidcos docker create ./dcos_generate_config.sh
minidcos docker wait
minidcos docker run --test-env --sync-dir /path/to/dcos/checkout pytest -k test_tls.py

There are multiple options and shortcuts for using these commands. See run for more information on this command.

Viewing the Web UI ¶

To view the web UI of your cluster, use the web command. To see the web UI URL of your cluster, use the inspect command.

Before viewing the UI, you may first need to configure your browser to trust your DC/OS CA, or choose to override the browser protection.

macOS ¶

On macOS, by default, viewing the web UI requires IP routing to be set up. Use setup-mac-network to set up IP routing.

The web UI is served by master nodes on port 80. To view the web UI on macOS without setting up IP routing, use the --one-master-host-port-map option on the create command to forward port 80 to your host. For example:

minidcos docker create ./dcos_generate_config.sh --one-master-host-port-map 70:80
minidcos docker wait
open localhost:70

Using a Custom CA Certificate ¶

On DC/OS Enterprise clusters, it is possible to use a custom CA certificate. See the Custom CA certificate documentation for details. It is possible to use create to create a cluster with a custom CA certificate.

Create or obtain the necessary files:

dcos-ca-certificate.crt, dcos-ca-certificate-key.key, and dcos-ca-certificate-chain.crt.
Put the above-mentioned files into a directory, e.g. /path/to/genconf/.
Create a file containing the “extra” configuration.

create takes an --extra-config option. This adds the contents of the specified YAML file to a minimal DC/OS configuration.

Create a file with the following contents:
```
ca_certificate_path: genconf/dcos-ca-certificate.crt
ca_certificate_key_path: genconf/dcos-ca-certificate-key.key
ca_certificate_chain_path: genconf/dcos-ca-certificate-chain.crt
```

Create a cluster.

minidcos docker create \
    /path/to/dcos_generate_config.ee.sh \
    --variant enterprise \
    --genconf-dir /path/to/genconf/ \
    --copy-to-master /path/to/genconf/dcos-ca-certificate-key.key:/var/lib/dcos/pki/tls/CA/private/custom_ca.key \
    --license-key /path/to/license.txt \
    --extra-config config.yml

Verify that everything has worked.

See Verify installation for steps to verify that the DC/OS Enterprise cluster was installed properly with the custom CA certificate.

Using a Loopback Sidecar ¶

The create-loopback-sidecar command can be used to create a loopback sidecar. This will provide all containers with a unformatted block device, mounted as a loopback device. All containers have access to this loopback device. Therefore, care must be taken that only a single container has write-access to it.

minidcos docker create-loopback-sidecar sidecar1
/dev/loop0
minidcos docker create /tmp/dcos_generate_config.sh
minidcos docker wait
minidcos docker destroy-loopback-sidecar sidecar1

Loopback sidecars can be listed with list-loopback-sidecars. Loopback sidecars can be destroyed with destroy-loopback-sidecar.

Limitations ¶

Docker does not represent a real DC/OS environment with complete accuracy. This section describes the currently known differences between clusters created with minidcos docker and a real DC/OS environment.

SELinux ¶

Tests inherit the host’s environment. Any tests that rely on SELinux being available require it be available on the host.

Storage ¶

Docker does not support storage features expected in a real DC/OS environment.

Reboot ¶

DC/OS nodes cannot be rebooted. The cluster cannot survive a system reboot.

Resources UI ¶

The DC/OS web UI Resources tab shows resources available to each DC/OS node. On a minidcos docker cluster, resources are not specific to one node. That means, if the cluster has 16 GB memory available in total, the web UI will show that each node has 16 GB memory available.

Marathon-LB ¶

Network configuration options vary by kernel version. If you see the following when installing Marathon-LB, change the Marathon-LB sysctl-params configuration value:

sysctl: cannot stat /proc/sys/net/ipv4/tcp_tw_reuse: No such file or directory
sysctl: cannot stat /proc/sys/net/ipv4/tcp_max_syn_backlog: No such file or directory
sysctl: cannot stat /proc/sys/net/ipv4/tcp_max_tw_buckets: No such file or directory
sysctl: cannot stat /proc/sys/net/ipv4/tcp_max_orphans: No such file or directory

Remove the relevant sysctl-params values. This may leave:

net.ipv4.tcp_fin_timeout=30 net.core.somaxconn=10000

CLI Reference ¶

minidcos docker ¶

Manage DC/OS clusters on Docker.

minidcos docker [OPTIONS] COMMAND [ARGS]...

clean ¶

Remove containers, volumes and networks created by this tool.

minidcos docker clean [OPTIONS]

Options

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

create ¶

Create a DC/OS cluster.

DC/OS Enterprise

DC/OS Enterprise clusters require different configuration variables to DC/OS OSS. For example, enterprise clusters require the following configuration parameters:

superuser_username, superuser_password_hash, fault_domain_enabled, license_key_contents

These can all be set in --extra-config. However, some defaults are provided for all but the license key.

The default superuser username is bootstrapuser. The default superuser password is deleteme. The default fault_domain_enabled is false.

license_key_contents must be set for DC/OS Enterprise 1.11 and above. This is set to one of the following, in order:

* The license_key_contents set in --extra-config. * The contents of the path given with --license-key. * The contents of the path set in the DCOS_LICENSE_KEY_PATH environment variable.

If none of these are set, license_key_contents is not given.

minidcos docker create [OPTIONS] INSTALLER

Options

--docker-version <docker_version>¶

The Docker version to install on the nodes. This can be provided by setting the MINIDCOS_NODE_DOCKER_VERSION environment variable. [default: 18.06.3-ce]

Options: 1.11.2|1.13.1|17.12.1-ce|18.06.3-ce

--linux-distribution <linux_distribution>¶

The Linux distribution to use on the nodes. [default: centos-7]

Options: centos-7|centos-8|coreos|flatcar|ubuntu-16.04

--docker-storage-driver <docker_storage_driver>¶

The storage driver to use for Docker in Docker. By default this uses the host’s driver. [default: auto]

Options: aufs|auto|overlay|overlay2

--mount-sys-fs-cgroup, --no-mount-sys-fs-cgroup¶: Mounting /sys/fs/cgroup from the host is required to run applications which require cgroup isolation. Choose to not mount /sys/fs/cgroup if it is not available on the host. [default: True]

--masters <masters>¶: The number of master nodes. [default: 1]

--agents <agents>¶: The number of agent nodes. [default: 1]

--public-agents <public_agents>¶: The number of public agent nodes. [default: 1]

--extra-config <extra_config>¶: The path to a file including DC/OS configuration YAML. The contents of this file will be added to add to a default configuration.

--security-mode <security_mode>¶

The security mode to use for a DC/OS Enterprise cluster. This overrides any security mode set in --extra-config.

Options: disabled|permissive|strict

-c, --cluster-id <cluster_id>¶: A unique identifier for the cluster. Use the value “default” to use this cluster for other commands without specifying –cluster-id.

--license-key <license_key>¶: This is ignored if using open source DC/OS. If using DC/OS Enterprise, this defaults to the value of the DCOS_LICENSE_KEY_PATH environment variable.

--genconf-dir <files_to_copy_to_genconf_dir>¶: Path to a directory that contains additional files for the DC/OS installer. All files from this directory will be copied to the “genconf” directory before running the DC/OS installer.

--copy-to-master <copy_to_master>¶: Files to copy to master nodes before installing DC/OS. This option can be given multiple times. Each option should be in the format /absolute/local/path:/remote/path.

--custom-volume <custom_volume>¶: Bind mount a volume on all cluster node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--custom-master-volume <custom_master_volume>¶: Bind mount a volume on all cluster master node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--custom-agent-volume <custom_agent_volume>¶: Bind mount a volume on all cluster agent node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--custom-public-agent-volume <custom_public_agent_volume>¶: Bind mount a volume on all cluster public agent node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--workspace-dir <workspace_dir>¶: Creating a cluster can use approximately 2 GB of temporary storage. Set this option to use a custom “workspace” for this temporary storage. See https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir for details on the temporary directory location if this option is not set.

--variant <variant>¶

Choose the DC/OS variant. If the variant does not match the variant of the given installer, an error will occur. Using “auto” finds the variant from the installer. Finding the variant from the installer takes some time and so using another option is a performance optimization.

Options: auto|oss|enterprise

--wait-for-dcos¶: Wait for DC/OS after creating the cluster. This is equivalent to using “minidcos docker wait” after this command. “minidcos docker wait” has various options available and so may be more appropriate for your use case. If the chosen transport is “docker-exec”, this will skip HTTP checks and so the cluster may not be fully ready.

--network <network>¶: The Docker network containers will be connected to.It may not be possible to SSH to containers on a custom network on macOS.

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

--one-master-host-port-map <one_master_host_port_map>¶: Publish a container port of one master node to the host. Only Transmission Control Protocol is supported currently. The syntax is <HOST_PORT>:<CONTAINER_PORT>

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

Arguments

INSTALLER¶: Required argument

Environment variables

MINIDCOS_NODE_DOCKER_VERSION: Provide a default for --docker-version

DCOS_LICENSE_KEY_PATH: Provide a default for --license-key

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

create-loopback-sidecar ¶

Create a loopback sidecar.

A loopback sidecar provides a loopback device that points to a (unformatted) block device.

minidcos docker create-loopback-sidecar [OPTIONS] NAME

Options

--size <size>¶: Size (in Megabytes) of the block device.

Arguments

NAME¶: Required argument

destroy ¶

Destroy a cluster.

minidcos docker destroy [OPTIONS]

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

destroy-list ¶

Destroy clusters.

To destroy all clusters, run minidcos docker destroy $(minidcos docker list).

minidcos docker destroy-list [OPTIONS] [CLUSTER_IDS]...

Options

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

Arguments

CLUSTER_IDS¶: Optional argument(s)

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

destroy-loopback-sidecar ¶

Destroy a loopback sidecar.

minidcos docker destroy-loopback-sidecar [OPTIONS] NAME

Options

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

Arguments

NAME¶: Required argument

destroy-mac-network ¶

Destroy containers created by “minidcos docker setup-mac-network”.

minidcos docker destroy-mac-network [OPTIONS]

Options

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

doctor ¶

Diagnose common issues which stop this CLI from working correctly.

minidcos docker doctor [OPTIONS]

Options

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

download-installer ¶

Download a DC/OS Open Source installer.

For DC/OS Enterprise installers, contact your sales representative.

minidcos docker download-installer [OPTIONS]

Options

--dcos-version <dcos_version>¶: The DC/OS Open Source installer version to download. This can be in one of the following formats: stable, testing/master, testing/<DC/OS MAJOR RELEASE>, stable/<DC/OS MINOR RELEASE>, testing/pull/<GITHUB-PR-NUMBER>. See https://dcos.io/releases/ for available releases. If an HTTP or HTTPS URL is given, that is downloaded. [default: stable]

--download-path <download_path>¶: The path to download an installer to. [default: ./dcos_generate_config.sh]

inspect ¶

Show cluster details.

minidcos docker inspect [OPTIONS]

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

install ¶

Install DC/OS on the given Docker cluster.

minidcos docker install [OPTIONS] INSTALLER

Options

--genconf-dir <files_to_copy_to_genconf_dir>¶: Path to a directory that contains additional files for the DC/OS installer. All files from this directory will be copied to the “genconf” directory before running the DC/OS installer.

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

--extra-config <extra_config>¶: The path to a file including DC/OS configuration YAML. The contents of this file will be added to add to a default configuration.

--security-mode <security_mode>¶

The security mode to use for a DC/OS Enterprise cluster. This overrides any security mode set in --extra-config.

Options: disabled|permissive|strict

--license-key <license_key>¶: This is ignored if using open source DC/OS. If using DC/OS Enterprise, this defaults to the value of the DCOS_LICENSE_KEY_PATH environment variable.

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

--variant <variant>¶

Choose the DC/OS variant. If the variant does not match the variant of the given installer, an error will occur. Using “auto” finds the variant from the installer. Finding the variant from the installer takes some time and so using another option is a performance optimization.

Options: auto|oss|enterprise

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

--wait-for-dcos¶: Wait for DC/OS after creating the cluster. This is equivalent to using “minidcos docker wait” after this command. “minidcos docker wait” has various options available and so may be more appropriate for your use case. If the chosen transport is “docker-exec”, this will skip HTTP checks and so the cluster may not be fully ready.

--workspace-dir <workspace_dir>¶: Creating a cluster can use approximately 2 GB of temporary storage. Set this option to use a custom “workspace” for this temporary storage. See https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir for details on the temporary directory location if this option is not set.

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

Arguments

INSTALLER¶: Required argument

Environment variables

DCOS_LICENSE_KEY_PATH: Provide a default for --license-key

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

list ¶

List all clusters.

minidcos docker list [OPTIONS]

list-loopback-sidecars ¶

List loopback sidecars.

minidcos docker list-loopback-sidecars [OPTIONS]

provision ¶

Provision Docker containers to install a DC/OS cluster.

minidcos docker provision [OPTIONS]

Options

--docker-version <docker_version>¶

The Docker version to install on the nodes. This can be provided by setting the MINIDCOS_NODE_DOCKER_VERSION environment variable. [default: 18.06.3-ce]

Options: 1.11.2|1.13.1|17.12.1-ce|18.06.3-ce

--linux-distribution <linux_distribution>¶

The Linux distribution to use on the nodes. [default: centos-7]

Options: centos-7|centos-8|coreos|flatcar|ubuntu-16.04

--docker-storage-driver <docker_storage_driver>¶

The storage driver to use for Docker in Docker. By default this uses the host’s driver. [default: auto]

Options: aufs|auto|overlay|overlay2

--mount-sys-fs-cgroup, --no-mount-sys-fs-cgroup¶: Mounting /sys/fs/cgroup from the host is required to run applications which require cgroup isolation. Choose to not mount /sys/fs/cgroup if it is not available on the host. [default: True]

--masters <masters>¶: The number of master nodes. [default: 1]

--agents <agents>¶: The number of agent nodes. [default: 1]

--public-agents <public_agents>¶: The number of public agent nodes. [default: 1]

-c, --cluster-id <cluster_id>¶: A unique identifier for the cluster. Use the value “default” to use this cluster for other commands without specifying –cluster-id.

--custom-volume <custom_volume>¶: Bind mount a volume on all cluster node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--custom-master-volume <custom_master_volume>¶: Bind mount a volume on all cluster master node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--custom-agent-volume <custom_agent_volume>¶: Bind mount a volume on all cluster agent node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--custom-public-agent-volume <custom_public_agent_volume>¶: Bind mount a volume on all cluster public agent node containers. See https://docs.docker.com/engine/reference/run/#volume-shared-filesystems for the syntax to use.

--workspace-dir <workspace_dir>¶: Creating a cluster can use approximately 2 GB of temporary storage. Set this option to use a custom “workspace” for this temporary storage. See https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir for details on the temporary directory location if this option is not set.

--network <network>¶: The Docker network containers will be connected to.It may not be possible to SSH to containers on a custom network on macOS.

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

--one-master-host-port-map <one_master_host_port_map>¶: Publish a container port of one master node to the host. Only Transmission Control Protocol is supported currently. The syntax is <HOST_PORT>:<CONTAINER_PORT>

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

Environment variables

MINIDCOS_NODE_DOCKER_VERSION: Provide a default for --docker-version

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

run ¶

Run an arbitrary command on a node or multiple nodes.

To use special characters such as single quotes in your command, wrap the whole command in double quotes.

minidcos docker run [OPTIONS] NODE_ARGS...

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

--dcos-login-uname <dcos_login_uname>¶: The username to set the DCOS_LOGIN_UNAME environment variable to. [default: bootstrapuser]

--dcos-login-pw <dcos_login_pw>¶: The password to set the DCOS_LOGIN_PW environment variable to. [default: deleteme]

--sync-dir <sync_dir>¶: The path to a DC/OS checkout. Part of this checkout will be synced to all master nodes before the command is run. The bootstrap directory is synced if the checkout directory variant matches the cluster variant.Integration tests are also synced.Use this option multiple times on a DC/OS Enterprise cluster to sync both DC/OS Enterprise and DC/OS Open Source tests.

-te, --test-env¶: With this flag set, environment variables are set and the command is run in the integration test directory. This means that “pytest” will run the integration tests.

--node <node>¶: A reference to a particular node to run the command on. This can be one of: The node’s IP address, the node’s Docker container name, the node’s Docker container ID, a reference in the format “<role>_<number>”. These details be seen with minidcos docker inspect. [default: master_0]

--env <env>¶: Set environment variables in the format “<KEY>=<VALUE>”

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

Arguments

NODE_ARGS¶: Required argument(s)

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

send-file ¶

Send a file to a node or multiple nodes.

minidcos docker send-file [OPTIONS] SOURCE DESTINATION

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

--node <node>¶: A reference to a particular node to run the command on. This can be one of: The node’s IP address, the node’s Docker container name, the node’s Docker container ID, a reference in the format “<role>_<number>”. These details be seen with minidcos docker inspect. [default: master_0]

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

Arguments

SOURCE¶: Required argument

DESTINATION¶: Required argument

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

setup-mac-network ¶

Set up a network to connect to nodes on macOS.

This creates an OpenVPN configuration file and describes how to use it.

minidcos docker setup-mac-network [OPTIONS]

Options

--configuration-dst <configuration_dst>¶: The location to create an OpenVPN configuration file. [default: ~/Documents/docker-for-mac.ovpn]

--force¶: Overwrite any files and destroy conflicting containers from previous uses of this command.

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

sync ¶

Sync files from a DC/OS checkout to master nodes.

This syncs integration test files and bootstrap files.

DCOS_CHECKOUT_DIR should be set to the path of clone of an open source DC/OS or DC/OS Enterprise repository.

By default the DCOS_CHECKOUT_DIR argument is set to the value of the DCOS_CHECKOUT_DIR environment variable.

If no DCOS_CHECKOUT_DIR is given, the current working directory is used.

This makes an assumption that all DC/OS Enterprise and DC/OS OSS integration tests are in the top level packages/dcos-integration-test directory.

minidcos docker sync [OPTIONS] [DCOS_CHECKOUT_DIR]

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

Arguments

DCOS_CHECKOUT_DIR¶: Optional argument

Environment variables

DCOS_CHECKOUT_DIR: Provide a default for DCOS_CHECKOUT_DIR

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

upgrade ¶

Upgrade a cluster to a given version of DC/OS.

minidcos docker upgrade [OPTIONS] INSTALLER

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

--extra-config <extra_config>¶: The path to a file including DC/OS configuration YAML. The contents of this file will be added to add to a default configuration.

--variant <variant>¶

Choose the DC/OS variant. If the variant does not match the variant of the given installer, an error will occur. Using “auto” finds the variant from the installer. Finding the variant from the installer takes some time and so using another option is a performance optimization.

Options: auto|oss|enterprise

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

--workspace-dir <workspace_dir>¶: Creating a cluster can use approximately 2 GB of temporary storage. Set this option to use a custom “workspace” for this temporary storage. See https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir for details on the temporary directory location if this option is not set.

--security-mode <security_mode>¶

The security mode to use for a DC/OS Enterprise cluster. This overrides any security mode set in --extra-config.

Options: disabled|permissive|strict

--wait-for-dcos¶: Wait for DC/OS after creating the cluster. This is equivalent to using “minidcos docker wait” after this command. “minidcos docker wait” has various options available and so may be more appropriate for your use case. If the chosen transport is “docker-exec”, this will skip HTTP checks and so the cluster may not be fully ready.

--license-key <license_key>¶: This is ignored if using open source DC/OS. If using DC/OS Enterprise, this defaults to the value of the DCOS_LICENSE_KEY_PATH environment variable.

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

--genconf-dir <files_to_copy_to_genconf_dir>¶: Path to a directory that contains additional files for the DC/OS installer. All files from this directory will be copied to the “genconf” directory before running the DC/OS installer.

Arguments

INSTALLER¶: Required argument

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

DCOS_LICENSE_KEY_PATH: Provide a default for --license-key

wait ¶

Wait for DC/OS to start.

minidcos docker wait [OPTIONS]

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

--superuser-username <superuser_username>¶: The superuser username is needed only on DC/OS Enterprise clusters. [default: bootstrapuser]

--superuser-password <superuser_password>¶: The superuser password is needed only on DC/OS Enterprise clusters. [default: deleteme]

--skip-http-checks¶: Do not wait for checks which require an HTTP connection to the cluster. If this flag is used, this command may return before DC/OS is fully ready. Use this flag in cases where an HTTP connection cannot be made to the cluster. For example this is useful on macOS without a VPN set up. [default: False]

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

--enable-spinner, --no-enable-spinner¶: Whether to show a spinner animation. This defaults to true if stdout is a TTY.

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport

web ¶

Open the browser at the web UI.

Note that the web UI may not be available at first. Consider using minidcos docker wait before running this command.

minidcos docker web [OPTIONS]

Options

-c, --cluster-id <cluster_id>¶: The ID of the cluster to use. [default: default]

-v, --verbose¶: Use verbose output. Use this option multiple times for more verbose output.

--transport <transport>¶

The communication transport to use. On macOS the SSH transport requires IP routing to be set up. See “minidcos docker setup-mac-network”. It also requires the “ssh” command to be available. This can be provided by setting the MINIDCOS_DOCKER_TRANSPORT environment variable. When using a TTY, different transports may use different line endings. [default: docker-exec]

Options: docker-exec|ssh

Environment variables

MINIDCOS_DOCKER_TRANSPORT: Provide a default for --transport