`dcos-vagrant` CLI¶

The dcos-vagrant 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, then create, manage and destroy a cluster:

# Fix issues shown by dcos-vagrant doctor
$ dcos-vagrant doctor
$ dcos-vagrant create /tmp/dcos_generate_config.sh --agents 0
default
$ dcos-vagrant wait
$ dcos-vagrant run --sync-dir /path/to/dcos/checkout pytest -k test_tls
...
$ dcos-vagrant destroy

Each of these and more are described in detail below.

Requirements ¶

Hardware ¶

A minimum of 2 GB of free memory is required per DC/OS node.

`ssh`¶

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

Vagrant ¶

Vagrant must be installed. This has been tested with:

Vagrant 2.1.1
Vagrant 2.1.2

VirtualBox ¶

VirtualBox must be installed. This has been tested with VirtualBox 5.1.18.

`dcos-vagrant doctor`¶

DC/OS E2E comes with the dcos-vagrant doctor command. Run this command to check your system for common causes of problems.

Installing the CLI ¶

The CLI can be installed with Homebrew on macOS or Linuxbrew on Linux. The library and CLI can be installed together with pip on any Linux and macOS.

CLI on macOS With Homebrew ¶

To install the CLI on macOS, install Homebrew.

Then install the latest stable version:

brew install https://raw.githubusercontent.com/dcos/dcos-e2e/master/dcose2e.rb

To upgrade from an older version, run the following command:

brew upgrade https://raw.githubusercontent.com/dcos/dcos-e2e/master/dcose2e.rb

Or the latest master:

Homebrew installs the dependencies for the latest released version and so installing master may not work.

brew install --HEAD https://raw.githubusercontent.com/dcos/dcos-e2e/master/dcose2e.rb

Run dcos-docker doctor to make sure that your system is ready to go for the dcos-docker CLI:

$ dcos-docker doctor

CLI on Linux With Linuxbrew ¶

One way to install the CLI on Linux is with Linuxbrew. Install Linuxbrew, then install the latest stable version:

brew install https://raw.githubusercontent.com/dcos/dcos-e2e/master/dcose2e.rb

To upgrade from an older version, run the following command:

brew upgrade https://raw.githubusercontent.com/dcos/dcos-e2e/master/dcose2e.rb

Or the latest master:

Homebrew installs the dependencies for the latest released version and so installing master may not work.

brew install --HEAD https://raw.githubusercontent.com/dcos/dcos-e2e/master/dcose2e.rb

Run dcos-docker doctor to make sure that your system is ready to go for the dcos-docker CLI:

$ dcos-docker doctor

Library and CLI with Python ¶

If the CLI has been installed with Homebrew, you do not need to install the library to use the CLI.

Requires Python 3.5.2+. To avoid interfering with your system’s Python, we recommend using a virtualenv.

Check the Python version:

python3 --version

On Fedora, install Python development requirements:

sudo dnf install -y git python3-devel

On Ubuntu, install Python development requirements:

apt install -y gcc python3-dev

Optionally replace master with a particular version of DC/OS E2E. The latest release is 2018.07.22.1. See available versions.

If you are not in a virtualenv, you may have to use sudo before the following command, or --user after install.

pip3 install --upgrade git+https://github.com/dcos/dcos-e2e.git@master

Run dcos-docker doctor to make sure that your system is ready to go for the Docker Backend and the dcos-docker CLI:

$ dcos-docker doctor

Run dcos-vagrant doctor to make sure that your system is ready to go for the Vagrant Backend and the dcos-vagrant CLI:

$ dcos-vagrant doctor

Creating a Cluster ¶

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

This can be done via the releases page or with the dcos-vagrant download-artifact command.

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

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

See the dcos-vagrant create reference for details on this command and its options.

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

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

DC/OS Enterprise ¶

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

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

Ask your sales representative for DC/OS Enterprise release artifacts.

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

$ dcos-vagrant 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 dcos-vagrant wait command.

See the dcos-vagrant create reference for details on this command and its options.

It can become tedious repeatedly typing the cluster ID, particularly if you only have one cluster. Any command which takes a cluster-id option defaults to using “default” if no cluster ID is given. This means that you can use dcos-vagrant wait with no arguments to wait for the default cluster.

Running commands on Cluster Nodes ¶

It is possible to run commands on a cluster node in multiple ways. These include using dcos-vagrant run and ssh.

Running commands on a cluster node using dcos-vagrant run ¶

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

$ dcos-vagrant run --cluster-id example systemctl list-units

See the dcos-vagrant run reference for more information on this command.

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 dcos-vagrant inspect.

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 dcos-vagrant run to run bash to get on to an arbitrary master node:

$ dcos-vagrant run --cluster-id example bash

Destroying Clusters ¶

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

Either destroy a cluster with dcos-vagrant destroy:

$ dcos-vagrant destroy
default
$ dcos-vagrant destroy --cluster-id pr_4033_strict
pr_4033_strict

or use dcos-vagrant destroy-list to destroy multiple clusters:

$ dcos-vagrant destroy-list pr_4033_strict pr_4019_permissive
pr_4033_strict
pr_4019_permissive

To destroy all clusters, run the following command:

$ dcos-vagrant destroy-list $(dcos-vagrant list)
pr_4033_strict
pr_4019_permissive

Running Integration Tests ¶

The dcos-vagrant 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:

