197 lines
6.2 KiB
ReStructuredText
197 lines
6.2 KiB
ReStructuredText
DC/OS Command Line Interface
|
|
===========================
|
|
The DC/OS Command Line Interface (CLI) is a cross-platform command line utility
|
|
that provides a user-friendly yet powerful way to manage DC/OS installations.
|
|
|
|
Installation and Usage
|
|
----------------------
|
|
|
|
If you're a **user** of DC/OS, please follow the `installation instructions`_.
|
|
Otherwise, follow the instructions below to set up your development environment.
|
|
|
|
Detailed help and usage information is available through the :code:`dcos help`
|
|
command and for specific subcommands through :code:`dcos <subcommand> --help`.
|
|
|
|
Additional documentation for the CLI and for the DC/OS in general is available
|
|
in the `Mesosphere docs`_.
|
|
|
|
Parsing CLI Output
|
|
------------------
|
|
|
|
The CLI outputs either whitespace delimited tables which can be processed by
|
|
all of your favourite Unix/Linux tools like sed, awk and grep, or text formatted
|
|
as JSON when using the :code:`--json` flag.
|
|
|
|
If using JSON, you can combine it with the powerful jq_ utility.
|
|
The example below installs every package available in the DC/OS repository::
|
|
|
|
dcos package search --json | jq '.[0].packages[].name' | xargs -L 1 dcos package install --yes
|
|
|
|
Using the CLI without DC/OS
|
|
--------------------------
|
|
|
|
You may optionally configure the DC/OS CLI to work with open source Mesos and
|
|
Marathon_ by setting the following properties::
|
|
|
|
dcos config set core.mesos_master_url http://<mesos-master-host>:5050
|
|
dcos config set marathon.url http://<marathon-host>:8080
|
|
|
|
Note that the DC/OS CLI has tight integration with DC/OS and certain
|
|
functionality may not work as expected or at all when using it directly with
|
|
Mesos and Marathon.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
#. git_ must be installed and on the system path in order to fetch
|
|
packages from :code:`git` sources.
|
|
|
|
#. virtualenv_ must be installed and on the system path in order to install
|
|
subcommands.
|
|
|
|
#. win_bash_ must be installed if you are running this in Windows
|
|
in order to run setup scripts from the Makefiles.
|
|
|
|
Setup
|
|
-----
|
|
|
|
#. Make sure you meet requirements for installing packages_
|
|
#. Clone git repo for the dcos cli::
|
|
|
|
git clone git@github.com:dcos/dcos-cli.git
|
|
|
|
#. Change directory to the repo directory::
|
|
|
|
cd dcos-cli
|
|
|
|
#. Make sure that you have virtualenv installed. If not type::
|
|
|
|
sudo pip install virtualenv
|
|
|
|
#. Create a virtualenv and packages for the dcos project::
|
|
|
|
make env
|
|
make packages
|
|
|
|
#. Create a virtualenv for the dcoscli project::
|
|
|
|
cd cli
|
|
make env
|
|
|
|
Configure Environment and Run
|
|
-----------------------------
|
|
|
|
#. :code:`source` the setup file to add the :code:`dcos` command line
|
|
interface to your :code:`PATH` and create an empty configuration file::
|
|
|
|
source bin/env-setup-dev
|
|
|
|
#. Configure the CLI, changing the values below as appropriate for your local
|
|
installation of DC/OS::
|
|
|
|
dcos config set core.dcos_url http://dcos-ea-1234.us-west-2.elb.amazonaws.com
|
|
|
|
#. Get started by calling the DC/OS CLI help::
|
|
|
|
dcos help
|
|
|
|
Running Tests
|
|
--------------
|
|
|
|
Setup
|
|
#####
|
|
|
|
Tox, our test runner, tests against Python 3.4. We have a set of tests in
|
|
the :code:`dcos` package (root directory) and in the :code:`dcoscli` package
|
|
(:code:`cli` directory). When running the tests describe below change
|
|
directory to one of those two and follow the instructions.
|
|
|
|
|
|
Initialization
|
|
#######
|
|
|
|
The `config` integration tests use static config files. To run these tests
|
|
make sure you set owner only permissions on these files:
|
|
|
|
:code:`chmod 600 cli/tests/data/dcos.toml`
|
|
|
|
:code:`chmod 600 cli/tests/config/parse_error.toml`
|
|
|
|
The :code:`node` integration tests use :code:`CLI_TEST_SSH_KEY_PATH` for ssh
|
|
credentials to your cluster.
|
|
|
|
The :code:`ssl` integration tests resolve :code:`dcos.snakeoil.mesosphere.com`
|
|
to test SSL certs. To run this test suite be sure to add this resolution to your
|
|
:code:`/etc/hosts` file:
|
|
|
|
:code:`echo "dcos/cluster/url dcos.snakeoil.mesosphere.com" >> /etc/hosts`
|
|
|
|
|
|
Running
|
|
#######
|
|
|
|
Tox will run unit and integration tests in Python 3.4 using a temporarily
|
|
created virtualenv.
|
|
|
|
You can set :code:`DCOS_CONFIG` to a config file that points to a DC/OS
|
|
cluster you want to use for integration tests. This defaults to
|
|
:code:`~/.dcos/dcos.toml`
|
|
|
|
There are two ways to run tests, you can either use the virtualenv created by
|
|
:code:`make env` above::
|
|
|
|
make test
|
|
|
|
Or, assuming you have tox installed (via :code:`sudo pip install tox`)::
|
|
|
|
tox
|
|
|
|
Other Useful Commands
|
|
#####################
|
|
|
|
#. List all of the supported test environments::
|
|
|
|
tox --listenvs
|
|
|
|
#. Run a specific set of tests::
|
|
|
|
tox -e <testenv>
|
|
|
|
#. Run a specific integration test module::
|
|
|
|
tox -e py34-integration /test_config.py
|
|
|
|
|
|
Releasing
|
|
#########
|
|
|
|
Releasing a new version of the DC/OS CLI is only possible through an `automated TeamCity build`_ which is triggered automatically when a new tag is added.
|
|
|
|
The tag is used as the version number and must adhere to the conventional `PEP-440 version scheme`_.
|
|
|
|
Once all tests pass successfully, the automated build publishes two packages to PyPI using the `publish_to_pypi.sh script`_:
|
|
|
|
#. dcos_
|
|
|
|
#. dcoscli_
|
|
|
|
These packages are now available to be installed by the DC/OS CLI installation script in the `mesosphere/install-scripts`_ repository.
|
|
|
|
|
|
.. _automated TeamCity build: https://teamcity.mesosphere.io/viewType.html?buildTypeId=ClosedSource_DcosCli_PushToPyPI
|
|
.. _dcos: https://pypi.python.org/pypi/dcos
|
|
.. _dcoscli: https://pypi.python.org/pypi/dcoscli
|
|
.. _dcos-helloworld: https://github.com/mesosphere/dcos-helloworld
|
|
.. _jq: http://stedolan.github.io/jq/
|
|
.. _git: http://git-scm.com
|
|
.. _installation instructions: https://dcos.io/docs/usage/cli/install/
|
|
.. _Marathon: https://mesosphere.github.io/marathon/
|
|
.. _Mesosphere docs: https://docs.mesosphere.com
|
|
.. _mesosphere/install-scripts: https://github.com/mesosphere/install-scripts
|
|
.. _packages: https://packaging.python.org/en/latest/installing.html#installing-requirements
|
|
.. _PEP-440 version scheme: https://www.python.org/dev/peps/pep-0440/
|
|
.. _publish_to_pypi.sh script: https://github.com/mesosphere/dcos-cli/blob/master/bin/publish_to_pypi.sh
|
|
.. _setup: https://github.com/mesosphere/dcos-helloworld#setup
|
|
.. _virtualenv: https://virtualenv.pypa.io/en/latest/
|
|
.. _win_bash: https://sourceforge.net/projects/win-bash/files/shell-complete/latest
|