Skip to content
This repository has been archived by the owner on Aug 26, 2021. It is now read-only.

CLI guide

Jump to bottom
Lazarin Lazarov edited this page Sep 17, 2018 · 10 revisions

WARNING: Admiral CLI is deprecated and no longer actively maintained by VMware.

Overview

The Admiral CLI is tool used to manage your Admiral from the console or to create scripts which will automate some processes. This guide describes what prerequisites you need in order to build it, how to build it and how to use it.

Prerequisites

The Admiral CLI is built on Go using Cobra library. The version of Go used while creating the CLI is 1.7.1

  • Go 1.7.1
  • Git

For Windows you will need some Terminal emulator that support usage of Makefiles (e.g Cygwin).

Building

$ cd ${path_to_admiral_project}/cli/src/

You can build it for specific OS or for all currently supported(Linux, Windows, OS X).

$ make #This will build binaries for all platforms both 32 and 64 bit versions.
$ make linux #This will build binaries for Linux both 32 and 64 bit versions.
$ make windows #This will build binaries for Windows both 32 and 64 bit versions.
$ make darwin #This will build binaries for OS X both 32 and 64 bit versions.

When the building is done, new directory with name bin will be created next to the src directory containing the binaries.

$ ls cli
$ bin/  cli.png  README.md  src/
$ ls cli/bin
$ darwin-amd64/  darwin-i386/  linux-amd64/  linux-i386/  windows-amd64/  windows-i386/

The binaries are inside the bin folder.

Note: When you build the CLI binaries, the binary for your native OS/Architecture will not be placed in separate directory, but inside the bin folder. Example: You are using Linux amd64 machine to build the CLI. Once you run make command and then go to bin directory, if you list the containing items you will see this:

$ ls
$ admiral  darwin-amd64/  darwin-i386/  linux-i386/  windows-amd64/  windows-i386/

There are a binary and 5 directories containing binaries for the different OS/Architectures, the single binary within bin directory is the one for Linux amd64.

Running integration tests

You need clean Admiral running, without anything added except the defaults. You also need to setup the configuration file holding the needed properties. You can find this file inside ${path_to_admiral_project}/cli/src/admiral/testdata/test.config

  • "admiralAddress" is the address where your test Admiral is running.
  • "username" is used as username to login.
  • "password" is used as password to login.
  • "publicKey" is the path to the public key of the docker host used to create credentials.
  • "privateKey" is the path to the private key of the docker host used to create credentials.
  • "hostAddress" is the address of the docker host.
  • "placementZone" is the ID of the placement zone used for testing.

Once this is ready, move to ${path_to_admiral_project}/cli/src/ and use make test to run the tests.

$ cd ${path_to_admiral_project}/cli/src/
$ make test

Usage

Once you have built the tool, and have the binary for your platform, we recommend you to move it to place which is inside your $PATH or to include in $PATH the directory of the binary, then you can simply call it from everywhere.

$ admiral --version

When you use Admiral CLI for first time, it will create a configuration file inside ~/admiral-cli directory. There will be stored also file containing the authorization token.

Autocompletion

The Admiral CLI supports bash autocompletion thanks to Cobra library. You can generate the needed script with the following command:

$ admiral autocomplete

The file will be placed again inside ~/admiral-cli. In order to use it, you can move it to /etc/bash_completion.d/ then you should logout-login.

Note: The generated script supports autocompletion for the current version of the CLI, that means if there are any new commands/features, you should generate this script again. You can also use another method to activate the script.

Configuration and Authorization

The configuration file is in JSON format. In order to use the CLI you should configure the address where is running the Admiral. There are some ways to do it. From the CLI, the following command will set in the configuration file the property with name "url" the value "http://127.0.0.1:8282", of course you can set another address where actually is running your Admiral.

$ admiral config set -k url -v http://127.0.0.1:8282

You can set the address when you login.

$ admiral login --url http://127.0.0.1:8282

The login is happening with the following command:

$ admiral login

You can pass the username and password as parameters.

$ admiral login --user Username --pass Password

In case you didn't pass them as parameters, you will be prompted to enter the missing field. By default, if you have set the property "user" in the configuration file, it will automatically take it and will not prompt you for username. If the login is successful the authorization token will be stored in the directory ~/admiral-cli. You can get more information about the currently used token.

$ admiral login --status

The CLI can use authorization token from the file, from environment variable ADMIRAL_TOKEN and also for each command you use, you can pass specific token with the parameter "--token". The priority is Parameter > Environment variable > File. Once you have setup the authorization and configuration you can start manage your Admiral with the CLI.

How to use Admiral CLI without storing the token on your file system?

If you think that storing the token in a file as plain text is not secure here is another approach. You can use the login command with --quiet flag, this way you will get your token printed, but not saved in the token file.

$ admiral login --quiet

Once you have the token, you can store it in environment variable named ADMIRAL_TOKEN, this way the CLI automatically will recognize it and use it. Another way is to store it in environment variable with some different name, then you can pass it to each command with --token flag. Example:

