The following introduction will help you get up and running quickly with AMP.
We recommend installing the Docker CE stable channel release 17.09.1 on your system.
Make sure you check the What to know before you install
section on the Docker site for Mac OS and Windows to ensure your system meets the requirements.
NOTE: We currently do not support Docker Toolbox on any OS.
For the installers, go to Docker for Mac.
Configure Docker to use maximum CPU and at least half of the maximum memory. You can configure settings by right clicking the whale icon on the status bar and clicking Preferences
-> Advanced
.
Make sure you apply these changes for Docker to be configured with the new settings.
For the installers, go to Docker for Windows.
Configure Docker to use maximum CPU and at least half of the maximum memory. You can configure settings by right clicking the whale icon in the Notifications area and clicking Settings
-> Advanced
.
Make sure you apply these changes for Docker to be configured with the new settings.
You can find specific Linux distribution in the tables on Docker for Linux.
Download the latest release of the CLI for your platform from here.
Place the amp
binary from the release archive into some location in your system path.
For example:
$ sudo chmod +x ./amp
$ sudo mv ./amp /usr/local/bin
You can create an AMP cluster on your machine locally or on AWS.
This is the default mode for cluster creation on AMP.
During development of your application, you will want to have a quick and easy way of running and tearing down a cluster, rather than relying on a cloud based solution.
To enable Docker engine metrics, you must add some configuration to the Docker daemon.
Right click on the whale icon, go to Preferences
-> Daemon
and select the Advanced
tab, and add this:
{
"experimental" : true,
"metrics-addr" : "0.0.0.0:9323"
}
Make sure you apply these changes for Docker to be configured with the new settings.
To enable Docker engine metrics, you must add some configuration to the Docker daemon.
You can configure settings by right clicking the whale icon in the Notifications area and clicking Settings
-> Daemon
-> Advanced
tab.
{
"experimental" : true,
"metrics-addr" : "0.0.0.0:9323"
}
Make sure you apply these changes for Docker to be configured with the new settings.
To enable Docker engine metrics, you must add some configuration to the Docker daemon.
Edit or create the daemon.json
file in located etc/docker
to include:
$ sudo nano /etc/docker/daemon.json
{
"experimental" : true,
"metrics-addr" : "0.0.0.0:9323"
}
You must perform this additional step to increase virtual memory needed for Elasticsearch.
$ sudo sysctl -w vm.max_map_count=262144
To make this change permanent, you can run the following and reboot:
$ echo "vm.max_map_count = 262144" | sudo tee -a /etc/sysctl.conf
To create a cluster locally:
$ amp cluster create
...
2017/12/04 01:17:59 ampctl (version: 0.18.0-dev, build: a51daf88)
...
{"Swarm Status":"active","Core Services":17,"User Services":0}
This will create a single node swarm cluster on your machine and deploy AMP services on top of it.
Once you have started a local cluster, you will be able to deploy stacks and monitor the associated services by signing up.
$ amp user signup --name user1 --email user1@amp.com --password [password]
Verification is not necessary for this cluster.
Hi user1! You have been automatically logged in.
NOTE: See the user documentation in the AMP CLI Reference section for additional details about the user account related operations.
With the local cluster, you do not need to verify the account created and you will be logged in automatically after an account creation.
While deploying a local cluster, the default certificate is self-signed. You need to use the -k
or --insecure
option when using any of the AMP commands.
TIP: Set an alias for
amp
asalias amp='amp -k'
.
You can now deploy a stackfile on your newly created local cluster.
You can check if a cluster is running or not by running the following command:
$ amp cluster status
The output of this command displays the provider, swarm status, and the number of core and user services running.
Provider: local
Swarm Status: active
Core Services: 17
User Services: 0
NOTE: You must be logged in to the AMP cluster to run this command.
If you no longer use the deployed cluster, it can be removed by running the following command:
$ amp cluster rm
On success, the output looks something like this:
2017/12/08 21:49:40 ampctl (version: 0.18.0-dev, build: 4ad78fdd)
Removing service amp_agent
Removing service amp_alertmanager
Removing service amp_ampbeat
Removing service amp_amplifier
Removing service amp_cadvisor
Removing service amp_docker-engine
Removing service amp_elasticsearch
Removing service amp_etcd
Removing service amp_gateway
Removing service amp_grafana
Removing service amp_haproxy_exporter
Removing service amp_kibana
Removing service amp_nats
Removing service amp_nats_exporter
Removing service amp_nodes
Removing service amp_prometheus
Removing service amp_proxy
2017/12/08 21:49:40 waiting for all services to clear up...
2017/12/08 21:49:40 Removing container /amp_ampbeat.1.rwh3rnmwpf94rasrcah5hunk1 [Exited (1) 10 minutes ago]
2017/12/08 21:49:52 Removing container /amp_prometheus.1.bj1g2byp3te34sjov0rlz6gos [Exited (0) 9 seconds ago]
2017/12/08 21:49:52 Removing container /amp_nats_exporter.1.mv8lgp1c3jqm3ng009izh3oak [Exited (143) 9 seconds ago]
2017/12/08 21:49:55 Removing container /amp_agent.7z8aobvghzadvrb8n3zf22ake.pinz6oz4mk2m6y8h47455nrxk [Exited (137) 3 seconds ago]
2017/12/08 21:49:56 cleared up
2017/12/08 21:49:56 Removing volume [amp_etcd-data]...
2017/12/08 21:49:56 Removing volume [amp_ampagent]...
2017/12/08 21:49:56 Removing volume [amp_elasticsearch-data]...
2017/12/08 21:49:56 Removing volume [amp_prometheus-data]...
2017/12/08 21:49:56 Removing volume [amp_alertmanager-data]...
2017/12/08 21:49:56 Removing volume [amp_grafana-data]...
2017/12/08 21:49:56 Successfully removed network public [prn2d38x4q90vq3vqhejcb2h5]
2017/12/08 21:49:56 Successfully removed network monit [ik9ojg3hh5t2gdjv96s098cis]
2017/12/08 21:49:56 Successfully removed network core [zfc7cios4kmz4ogdknu5mrd2k]
2017/12/08 21:49:58 cluster deleted
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.
This page outlines the steps to set up an AMP cluster on AWS.
When you application is ready or when you want your team to share a common cluster, it is easy to spin up an AMP cluster on AWS.
The prerequisites for creating an AWS cluster on AMP is to have:
You will need an AWS account with adequate IAM rights to deploy Cloud Formation stacks.
If you don't already have one, sign up here.
To learn more about managing IAM roles, see the official documentation from AWS here.
You will need an AWS key pair specific to the region you choose.
For creating key pairs on AWS, see the official documentation from AWS here.
You will need to provide your AWS Access Key ID
and AWS Secret Access Key
in order to deploy an AMP cluster.
You can find out more about AWS access keys here.
NOTE: If you already have the AWS CLI installed on your system, make sure it is configured since the AMP CLI will use this information for cluster creation. See more details here.
Before deploying your cluster, you will need the following elements:
us-west-2
NOTE: If you already have the AWS CLI installed, the AMP CLI will use the
Region
,AWS Access Key ID
andAWS Secret Access Key
from it.
If you don't have the AWS CLI installed, enter the following:
$ export REGION=us-west-2
$ export KEY_NAME=user-keypair
$ export ACCESS_KEY_ID=xxxxx
$ export SECRET_ACCESS_KEY=xxxxx
$ export STACK_NAME=amp-test
$ amp cluster create --provider aws --aws-region $REGION --aws-parameter KeyName=$KEY_NAME --aws-access-key-id $ACCESS_KEY_ID --aws-secret-access-key $SECRET_ACCESS_KEY --aws-stackname $STACK_NAME --aws-sync
If you have the AWS CLI installed, enter the following:
$ export KEY_NAME=user-keypair
$ export STACK_NAME=amp-test
$ amp cluster create --provider aws --aws-parameter KeyName=$KEY_NAME --aws-stackname $STACK_NAME --aws-sync
The AMP cluster deployment on AWS takes roughly 10 minutes to complete. On success, the output looks something like this:
Fri Dec 8 01:16:53 UTC 2017 amp-test CREATE_IN_PROGRESS (User Initiated)
Fri Dec 8 01:17:16 UTC 2017 Vpc CREATE_COMPLETE
Fri Dec 8 01:19:34 UTC 2017 ManagerAutoScalingGroup CREATE_COMPLETE
Fri Dec 8 01:20:56 UTC 2017 ManagerWaitCondition CREATE_COMPLETE
Fri Dec 8 01:21:02 UTC 2017 CoreWorkerAutoScalingGroup CREATE_COMPLETE
Fri Dec 8 01:21:02 UTC 2017 UserWorkerAutoScalingGroup CREATE_COMPLETE
Fri Dec 8 01:21:58 UTC 2017 CoreWaitCondition CREATE_COMPLETE
Fri Dec 8 01:21:59 UTC 2017 UserWaitCondition CREATE_COMPLETE
Fri Dec 8 01:23:50 UTC 2017 ApplicationWaitCondition CREATE_COMPLETE
Fri Dec 8 01:23:54 UTC 2017 amp-test CREATE_COMPLETE
-------------------------------------------------------------------------------
VPC ID | vpc-a92ec8d0
NFSv4 Endpoint | disabled
URL for cluster health dashboard | amp-test-ManagerEx-8IKHVRJOUT98-636105687.us-west-2.elb.amazonaws.com:8080
internal endpoint for the registry service | disabled
public facing endpoint for the cluster | amp-test-ManagerEx-8IKHVRJOUT98-636105687.us-west-2.elb.amazonaws.com
You can now deploy a stackfile on your newly created local cluster.
The cluster has been created with the default configuration. You'll need to update it according to your convenience.
You should generate a certificate valid for the domain that will be served by the cluster. Ideally it can be a wildcard certificate, but it should at least include the virtual hosts amplifier, dashboard, kibana and alerts.
The default certificate is stored in the secret certificate_amp
. It should include the private key, the certificate and the full certificate chain (in this order). Create a new secret with your new certificate:
$ cat certificate.pem | docker secret create certificate_amp_custom -
Update the services that use it:
$ docker service update --secret-rm certificate_amp --secret-add source=certificate_amp_custom,target=/run/secrets/cert0.pem amp_amplifier
$ docker service update --secret-rm certificate_amp --secret-add source=certificate_amp_custom,target=/run/secrets/cert0.pem amp_proxy
Check that the service is stabilizing with the new configuration
$ docker service ps amp_amplifier
$ docker service ps amp_proxy
amp cluster create
uses a docker secret named amplifier_yml
for amplifier configuration.
If the secret is not present before the invocation of amp cluster create
, it will be automatically generated with sensible values for the following keys:
JWTSecretKey
: A secret key of 128 random characters will be generated.SUPassword
: A super user password of 32 characters will be generated and displayed during the execution of the command.If the secret is already created, it will be used as is without any modifications.
The secret amplifier_yml
contains the configuration for the user registration.
To enable it, you should get a Sendgrid key (you can have a 30 days trial key here.
$ cat > amplifier.yml << EOF
EmailKey: SENDGRID_KEY
SUPassword: SUPER_USER_PASSWORD
JWTSecretKey: JWT_RANDOM_STRING
EOF
$ cat amplifier.yml | docker secret create amplifier_yml_custom -
Update the service:
$ docker service update --secret-rm amplifier_yml --secret-add source=amplifier_yml_custom,target=/run/secrets/amplifier.yml amp_amplifier
Check that the service is stabilizing with the new configuration.
You can configure where notifications will be sent. The default (no notification configured) is in the secret alertmanager_yml
.
Create a new file with your configuration:
$ cat > alertmanager.yml << EOF
---
global:
slack_api_url: "https://hooks.slack.com/services/YOUR_WEB_HOOK"
templates:
- '/etc/alertmanager/template/*.tmpl'
route:
receiver: 'slack-receiver'
repeat_interval: 5m
routes:
- receiver: 'slack-receiver'
receivers:
- name: "slack-receiver"
slack_configs:
- channel: "@CHANNEL_NAME"
username: "Alertmanager"
title: '*DOMAIN_NAME* {{ range .Alerts }}{{ .Annotations.summary }} {{ end }}'
text: '{{ range .Alerts }}{{ .Annotations.description }} {{ end }}'
send_resolved: true
EOF
$ cat alertmanager.yml | docker secret create alertmanager_yml_custom -
Update the service:
$ docker service update --secret-rm alertmanager_yml --secret-add source=alertmanager_yml_custom,target=/run/secrets/alertmanager.yml amp_alertmanager
Check that the service is stabilizing with the new configuration.
Now you can also configure the alerts definitions. By default, the Docker config prometheus_alerts_rules
contains empty rules.
Create a new file with the configuration. You can find an example in the amp repo in examples/monitoring/prometheus_alerts.rules
.
$ cat prometheus_alerts.rules | docker config create prometheus_alerts_rules_custom -
Update the service
$ docker service update --config-rm prometheus_alerts_rules --config-add source=prometheus_alerts_rules_custom,target=/etc/prometheus/alerts.rules amp_prometheus
Check that the service is stabilizing with the new configuration.
You should create or update the domain name that you use to create the certificate. Use a service such as route53, dnsimple or similar to create a CNAME pointing to the DNS name from the output of the cluster creation. If you don't have access to it anymore, you can find it in the output of the cloudformation stack on the AWS console.
Wait for the DNS to be updated.
Use the CLI from your workstation (not from the cluster anymore) and check that the connection is done and that the certificate is valid:
$ amp -s DOMAIN_NAME user ls
Then signup a new user
$ amp -s DOMAIN_NAME user signup --name LOGIN --email EMAIL
You should receive an email with a command line for the validation of the account.
Note that if it is a test cluster, you can skip certificate creation step and use -k (--insecure) AMP CLI argument.
Also you can grab public endpoint (ELB) DNS name from Cloudformation -> Stacks - Outputs -> DNSTarget key.
$ DOMAIN_NAME=nderzhak-ManagerE-1FQNBP6KF3O24-818587690.us-west-2.elb.amazonaws.com; ./amp -s $DOMAIN_NAME -k user ls
[nderzhak-ManagerE-1FQNBP6KF3O24-818587690.us-west-2.elb.amazonaws.com:50101]
USERNAME EMAIL CREATED ON
su 29 Nov 17 14:41
You can remove the old secrets and config now that the cluster is configured and running.
$ docker secret rm amplifier_yml
$ docker secret rm alertmanager_yml
$ docker secret rm certificate_amp
$ docker config rm prometheus_alerts_rules
If you no longer use the deployed cluster, it can be removed by running the following command:
$ amp cluster rm --provider aws --aws-stackname $STACK_NAME --aws-sync
The cluster teardown on AWS takes about 10 minutes to complete. On success, the output looks something like this:
Fri Dec 8 01:17:16 UTC 2017 Vpc CREATE_COMPLETE
Fri Dec 8 01:19:34 UTC 2017 ManagerAutoScalingGroup CREATE_COMPLETE
Fri Dec 8 01:20:56 UTC 2017 ManagerWaitCondition CREATE_COMPLETE
Fri Dec 8 01:21:02 UTC 2017 UserWorkerAutoScalingGroup CREATE_COMPLETE
Fri Dec 8 01:21:02 UTC 2017 CoreWorkerAutoScalingGroup CREATE_COMPLETE
Fri Dec 8 01:21:58 UTC 2017 CoreWaitCondition CREATE_COMPLETE
Fri Dec 8 01:21:59 UTC 2017 UserWaitCondition CREATE_COMPLETE
Fri Dec 8 01:23:50 UTC 2017 ApplicationWaitCondition CREATE_COMPLETE
Fri Dec 8 01:23:54 UTC 2017 amp-test CREATE_COMPLETE
Fri Dec 8 01:26:12 UTC 2017 amp-test DELETE_IN_PROGRESS (User Initiated)
Fri Dec 8 01:26:14 UTC 2017 ApplicationWaitCondition DELETE_IN_PROGRESS
Fri Dec 8 01:26:15 UTC 2017 UserWaitCondition DELETE_IN_PROGRESS
Fri Dec 8 01:26:15 UTC 2017 CoreWaitCondition DELETE_IN_PROGRESS
Fri Dec 8 01:26:17 UTC 2017 UserWorkerAutoScalingGroup DELETE_IN_PROGRESS
Fri Dec 8 01:26:17 UTC 2017 CoreWorkerAutoScalingGroup DELETE_IN_PROGRESS
Fri Dec 8 01:29:54 UTC 2017 ManagerWaitCondition DELETE_IN_PROGRESS
Fri Dec 8 01:29:56 UTC 2017 ManagerAutoScalingGroup DELETE_IN_PROGRESS
Fri Dec 8 01:35:11 UTC 2017 Vpc DELETE_IN_PROGRESS
Fri Dec 8 01:35:30 UTC 2017 amp-test DELETE_COMPLETE
You can deploy your own stacks on your AMP cluster. This section is a WIP.
Alternatively, if you wish to work with the latest development version directly from master
on Github,
you can fork the repo and build your own CLI. The entire toolchain has been containerized so you only need to install Docker.
TIP: Here is the official Go documentation explaining how to create a Go project structure and set GOPATH.
To get the repo setup, you can run the following set of commands to clone the repository into your go
workspace and add the CLI path to your system PATH
.
$ cd $GOPATH/src
$ mkdir -p github.com/appcelerator
$ cd github.com/appcelerator
$ git clone https://github.com/appcelerator/amp
$ cd amp
$ export PATH=$GOPATH/src/github.com/appcelerator/amp/bin/{YourOS}/amd64:$PATH
To build the CLI and the core AMP images, you can then run:
$ ampmake build
This will build cross-compiled versions of the CLI and place them in the appropriate locations under ./bin
.
In addition, this will build the development versions of each of the images necessary for creation of the AMP cluster.
The amp cluster
command manages all cluster related operations for AMP.
$ amp cluster --help
Usage: amp cluster [OPTIONS] COMMAND
Cluster management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
-v, --volume stringSlice Bind mount a volume
Management Commands:
node Cluster node management operations
Commands:
create Set up a cluster in swarm mode
rm Destroy an amp cluster
status Retrieve details about an amp cluster
Run 'amp cluster COMMAND --help' for more information on a command.
NOTE: Currently a number of
amp cluster create
options are in a state of transition. We recommend you stick to the outlined examples for deploying cluster environments.
For learning how to deploy a cluster locally on your machine, see the section on local cluster creation
For learning how to deploy a cluster on AWS, see the section on AWS cluster creation
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.
$ amp cluster create
AMP comprises of 4 features:
It is possible to disable the optional features using the following commands:
To create a local cluster without metrics:
$ amp cluster create --local-no-metrics
To create a local cluster without logging:
$ amp cluster create --local-no-logs
To create a local cluster without proxy:
$ amp cluster create --local-no-proxy
$ amp cluster status
NOTE: You must be logged in to the AMP cluster to run this command.
$ amp cluster rm
If you don't have the AWS CLI installed, enter the following:
$ export REGION=us-west-2
$ export KEY_NAME=user-keypair
$ export ACCESS_KEY_ID=xxxxx
$ export SECRET_ACCESS_KEY=xxxxx
$ export STACK_NAME=amp-test
$ amp cluster create --provider aws --aws-region $REGION --aws-parameter KeyName=$KEY_NAME --aws-access-key-id $ACCESS_KEY_ID --aws-secret-access-key $SECRET_ACCESS_KEY --aws-stackname $STACK_NAME --aws-sync
If you have the AWS CLI installed, enter the following:
$ export KEY_NAME=user-keypair
$ export STACK_NAME=amp-test
$ amp cluster create --provider aws --aws-parameter KeyName=$KEY_NAME --aws-stackname $STACK_NAME --aws-sync
$ amp cluster rm --provider aws --aws-stackname $STACK_NAME --aws-sync
The amp completion
command allows you to add shell completion to your AMP CLI.
$ amp completion --help
Usage: amp completion SHELL [flags]
Output shell completion code for the specified shell (bash or zsh)
Examples:
# Install bash completion on a Mac using homebrew
$ brew install bash-completion
Once installed, bash_completion must be evaluated. This can be done by adding the
following line to the .bash_profile, and reloading it
source $(brew --prefix)/etc/bash_completion
$ source $HOME/.bash_profile
# Write bash completion code to a file
$ amp completion bash > ~/.config/amp/completion.bash.inc
Add this line in your $HOME/.bash_profile, and reload it
source "$HOME/.config/amp/completion.bash.inc"
$ source $HOME/.bash_profile
# Load the amp completion code for zsh[1] into the current shell
source <(amp completion zsh)
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.
In order to use shell completion with AMP, follow the installation instructions for your corresponding shell.
Make sure bash completion is installed:
brew install bash-completion
After bash completion is installed, add the following line to your ~/.bash_profile
file:
source $(brew --prefix)/etc/bash_completion
Then, either source your ~/.bash_profile
or launch a new terminal.
Now you need to write the bash completion, generated by AMP, to a file. We recommend writing
it to a file in your $HOME/.config/amp
directory.
$ amp completion bash > ~/.config/amp/completion.bash.inc
After doing this, add the following line to your ~/.bash_profile
file to source your bash completion file.
source "$HOME/.config/amp/completion.bash.inc"
Then either source your ~/.bash_profile
or launch a new terminal again.
In a Zsh shell, load the amp completion code with:
$ source <(amp completion zsh)
or add source <(amp completion zsh)
to your ~/.zshrc
file.
With the shell completion code loaded for AMP, you can hit tab twice to view the shell completion.
$ amp
cluster completion config login logout logs password service stack stats team user version whoami
$ amp stack
deploy logs ls rm services
$ amp stack deploy -c examples/stacks/pinger/
README.md pinger.yml
The amp config
command manages all configuration related operations for AMP.
$ amp config --help
Usage: amp config [OPTIONS] COMMAND
Configuration management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
create Create a config from a file or STDIN as content
ls List configs
remove Remove one or more configs
Run 'amp config COMMAND --help' for more information on a command.
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.NOTE: To be able to perform any secret related operations, you must be logged in to AMP using a verified account.
To create a config:
$ amp config create test ./test
66cxrj0wcn2ugqspyocmui2tb
On success, this command returns an alphanumeric ID which is the secret ID.
To list all config:
$ amp config ls
ID NAME
66cxrj0wcn2ugqspyocmui2tb test
c74xny5z0nv5mtyb8cl8k799y prometheus_alerts_rules
To remove one or more configs:
$ amp config rm test
test
The amp logs
command is used to query or stream logs. It provides useful filtering options to manage what is presented.
$ amp logs --help
Usage: amp logs [OPTIONS] SERVICE [flags]
Display logs matching provided criteria
Options:
--container string Filter by the given Container
-f, --follow Follow log output
-h, --help Print usage
-i, --include Include AMP logs
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-m, --meta Display entry metadata
--msg string Filter the message content by the given pattern
--node string Filter by the given node
-n, --number int32 Number of results (default 1000)
-r, --raw Display raw logs (no prefix)
--regexp Treat '--msg' option as a regular expression
-s, --server string Specify server (host:port)
--since int32 Number of days to include in the search (maximum 100) (default 2)
--stack string Filter by the given stack
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.NOTE: To be able to perform any logs related operations, you must be logged in to AMP using a verified account.
To fetch and follow all the logs:
$ amp logs -f
To fetch and follow the logs for a specific service:
$ amp logs -f amp_etcd
To search for a specific pattern through all the logs:
$ amp logs --msg error
To fetch the logs for a service called foobar
, using partial service name:
$ amp logs foo
To fetch infrastructure logs:
$ amp logs -i
To fetch all the logs and display metadata associated with each entry:
$ amp logs -m
The amp password
command is used to manage all password related operations for AMP.
$ amp password --help
Usage: amp password [OPTIONS] COMMAND
Password management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
change Change password
reset Reset password
set Set password
Run 'amp password COMMAND --help' for more information on a command.
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.
To update your current password:
$ amp password change
current password: [oldpassword]
new password: [newpassword]
Your password change has been successful.
If you have forgotten your password and need it reset:
$ amp password reset [username]
NOTE: If you are working on a cluster without email verification, such as a local cluster, this command will be disabled.
An email with instructions to reset password will be sent to the registered email address. In this email, you will be sent a link to reset your password with or you can reset it with the provided CLI command.
$ amp password set --token [token]
NOTE: If you are working on a cluster without email verification, such as a local cluster, this command will be disabled
The amp secret
command manages all operations related to AMP secrets.
$ amp secret --help
Usage: amp secret [OPTIONS] COMMAND
Secret management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
create Create a secret from a file or STDIN as content
ls List secrets
remove Remove one or more secrets
Run 'amp secret COMMAND --help' for more information on a command.
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.NOTE: To be able to perform any secret related operations, you must be logged in to AMP using a verified account.
To create a secret:
$ amp secret create test ./test
c60z5iv6kguxdk5p1n4p7lulm
On success, this command returns an alphanumeric ID which is the secret ID.
To list all secrets:
$ amp secret ls
ID NAME
8lpnhb7k140s65ftdjwav1k35 certificate_amp
c60z5iv6kguxdk5p1n4p7lulm test
huns47stt3ade3neufohl5pzg alertmanager_yml
i2gjv0m8ilhl5aqixmp0oeoy0 amplifier_yml
To remove one or more secrets:
$ amp secret rm test
test
The amp service
command is used to manage all service related operations for AMP.
$ amp service --help
Usage: amp service [OPTIONS] COMMAND
Service management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
inspect Display detailed information of a service
logs Display logs of given service matching provided criteria
ls List services
ps List tasks of a service
scale Scale a replicated service
Run 'amp service COMMAND --help' for more information on a command.
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.NOTE: To be able to perform any service related operations, you must be logged in to AMP using a verified account.
To inspect a service:
$ amp service inspect pinger
{
"ID": "0k1fzgc2pfuyowej0gedm6kmr",
"Version": {
"Index": 231
},
"CreatedAt": "2017-07-05T22:00:41.444720874Z",
"UpdatedAt": "2017-07-05T22:00:41.449032363Z",
"Spec": {
"Name": "pinger_pinger",
"Labels": {
"com.docker.stack.namespace": "pinger"
},
"TaskTemplate": {
"ContainerSpec": {
"Image": "subfuzion/pinger:latest",
"Labels": {
"com.docker.stack.namespace": "pinger"
},
"Env": [
"SERVICE_PORTS=3000",
"VIRTUAL_HOST=pinger.examples.*,https://pinger.examples.*"
],
"StopGracePeriod": 10000000000,
"DNSConfig": {}
},
...
TIP: Use the
service-id
orservice-name
as the argument.
To list the available services with detailed status about their tasks:
$ amp service ls
ID NAME MODE REPLICAS STATUS IMAGE TAG
0k1fzgc2pfuyowej0gedm6kmr pinger_pinger replicated 3/3 RUNNING appcelerator/pinger latest
NOTE: this command only displays services which are part of user deployed stacks.
To list the tasks of a service:
$ amp service ps pinger_pinger
ID NAME IMAGE DESIRED STATE CURRENT STATE NODE ID ERROR
2oyhxm5eon3u40didkvglc4oa pinger_pinger.1 appcelerator/pinger:latest RUNNING RUNNING 7z8aobvghzadvrb8n3zf22ake
9uy23btldzx9ww901djhaph4c pinger_pinger.2 appcelerator/pinger:latest RUNNING RUNNING 7z8aobvghzadvrb8n3zf22ake
nwm34nsxexmhujixni7b1k6gh pinger_pinger.3 appcelerator/pinger:latest RUNNING RUNNING 7z8aobvghzadvrb8n3zf22ake
To retrieve logs of a service:
$ amp service logs pinger
pinger_pinger.2 | listening on :3000
pinger_pinger.1 | listening on :3000
pinger_pinger.3 | listening on :3000
pinger_pinger.2 | listening on :3000
pinger_pinger.1 | listening on :3000
pinger_pinger.3 | listening on :3000
...
TIP: Use the
service-id
orservice-name
as the argument.
To scale up or scale down the number of replicas of the service:
$ amp service scale
service id or name: pinger_pinger
replicas: 2
Service pinger_pinger has been scaled to 2 replicas.
The amp settings
command displays settings for AMP CLI. It can be accessed by storing the value in a settings file or passing it as a command-line argument.
amp settings --help
Usage: amp settings [flags]
Display AMP settings
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
In order to start using the CLI settings:
.amp
in the current working (local) directory and add the config file amp.yml
in this directory, ORamp
in the $HOME/.config
directory and add the config file amp.yml
in this directory (This is the default location).Variable: value
NOTE: For the moment, the settings file only stores the
Server
parameter, which is used to point the CLI to a target cluster. More will be added in future releases.
If the settings file is placed in the directory $HOME/.config/amp
with Server: local.appcelerator.io
, you can view the settings of AMP using:
$ amp settings
[local.appcelerator.io:50101]
Settings file: $HOME/.config/amp/amp.yml
AMP Settings:
Server: local.appcelerator.io:50101
If the settings file is placed in the directory $PWD/.amp
with Server: local.appcelerator.io
, you can view the settings of AMP using:
$ amp settings
[local.appcelerator.io:50101]
Settings file: $PWD/.amp/amp.yml
AMP Settings:
Server: local.appcelerator.io:50101
If you have not defined a settings
file:
$ amp settings
[127.0.0.1:50101]
Settings file: none
AMP Settings:
Server: 127.0.0.1:50101
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.
The amp stack
command is used to manage all stack related operations for AMP.
$ amp stack --help
Usage: amp stack [OPTIONS] COMMAND
Stack management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
deploy Deploy a stack with a Docker Compose v3 file
logs Display filtered logs for stack
ls List deployed stacks
rm Remove one or more deployed stacks
services List services of a stack
Run 'amp stack COMMAND --help' for more information on a command.
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.NOTE: To be able to perform any stack related operations, you must be logged in to AMP using a verified account.
To deploy a stack using a compose file:
$ amp stack deploy -c examples/stacks/counter/counter.yml counter
Deploying stack counter using examples/stacks/counter/counter.yml
Creating service counter_go
Creating service counter_redis
NOTE: If no name is specified for the stack, the name of the stack will be the filename.
To list the deployed stacks, with detailed status about their services:
$ amp stack ls
ID NAME RUNNING COMPLETE PREPARING TOTAL SERVICES STATUS OWNER
95508f3ca3ad3877e8c33e69a92a9e3490eb60395bd1b26f0c6f80f1f5521976 counter 2 0 0 2 2/2 RUNNING su
NOTE: this command only displays stacks created by the user. No infrastructure stacks are displayed.
To list the services within a stack:
$ amp stack services counter
ID NAME MODE REPLICAS IMAGE
k5fzzzryjpda counter_redis replicated 1/1 redis
njsru7ka1gek counter_go replicated 3/3 htilford/go-redis-counter
To view the logs of the entire stack:
$ amp stack logs counter
...
1:M 05 Jul 21:21:36.050 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128.
1:M 05 Jul 21:21:36.056 # Server started, Redis version 3.2.9
1:M 05 Jul 21:21:36.056 # WARNING you have Transparent Huge Pages (THP) support enabled in your kernel. This will create latency and memory usage issues with Redis. To fix this issue run the command 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' as root, and add it to your /etc/rc.local in order to retain the setting after a reboot. Redis must be restarted after THP is disabled.
...
To update a stack with a new compose file:
$ amp stack deploy -c examples/stacks/counter/counter-2.yml counter
Deploying stack counter using examples/stacks/counter/counter-2.yml
Updating service counter_go (id: njsru7ka1gek1xzdt6z4b8wez)
Updating service counter_redis (id: k5fzzzryjpdaanlvqqu5b5qr7)
To remove a stack:
$ amp stack rm counter
Removing service counter_redis
Removing service counter_go
The amp team
command is used to manage all team related operations for AMP.
$ amp team --help
Usage: amp team [OPTIONS] COMMAND
Team management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Management Commands:
member Manage team members
resource Manage team resources
Commands:
create Create team
get Get team information
ls List teams
rm Remove one or more teams
Run 'amp team COMMAND --help' for more information on a command.
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.NOTE: To be able to perform any team related operations, you must be logged in to AMP using a verified account.
NOTE:
amp team
commands that require the--team
option will remember the last used team using a local preferences file. If you want to override this, specify the--team
option in the command.
To create a team:
$ amp team create team
Team has been created.
To retrieve details of a specific team:
$ amp team get team
Team: team
Created On: 05 Dec 17 15:25
To retrieve the list of teams:
$ amp team ls
TEAM CREATED ON
team 05 Dec 17 15:25
To remove a team:
$ amp team rm team
team
The amp team member
command is used to manage all team member related operations for AMP.
$ amp team member --help
Usage: amp team member [OPTIONS] COMMAND
Manage team members
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
add Add one or more members
ls List members
rm Remove one or more members
Run 'amp team member COMMAND --help' for more information on a command.
To add a member to a team:
$ amp team member add johndoe
team name: team
Member(s) have been added to team.
NOTE: The member to be added to the team must be a existing and verified user account.
To list members in a team:
$ amp team member ls --team team
team name: team
MEMBER
sample
johndoe
...
To remove a member from a team:
$ amp team member rm johndoe
team name: team
johndoe
The amp team resource
command is used to manage all team resource related operations for AMP.
$ amp team resource --help
Usage: amp team resource [OPTIONS] COMMAND
Manage team resources
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
add Add one or more resources
ls List resources
perm Change permission level over a resource
rm Remove one or more resources
Run 'amp team resource COMMAND --help' for more information on a command.
To add a resource to a team:
$ amp team resource add 93fce7d3f...
team name: team
Resource(s) have been added to team.
NOTE: Resources can be stacks.
To list resources available to a team:
$ amp team resource ls
team name: team
RESOURCE ID PERMISSION LEVEL
93fce7d3fc8ada786c7db6956849343bcc5700f65d8b1512523561166a2ec455 TEAM_READ
To change the permission level of a resource:
$ amp team resource perm 93fce7d3f... write
team name: team
Permission level has been changed.
The default permission level of a resource is read
. The permission level can be changed to read
, write
or admin
.
To remove a resource from a team:
$ amp team resource rm --team team 93fce7d3f...
team name: team
93fce7d3fc8ada786c7db6956849343bcc5700f65d8b1512523561166a2ec455
The amp user
command is used to manage all user related operations for AMP.
Other user-related commands that are not managed by amp user
include login
, logout
and whoami
.
$ amp user --help
Usage: amp user [OPTIONS] COMMAND
User management operations
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
Commands:
forgot-login Retrieve account name
get Get user information
ls List users
resend-verification-token Resend verification email to registered address
rm Remove one or more users
signup Signup for a new account
verify Verify account
Run 'amp user COMMAND --help' for more information on a command.
TIP: Use
-h
or--help
option for any of the AMP commands or sub-commands to more information about the command's usage.
NOTE: For the purpose of illustration, we will use the local cluster (which is default) for running AMP commands.
$ amp user signup
[your.server.com:50101]
username: sample
email: sample@amp.com
password: [password]
[user sample @ your.server.com:50101]
Hi sample! Please check your email to complete the signup process.
NOTE: If you are working on a cluster without email verification, such as a local cluster, you will not need to verify your account as you will not be sent an email and you will be logged in automatically.
amp user signup [127.0.0.1:50101] username: sample email: sample@amp.co, password: Verification is not necessary for this cluster. Hi sample! You have been automatically logged in.
After signing up, you will then be sent an email to your registered address. In this email, you will be sent a link to verify your account with or you can verify your account with the provided CLI command.
To verify your account using the token in verification email:
$ amp user verify [token]
[your.server.com:50101]
Your account has now been activated.
NOTE: If you are working on a cluster without email verification, such as a local cluster, this command will be disabled.
amp -k user verify <TOKEN> [user sample @ 127.0.0.1:50101] Error: `amp user verify` disabled. This cluster has no registration policy
If you are using hosted AMP, you will need to verify your account.
To login to your new account:
$ amp login
[127.0.0.1:50501]
username: sample
password: [password]
Welcome back sample!
Once you have logged in, you can check who is currently logged in with amp whoami
:
$ amp whoami
[user sample @ 127.0.0.1:50101]
Logged in as user: sample
In addition, every amp
command will display who you are logged in as at the top of the command output.
$ amp
[user sample @ 127.0.0.1:50101]
Usage: amp [OPTIONS] COMMAND
...
$ amp logout
[user sample @ 127.0.0.1:50101]
You have been logged out!
$ amp user forgot-login sample@amp.com
Your login name has been sent to the address: sample@amp.com
NOTE: If you are working on a cluster without email verification, this command will be disabled.
$ amp user get foo
$ amp user ls
$ amp user rm foo
This command only allows you to delete your own account. If you try to delete another user, you will see the following error:
$ amp user rm sample1
[user sample @ 127.0.0.1:50101]
Error: user not authorized
However, the `su` account has the privileges of removing other accounts in the cluster.
The amp version
command displays the current version of AMP.
$ amp version --help
Usage: amp version [flags]
Show version information
Options:
-h, --help Print usage
-k, --insecure Control whether amp verifies the server's certificate chain and host name
-s, --server string Specify server (host:port)
TIP: It would be useful to set an alias for
amp
asalias amp='amp -k'
in case the certificate on the server is not valid.NOTE: For the purpose of illustration, we will use the local cluster (which is default) for running AMP commands.
$ amp version
Client:
Version: v0.10.0-dev
Build: 6f590348
Server: 127.0.0.1:50101
Go version: go1.8
OS/Arch: darwin/amd64
Server:
Version: v0.10.0-dev
Build: 04daab98
Go version: go1.8.1
OS/Arch: linux/amd64
NOTE: The above example is just a sample of the output of
amp version
command. The output will vary according to the version of AMP used.
$ amp version
Client:
Version: v0.12.0-dev
Build: 4166f646
Server: 127.0.0.1:50101
Go version: go1.8
OS/Arch: darwin/amd64
Server: not connected
Error: unable to establish grpc connection: context deadline exceeded
NOTE: The above example is just a sample of the output of
amp version
command. The output will vary according to the version of AMP used.