Public | Automated Build

Last pushed: 3 months ago
Short Description
Unofficial Azure Container Service Command Line Interface
Full Description

RETIRED

Almost all of the useful features of this CLI have now been incorporated into the new Azure CLI.

The exception to this is the automated configuration of demo content. This has been moved into http://github.com/Azure/acs-demos.

This project is no longer maintained.

Original README

This project provides a convenience CLI for creating, testing and
working with ACS clusters. It's a work in progress and we welcome
contributions via the project issue tracker.

Quickstart

  1. Install Docker.

  2. Start the CLI container

docker run -it -v ~/.ssh:/root/.ssh -v ~/.acs:/root/.acs rgardler/acs
  1. View the available commands
acs --help

Demo application

The CLI provides quick commands to deploy clusters and demo
applications in those clusters. To see the available demo's run:

acs demo --help

Do deploy a demo run:

acs demo microscaling

The above command will:

  • ask the user to interactively login to their Azure subscription
  • create an ACS cluster to the specifications defined by the user
  • customize the ACS instance to open an addiitonal public port
  • create a storage account for our application
  • deploy a multi-container demo application

To remove a demo from a cluster run (this does not remove the cluster,
only the demo application):

acs demo microscaling --remove

Ways to run the ACS CLI

Assuming you have Docker installed the application will run "out of the
box" with the following command:

docker run -it rgardler/acs

You may also choose to use the latest developer version (which is the default
branch in github). This versoin will likely have features and fixes that are
still being tested. Simply use the ':dev' tag:

docker run -it rgardler/acs:dev

Although not required, it is preferable to mount your ssh and acs
configuration files into the running container. This way you can use
the same files across multiple versions of the cli container. To do
this use the following mounts:

docker run -it -v ~/.ssh:/root/.ssh -v ~/.acs:/root/.acs rgardler/acs:dev

NOTE 1: the first time you run this you may need to create the ~/.ssh
and ~/.acs directories.

NOTE 2: we provide a
convenience script for doing this (and more, see below).

NOTE 3: If you want to work with the latest development version (may
have more features, but may also have more bugs) replace
rgardler/acs with rgardler/acs:dev in the above commands.

At this point you are ready to start using the CLI.

NOTE: the run-docker.sh script linked above will always attempt to
restart a previously run container. This has the advantage of
maintaining your Azure login credentials.

Usage

The CLI includes some basic help guidance:

acs --help

To get help for a specific command use acs COMMAND --help, for example:

acs service --help

For more information see the
documentation, sources for which
are located in the docs/source folder of our
GitHub project.

Create a Cluster

Since the first thing most users will want to do is create a cluster
we are documenting this command here. Please see acs --help for a
list of all available commands.

acs service create

Unless otherwise specified the cluster configuration is defined in
~/.acs/default.ini within the container. If you mapped a local
directory to this location then it will be persisted on your
client. If this file does not exists you will be asked to answer some
questions about your desired configuration and the file will be
created for you.

You can override the location of the configuration file with the
option --config-file=PATH_TO_FILE, if the file exists it will be
used, if not you will be asked the same questions and the file will be
created.

Connecting to your cluster

It is necessary to open an SSH tunnel to you cluster. By default the
acs cli will use the keys in ~/.ssh/id_rsa (this can be configured
in the ini file in ~/.acs/. If the identified keys don't exist
when you run the acs service create command they will be created for
you.

To easily create a tunnel to your cluster run:

acs service connect

Take a note of the pid file this command outputs as you may want to kill this tunnel at a later time with:

kill $PID

Working with DCOS

If your cluster is using DC/OS as the orchestrator and you created it
using this set of tools then the DC/OS CLI will have been installed
for you when you created the cluster. If, however, you deployed the
cluster using a different method you can install the DC/OS cli with
the following commands.

acs service install_dcos_cli
. /src/bin/env-setup

Once installed you can run DCOS command directly with dcos COMMAND
(you must first have connected to the cluster with acs service connect).

Development

Contributions (bug reports, feature requests, docs, patches etc.) are
welcome via the
project page.

The easiest way to get started is to develop using the Docker
container, however, the application is a Python3 application can can
be run anywhere you can find Python 3. First you need to clone the dev
branch of the code:

git clone https://github.com/rgardler/acs-cli/tree/dev acs-cli

Once you have the source code, you can build a development container
with:

./scripts/build-docker.sh

To run your container with local files mapped into it:

./scripts/dev-docker.sh

Now you can edit the files using your favorite editor and test the
application from within the container. Note that when you have made
changes to your source files you should run the following in your
container:

python setup.py install

Development without Docker

If you would prefer to work outside of a container then consult the
Dockerfile in the project root for details of how to set up your
development environment.

Testing

Run tests using py.test: and
coverage:

sudo pip install -e .[test]
python setup.py test

Note, by default this does not run the slow tests (like creating the
cluster and installing features). You must therefore first have run the
full suite of tests at least once. You can do this with:

py.test --runslow

You can also run selected tests. For example the following command runs only the (non-slow) tests in test/commands/test_service.py:

py.test test/commands/test_service.py

To run a subset of the tests in a file us -k to provide a pattern to
match, for example, to test creation of a service:

py.test test/commands/test_service.py -k test_create

Adding a new top level command

To add a top level command representing a new feature follow the
these steps (in this example the new command is called Foo:

  • Add the command foo and its description to the "Commands" section of the docstring for acs/cli.py
  • Copy acs/commands/command.tmpl to acs/commands/foo.py
    • Add the subcommands and options to the docstring of the foo.py file
    • Implement each command in a method using the same name as the command
  • Add foo.py import to acs/commands/__init__.py
  • Add instantiation of foo.py to tests/conftest.py
  • Copy tests/command/test_command.tmpl to test/command/test_foo.py
    • Implement the tests
  • Run the tests with python setup.py test and iterate as necessary
  • Install the package with python setup.py install
  • Add the command to the documentation in docs/*

Adding a new subcommand

Subcommands are applied to commands, to add a subcommand do the following:

  • Add the subcommand to the docstring of the relevant command class (e.g. foo.bar)
  • Add a method with the same name as the subcommand
  • Add a test
  • Run the tests with python setup.py test and iterate as necessary
  • Install the package with python setup.py install

Releasing

This section describes how to create a release of the acs-cli.

Verify the code is ready for release

Ensure all local edits have been pushed to the dev branch:

git status
[git add <as necessary>]
git push

Ensure we have all the latest changes in the dev branch:

git checkout dev
git pull origin master
git merge master

Build the container.

./scripts/build-docker.sh

Ensure all tests pass:

docker run -it acs
python setup.py test
exit

If all tests pass then merge dev into master:

git checkout master
git merge dev
git push

Create a tag in git:

git tag x.y.z
git push --tags

There is no need to manual build and push the new Docker container as
this will be done by Docker Hub.

Update the version numbers in acs/__init__.py:

__version__ - 'x.y.z'

Commit to dev in order to start the next development cycle:

git checkout dev
git add as/__init__.py
git push

Updating Documentation

To build and publish the documentsation you need Sphinx installed:

sudo pip install -U Sphinx

Then you can build and deploy the docs with:

cd docs
make gh-pages
cd ..
Docker Pull Command
Owner
rgardler
Source Repository