$ export ADMIRAL_TOKEN=$(admiral login --quiet --user ${ADMIRAL_USERNAME} --pass ${ADMIRAL_PASSWORD})

The example above will authenticate you and store the token in $ADMIRAL_TOKEN without printing it in the terminal.

$ export CUSTOM_TOKEN=$(admiral login --quiet --user ${ADMIRAL_USERNAME} --pass ${ADMIRAL_PASSWORD})
$ admiral ps --token $CUSTOM_TOKEN

The example above will store the token in variable named $CUSTOM_TOKEN, but you can name it whatever you want. Then it's shown how to pass this token to any command.

Note: If your username, password and url(admiral address) are not passed from variables to the login command, make sure that when you pass them they are surrounded with single quotes '', otherwise if they contain some special symbols, this might break the command evaluation. Example:

 $ export ADMIRAL_TOKEN=$(admiral login --quiet --user 'u$3rn@me' --pass 'p@$$w0rd')

Example

Most of the commands require additional parameters, which are actually other Admiral entities. The following simple use case will provide basic insight how to use the CLI. We assume that you already configured your CLI to work with your desired Admiral instance, if not, you can read how to do it in the previous sections.

The case: Create new placement zone, add docker host, set some basic placement and provision a container.

We create new placement zone with the following command:

$ admiral placement-zone add sample-pz
Placement zone added: 134e60d7b5c3447554427a0447e90

After the command is executed, new placement zone will be created with name "sample-pz", it will also return message containing it's ID. If you want to check the existing placement zones you can do it with:

$ admiral placement-zone ls

ID                                NAME                         MEMORY     CPU       TAGS
134e60d7b5c3447554427a0447e90     sample-pz                    0.00%      0.00%     n/a

134egg432h912y4732yh543h713h5     sample-pz2                   0.00%      0.00%     n/a

Now it's time to add the docker host to the newly created placement zone. As said earlier some commands require other Admiral entities as parameters. This is done when you pass the ID of the required entity. The current CLI implementation allows you to pass only prefix of the ID but this prefix should be unique and other entities of the same type should not contain the same prefix. In the example above you can see unique prefixes that are marked with bold. Another way of passing entities as parameters the CLI supports is by passing the name of it, as long as the name is unique. The following command will show how to add docker host and how to pass entity by it's ID or by it's name.

$ admiral host add --address ${host-address} --placement-zone 134e6 --public ${path/to/publicKey} --private ${path/to/privateKey}

$ admiral host add --address ${host-address} --placement-zone sample-pz --public ${path/to/publicKey} --private ${path/to/privateKey}

Both commands will do the same: Add new docker host to the placement zone we created earlier with name "sample-pz". "--public" and "--private" provide public and private keys if the host is secured, if not, you can omit these parameters. In our example beside adding the docker host, the command also created new credentials with the provided keys. You can list the credentials and host with:

$ admiral credentials ls
$ admiral host ls

It's time to create project and placement. We create project with the following command:

$ admiral project add sample-project
Project added: 134e60d7b5c3447554428138e3648

Then with this project and the placement zone we will create placement with some simple policies.

$ admiral placement add sample-placement --placement-zone 134e6 --project 134 --priority 1 --memory-limit 500mb --cpu-shares 2

$ admiral placement add sample-placement --placement-zone sample-pz --project sample-project --priority 1 --memory-limit 500mb --cpu-shares 2

Again, both commands do the same job but for the one we used IDs and for the other the names of the entities.

Placement added: 134e60d7b5c34475544282c7e2758

Now let's provision container using the project we created with name "sample-project".

$ admiral run vmware/admiral --project 134

$ admiral run vmware/admiral --project sample-project

Container(s) provisioned: admiral-mcm346-30715621738

Or you can list your running containers with:

$ admiral ps
ID                             NAME                           ADDRESS        STATUS                CREATED           [HOST:CONTAINER]     EXTERNAL ID
admiral-mcm346-30715621738     admiral-mcm346-30715621738     172.17.0.4     RUNNING 2 minutes     2 minutes ago     [33500:8282]         0522e780e1c6407

Using CLI for scripting

In case you want to use the CLI for scripting, and the current output does not satisfy you, because you will need only the IDs of the manipulated entities, you can use the global option --quiet, which will omit everything but the ID that is going to be returned from your current command. For the following example we will remove previously deployed container "admiral-mcm346-30715621738" and the project we created earlier - "sample-project".

$ admiral rm admiral-mcm346-30715621738 --force --quiet
admiral-mcm346-30715621738

$ admiral project rm sample-project --quiet
134e60d7b5c3447554428138e3648

Don't forget that every command have "--help" option which will display more information about it.

CLI reference

You can find the full reference guide [here] (https://github.com/vmware/admiral/wiki/CLI-reference).

Using Admiral

Contributing

Clone this wiki locally