-
Notifications
You must be signed in to change notification settings - Fork 65
CLI guide
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.
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).
$ 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.
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
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.
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.
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.
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')
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
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.
You can find the full reference guide [here] (https://github.com/vmware/admiral/wiki/CLI-reference).