Vamp-cli-ee NPM

Vamp CLI Enterprise Edition

Installation

Vamp CLI EE is a Node.js package. Install it globally and export the host address of your Vamp installation via VAMP_HOST.

npm install -g vamp-cli-ee
export VAMP_HOST=http://vamp-host
vamp --help

You will need to authenticate and provide the correct namespace to further use the CLI

Tokens & Namespaces

To use the CLI, you need have an API token and set the correct namespace.

API token: can be set by export VAMP_TOKEN=<token uuid> or as an CLI argument --token
Namespace: can be set by export VAMP_NAMESPACE=<namespace uuid> or as an CLI argument --namespace

Adding cookies

You might need to add a specific Cookie header to each API request generated by the Vamp CLI to access production networks. Similar to other authentication data, you can add this in three ways:

use the CLI argument --cookie <cookie>
set export VAMP_COOKIE=<cookie>
add a { cookie: "cookie" } value to the ~/.vamp file in your home directory

In each case, the <cookie> value is a simple string with this format "name=value".

Logging in

The best practice to log in to Vamp CLI is to execute vamp login command without any additional parameters. You will be prompted to enter your user name and password. The second option is to pass your credentials using -u and -p parameters (vamp login -u tim -p password). Please note that when using this method, your password will be visible in your bash history in plain text, so it's not a recommeneded way of logging in.

Logging in as a non admin

If you do not have the access rights to create a token, your Vamp admin should provide you with one. Also, you should be provided with the correct namespace UUID.

# Logging in will prompt you to request an API token from your admin
vamp login
User name: tim
Password: ***
You do not have enough rights to create an API token, please request a token from your Vamp admin. Then add the token
to your request using the "--token [token]" syntax or export as VAMP_TOKEN

# Once you have the token and namespace, you can proceed
export VAMP_TOKEN=3366ca4397f87f5de6bc9b5863f37efb46f4bc6f4d9626e
export VAMP_NAMESPACE=6d1339c7c7a1ac54246a57320bb1dd15176ce29

# You can now use the CLI
vamp list deployments
NAME   CLUSTERS                   PORTS                                                                STATUS
sava   sava, backend1, backend2   sava.webport:40000, backend1.webport:40002, backend2.webport:40001   Deployed

Credentials are evaluated in the following order: 1. passed in on CLI with --namespace etc 2. passed in via ENV vars 3. passed in via ~/.vamp file. This file is written when logging in as an admin

Logging in as an admin

Admins are a bit different from other users:

They can generate their own API access tokens
They can query the organisation namespace for users, roles, tokens, environments etc.

# Logging in when you are an admin sets the admin namespace as default
vamp login
User name: tim
Password: ***
Login successful

# You can now query the organisation namespace
vamp list users
NAME    ROLES
Bob     qa
Admin   admin
Tim     developer
Jason   developer

# Querying a specific environment artifacts requires setting the namespace. First get a list of the available namespaces
vamp list namespaces
NAME          UUID
test          6d1339c7c7a1ac54246a57320bb1dd15176ce29
prod          51b1a5465f4ea62adf537b4f72bb23dc096ce6ca

# Then set the namespace as cli parameters, or export it as an environment variable, `export VAMP_NAMESPACE=<uuid>`. Bot methods are equivalent.
export VAMP_NAMESPACE=6d1339c7c7a1ac54246a57320bb1dd15176ce29
vamp list deployments
NAME   CLUSTERS                   PORTS                                                                STATUS
sava   sava, backend1, backend2   sava.webport:40000, backend1.webport:40002, backend2.webport:40001   Deployed

Admin credentials are written to a .vamp file in the user's home directory.

Note for Windows users

On Windows, the '%' sign is reserved. The Vamp CLI uses this character when updating the weight on gateways. You need to surround the --weightscommand argument with double quotes"`, i.e.

vamp update-gateway myDeployment/myService/web --weights "route1@50%,route2@50%"

Examples

# deploy a blueprint from a stored blueprint
vamp deploy myService:1.0.0 myDeployment

# deploy a blueprint directly from a file and wait for the deploy to finish
vamp deploy -f blueprint.yml myDeployment --wait

# get the details of a deployment
vamp describe deployment myDeployment

# merge a blueprint to a running deployment
vamp merge myService:1.1.0 myDeployment

# get the details of a gateway
vamp describe gateway myDeployment/myService/web

# set a condition on specific route in a gateway
vamp update-gateway myDeployment/myService/web --route  myDeployment/myCluster/myService:1.1.0/web --condition "User-Agent == Safari" --strength 100%

# set the weight distribution on set of routes in a gateway
vamp update-gateway myDeployment/myService/web --weights myDeployment/myCluster/myService:1.0.0/web@50%,myDeployment/myCluster/myService:1.1.0/web@50%

# undeploy a complete deployment, waiting for the undeploy to finish
vamp undeploy myDeployment --wait

# undeploy a specific service of a deployment
vamp undeploy myDeployment --service myService:1.0.0

# list metrics, filtered with tags and paginated
vamp list events --tags metrics --per-page 10 --page 1
# list all the roles
vamp list roles

# using environment variable for token and namespace
export VAMP_TOKEN=14b8a1e541edc87839d288368f0f0b7639509594cd934d61
export VAMP_NAMESPACE=851ff948633b26de75ffea856b1bb10d414df47d
vamp list roles

# see details of a role
vamp describe role admin

# create a role
vamp create role -f createRole.json

# delete a role
vamp delete role myrole2

# list all users
vamp list users

# see details of an user
vamp describe user admin

# create a user
vamp create user -f createUser.json

# delete an user
vamp delete user abc

# list all tokens
vamp list tokens

# see details of a token
vamp describe token mytoken

# create a token
vamp create token -f createToken.json

# delete an user
vamp delete token mytoken

# login
vamp login

# show stored token
vamp credentials

Using the CLI programmatically

You can include the vamp-cli-ee package in your code. It will expose the api object which you can use to interact with Vamp in your Node.js code. Configure the host by either setting the VAMP_HOST environment variable or pass in a config object with a host entry

const vamp = require('vamp-cli-ee/src/api')({ host: 'http://localhost:8080', token: <token>, namespace: <namespace> })

vamp.breed.list()
  .then(res => console.info(res))

vamp.deployment.get('mydeployment')
.then(res => console.info(res))

Checkout the api.md file for jsDoc styled API docs