$ dcos-vagrant create /tmp/dcos_generate_config.ee.sh
$ dcos-vagrant wait
$ dcos-vagrant run --sync-dir /path/to/dcos/checkout pytest -k test_tls.py

There are multiple options and shortcuts for using these commands. See the dcos-vagrant run reference for more information on this command.

Viewing the Web UI ¶

To view the web UI of your cluster, use the dcos-vagrant web command. If you instead want to view the web UI URL of your cluster, use the dcos-vagrant 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.

CLI Reference ¶

dcos-vagrant ¶

Manage DC/OS clusters on Vagrant.

dcos-vagrant [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

Commands

create: Create a DC/OS cluster.

destroy: Destroy a cluster.

destroy-list: Destroy clusters.

doctor: Diagnose common issues which stop DC/OS E2E…

download-artifact: Download a DC/OS Open Source artifact.

inspect: Show cluster details.

list: List all clusters.

run: Run an arbitrary command on a node.

sync: Sync files from a DC/OS checkout to master…

wait: Wait for DC/OS to start.

web: Open the browser at the web UI.

dcos-vagrant 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 admin. The default superuser password is admin. 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.

dcos-vagrant create [OPTIONS] ARTIFACT

Options

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

--agents <agents>¶: The number of 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.

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

--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 artifact, an error will occur. Using “auto” finds the variant from the artifact. Finding the variant from the artifact takes some time and so using another option is a performance optimization.

--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.

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

--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.

-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.

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

Arguments

ARTIFACT¶: Required argument

Environment variables

DCOS_LICENSE_KEY_PATH: Provide a default for --license-key

dcos-vagrant list ¶

List all clusters.

dcos-vagrant list [OPTIONS]

dcos-vagrant wait ¶

Wait for DC/OS to start.

dcos-vagrant 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. By default, on a DC/OS Enterprise cluster, admin is used.

--superuser-password <superuser_password>¶: The superuser password is needed only on DC/OS Enterprise clusters. By default, on a DC/OS Enterprise cluster, admin is used.

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

dcos-vagrant run ¶

Run an arbitrary command on a node.

This command sets up the environment so that pytest can be run.

For example, run dcos-vagrant run --cluster-id 1231599 pytest -k test_tls.py.

Or, with sync: dcos-vagrant run --sync-dir . --cluster-id 1231599 pytest -k test_tls.py.

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

dcos-vagrant 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.

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

--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.

--no-test-env¶: With this flag set, no environment variables are set and the command is run in the home directory.

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

Arguments

NODE_ARGS¶: Required argument(s)

dcos-vagrant inspect ¶

Show cluster details.

dcos-vagrant inspect [OPTIONS]

Options

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

dcos-vagrant 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.

dcos-vagrant sync [OPTIONS] [DCOS_CHECKOUT_DIR]

Options

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

Arguments

DCOS_CHECKOUT_DIR¶: Optional argument

Environment variables

DCOS_CHECKOUT_DIR: Provide a default for DCOS_CHECKOUT_DIR

dcos-vagrant destroy ¶

Destroy a cluster.

dcos-vagrant destroy [OPTIONS]

Options

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

dcos-vagrant destroy-list ¶

Destroy clusters.

To destroy all clusters, run dcos-vagrant destroy $(dcos-vagrant list).

dcos-vagrant destroy-list [OPTIONS] [CLUSTER_IDS]...

Arguments

CLUSTER_IDS¶: Optional argument(s)

dcos-vagrant doctor ¶

Diagnose common issues which stop DC/OS E2E from working correctly.

dcos-vagrant doctor [OPTIONS]

dcos-vagrant web ¶

Open the browser at the web UI.

Note that the web UI may not be available at first. Consider using dcos-vagrant wait before running this command.

dcos-vagrant web [OPTIONS]

Options

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

dcos-vagrant download-artifact ¶

Download a DC/OS Open Source artifact.

For DC/OS Enterprise release artifacts, contact your sales representative.

dcos-vagrant download-artifact [OPTIONS]

Options

--dcos-version <dcos_version>¶: The DC/OS Open Source artifact 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. [default: stable]

--download-path <download_path>¶: The path to download a release artifact to. [default: /tmp/dcos_generate_config.sh]

`dcos-vagrant` CLI¶

Requirements ¶

Hardware ¶

`ssh`¶

Vagrant ¶

VirtualBox ¶

`vagrant-vbguest`¶

`dcos-vagrant doctor`¶

Installing the CLI ¶

CLI on macOS With Homebrew ¶

CLI on Linux With Linuxbrew ¶

Library and CLI with Python ¶

Creating a Cluster ¶

DC/OS Enterprise ¶

“default” Cluster ID ¶

Running commands on Cluster Nodes ¶

Running commands on a cluster node using dcos-vagrant run ¶

Running commands on a cluster node using `ssh`¶

Getting on to a Cluster Node ¶

Destroying Clusters ¶

Running Integration Tests ¶

Viewing the Web UI ¶

CLI Reference ¶

dcos-vagrant ¶

dcos-vagrant create ¶

dcos-vagrant list ¶

dcos-vagrant wait ¶

dcos-vagrant run ¶

dcos-vagrant inspect ¶

dcos-vagrant sync ¶

dcos-vagrant destroy ¶

dcos-vagrant destroy-list ¶

dcos-vagrant doctor ¶

dcos-vagrant web ¶

dcos-vagrant download-artifact ¶

DC/OS E2E

Navigation

dcos-vagrant CLI¶

`dcos-vagrant` CLI¶