Vagrant¶
The minidcos vagrant CLI allows you to create, manage and destroy open source DC/OS and DC/OS Enterprise clusters on Vagrant VMs.
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 vagrant doctor
minidcos vagrant doctor
minidcos vagrant create ./dcos_generate_config.sh --agents 0
default
minidcos vagrant wait
minidcos vagrant run --test-env --sync-dir /path/to/dcos/checkout pytest -k test_tls
...
Get onto a node
minidcos vagrant run bash
[master-0]# exit
minidcos vagrant destroy
Each of these and more are described in detail below.
Requirements¶
Vagrant by HashiCorp¶
Vagrant must be installed. This has been tested with:
Vagrant 2.1.1
Vagrant 2.1.2
Oracle VirtualBox¶
VirtualBox must be installed. This has been tested with VirtualBox 5.1.18.
vagrant-vbguest
plugin¶
vagrant-vbguest must be installed.
doctor
command¶
minidcos vagrant 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.
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 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 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 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 vagrant run systemctl list-units
See run 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 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 run to run bash
to get on to an arbitrary master node:
minidcos vagrant run bash
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 vagrant destroy
default
minidcos vagrant destroy --cluster-id pr_4033_strict
pr_4033_strict
or use destroy-list to destroy multiple clusters:
minidcos vagrant destroy-list pr_4033_strict pr_4019_permissive
pr_4033_strict
pr_4019_permissive
To destroy all clusters, run the following command:
minidcos vagrant destroy-list $(dcos-vagrant 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 vagrant create ./dcos_generate_config.sh
minidcos vagrant wait
minidcos vagrant 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.
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
, anddcos-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 vagrant 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.
CLI Reference¶
minidcos vagrant¶
Manage DC/OS clusters on Vagrant.
minidcos vagrant [OPTIONS] COMMAND [ARGS]...
clean¶
Remove VMs created by this tool.
This is useful in removing paused and aborted VMs. VMs are aborted when the host is shut down.
minidcos vagrant clean [OPTIONS]
Options
-
--destroy-running-clusters
¶
Destroy running clusters. [default: False]
-
--enable-spinner
,
--no-enable-spinner
¶
Whether to show a spinner animation. This defaults to true if stdout is a TTY.
-
-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 isdeleteme
. The defaultfault_domain_enabled
isfalse
.
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 theDCOS_LICENSE_KEY_PATH
environment variable.If none of these are set,
license_key_contents
is not given.
minidcos vagrant create [OPTIONS] INSTALLER
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 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
-
--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.
-
--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
-
--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.
-
--vm-memory-mb
<vm_memory_mb>
¶ The amount of memory to give each VM. [default: 2048]
-
--enable-selinux-enforcing
¶
With this flag set, SELinux is set to enforcing before DC/OS is installed on the cluster.
-
--enable-spinner
,
--no-enable-spinner
¶
Whether to show a spinner animation. This defaults to true if stdout is a TTY.
-
--vagrant-box-url
<vagrant_box_url>
¶ The URL of the Vagrant box to use. [default: https://downloads.dcos.io/dcos-vagrant/metadata.json]
-
--vagrant-box-version
<vagrant_box_version>
¶ The version of the Vagrant box to use. See https://www.vagrantup.com/docs/boxes/versioning.html#version-constraints for details. [default: ~> 0.10]
-
--wait-for-dcos
¶
Wait for DC/OS after creating the cluster. This is equivalent to using “minidcos vagrant wait” after this command.
Arguments
-
INSTALLER
¶
Required argument
Environment variables
-
DCOS_LICENSE_KEY_PATH
Provide a default for
--license-key
destroy¶
Destroy a cluster.
minidcos vagrant destroy [OPTIONS]
Options
-
--enable-spinner
,
--no-enable-spinner
¶
Whether to show a spinner animation. This defaults to true if stdout is a TTY.
-
-c
,
--cluster-id
<cluster_id>
¶ The ID of the cluster to use. [default: default]
destroy-list¶
Destroy clusters.
To destroy all clusters, run
minidcos vagrant destroy $(minidcos vagrant list)
.
minidcos vagrant destroy-list [OPTIONS] [CLUSTER_IDS]...
Options
-
--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)
doctor¶
Diagnose common issues which stop this CLI from working correctly.
minidcos vagrant 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 vagrant 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 vagrant 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.
install¶
Install DC/OS on a provisioned Vagrant cluster.
minidcos vagrant install [OPTIONS] INSTALLER
Options
-
--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.
-
--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
-
--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.
-
--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.
-
-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.
-
--wait-for-dcos
¶
Wait for DC/OS after creating the cluster. This is equivalent to using “minidcos vagrant wait” after this command.
Arguments
-
INSTALLER
¶
Required argument
Environment variables
-
DCOS_LICENSE_KEY_PATH
Provide a default for
--license-key
provision¶
Provision a Vagrant cluster for installing DC/OS.
minidcos vagrant provision [OPTIONS]
Options
-
--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]
-
--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.
-
-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.
-
--enable-selinux-enforcing
¶
With this flag set, SELinux is set to enforcing before DC/OS is installed on the cluster.
-
--enable-spinner
,
--no-enable-spinner
¶
Whether to show a spinner animation. This defaults to true if stdout is a TTY.
-
--vagrant-box-url
<vagrant_box_url>
¶ The URL of the Vagrant box to use. [default: https://downloads.dcos.io/dcos-vagrant/metadata.json]
-
--vagrant-box-version
<vagrant_box_version>
¶ The version of the Vagrant box to use. See https://www.vagrantup.com/docs/boxes/versioning.html#version-constraints for details. [default: ~> 0.10]
-
--vm-memory-mb
<vm_memory_mb>
¶ The amount of memory to give each VM. [default: 2048]
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 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. [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.
-
--env
<env>
¶ Set environment variables in the format “<KEY>=<VALUE>”
-
--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 VM name, a reference in the format “<role>_<number>”. These details be seen with
minidcos vagrant inspect
. [default: master_0]
-
-v
,
--verbose
¶
Use verbose output. Use this option multiple times for more verbose output.
Arguments
-
NODE_ARGS
¶
Required argument(s)
send-file¶
Send a file to a node or multiple nodes.
minidcos vagrant send-file [OPTIONS] SOURCE DESTINATION
Options
-
-c
,
--cluster-id
<cluster_id>
¶ The ID of the cluster to use. [default: default]
-
--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 VM name, a reference in the format “<role>_<number>”. These details be seen with
minidcos vagrant 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
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 vagrant sync [OPTIONS] [DCOS_CHECKOUT_DIR]
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.
Arguments
-
DCOS_CHECKOUT_DIR
¶
Optional argument
Environment variables
-
DCOS_CHECKOUT_DIR
Provide a default for
DCOS_CHECKOUT_DIR
upgrade¶
Upgrade a cluster to a given version of DC/OS.
minidcos vagrant 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
-
--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 vagrant wait” after this command.
-
--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
-
DCOS_LICENSE_KEY_PATH
Provide a default for
--license-key
wait¶
Wait for DC/OS to start.
minidcos 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. [default: bootstrapuser]
-
--superuser-password
<superuser_password>
¶ The superuser password is needed only on DC/OS Enterprise clusters. [default: deleteme]
-
-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.
web¶
Open the browser at the web UI.
Note that the web UI may not be available at first.
Consider using minidcos vagrant wait
before running this command.
minidcos vagrant 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.