cloudsoft.io

CLI Usage Guide

This document provides a brief overview of using the most common AMP CLI commands, by using the CLI to deploy an application then examine various aspects of it.

The YAML blueprint for the application that will be deployed is shown at the end of this document.

NOTE: In the sample output, some additional line-wrapping has been used to aid readabilty. Additionally, the vertical bar character is omitted from table output for readability. For scripting purposes it can be useful in conjunction with a shell pipeline like some_command | cut -f 1 -d '|' | xargs -L1 some_other_command.

Login

First, login to the running AMP server. This example assumes that the AMP server is running on localhost configured to use basic authorization; change the URL and credentials as necessary.

$ br login http://localhost:8081 admin
Enter Password: *
Connected to AMP version 0.9.0-SNAPSHOT at http://localhost:8081

The version of the connected AMP server may be viewed with the version command:

$ br version
0.9.0-SNAPSHOT

Applications

Deploy the application; on success the Id of the new application is displayed:

$ br deploy webapp-policy.yaml
Id:       lmOcZbsT   
Name:     WebCluster   
Status:   In progress

The application command can be used to list a summary of all the running applications. After all of the entities have been started, the application status changes to RUNNING:

$ br application
Id         Name         Status    Location   
YeEQHwgW   AppCluster   RUNNING   CNTBOtjI
lmOcZbsT   WebCluster   RUNNING   CNTBOtjI

Further details of an application can be seen by using the ApplicationID or Name as a parameter for the application command:

$ br application WebCluster
Id:              lmOcZbsT   
Name:            WebCluster   
Status:          RUNNING   
ServiceUp:       true   
Type:            org.apache.brooklyn.entity.stock.BasicApplication   
CatalogItemId:   null   
LocationId:      CNTBOtjI   
LocationName:    FixedListMachineProvisioningLocation:CNTB   
LocationSpec:    byon   
LocationType:    org.apache.brooklyn.location.byon.FixedListMachineProvisioningLocation

The configuration details of an application can be seen with the config command:

$ br application WebCluster config
Key                    Value   
camp.template.id       TYWVroRz   
brooklyn.wrapper_app   true

Entities

The entities of an application can be viewed with the entity command:

$ br app WebCluster entity
Id        Name    Type   
xOcMooka  WebApp  org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
thHnLFkP  WebDB   org.apache.brooklyn.entity.database.mysql.MySqlNode

It is common for an entity to have child entities; these can be listed by providing an entity-scope for the entity command:

$ br app WebCluster entity WebApp entity
Id         Name                     Type   
e5pWAiHf   Cluster of TomcatServer  org.apache.brooklyn.entity.webapp.DynamicWebAppCluster   
CZ8QUVgX   NginxController:CZ8Q     org.apache.brooklyn.entity.proxy.nginx.NginxController

or by using -c (or --children) flag with the entity command:

$ br app WebCluster entity -c e5pWAiHf
Id         Name               Type   
x0P2LRxZ   quarantine         org.apache.brooklyn.entity.group.QuarantineGroup   
QK6QjmrW   TomcatServer:QK6Q  org.apache.brooklyn.entity.webapp.tomcat.TomcatServer

As for applications, the configuration details of an entity can be seen with the config command:

$ br app WebCluster entity thHnLFkP config
Key                                      Value   
install.unique_label                     MySqlNode_5.6.26   
brooklyn.wrapper_app                     true   
datastore.creation.script.template.url   https://bit.ly/brooklyn-visitors-creation-script   
camp.template.id                         dnw3GqN0   
camp.plan.id                             db   
onbox.base.dir                           /home/vagrant/brooklyn-managed-processes   
onbox.base.dir.resolved                  true

The value of a single configuration item can be displayed by using the configuration key as a parameter for the config command:

$ br app WebCluster entity thHnLFkP config datastore.creation.script.template.url
https://bit.ly/brooklyn-visitors-creation-script

The value of a configuration item can be changed by using the set command:

$ br app WebCluster entity thHnLFkP config datastore.creation.script.template.url set \"https://bit.ly/new-script\"

Sensors

The sensors associated with an application or entity can be listed with the sensor command:

$ br app WebCluster entity CZ8QUVgX sensor
Name                                    Value
download.addon.urls:                    {"stickymodule":"https://bitbucket.org/nginx-goodies/n  
                                        ginx-sticky-module-ng/get/${addonversion}.tar.gz","pcr  
                                        e":"ftp://ftp.csx.cam.ac.uk/pub/software/programming/p  
                                        cre/pcre-${addonversion}.tar.gz"}
download.url:                           http://nginx.org/download/nginx-${version}.tar.gz
expandedinstall.dir:                    /home/vagrant/brooklyn-managed-processes/installs/Ngi  
                                        nxController_1.8.0/nginx-1.8.0
host.address:                           192.168.52.102
host.name:                              192.168.52.102
host.sshAddress:                        vagrant@192.168.52.102:22
host.subnet.address:                    192.168.52.102
host.subnet.hostname:                   192.168.52.102
http.port:                              8000
install.dir:                            /home/vagrant/brooklyn-managed-processes/installs/Ngin  
                                        xController_1.8.0
log.location:                           /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2  
                                        /entities/NginxController_CZ8QUVgX/console
main.uri:                               http://192.168.52.102:8000/
member.sensor.hostandport:
member.sensor.hostname:                 {"typeToken":null,"type":"java.lang.String","name":"ho  
                                        st.subnet.hostname","description":"Host name as known   
                                        internally in the subnet where it is running (if diffe  
                                        rent to host.name)","persistence":"REQUIRED"}
member.sensor.portNumber:               {"typeToken":null,"type":"java.lang.Integer","name":"h  
                                        ttp.port","description":"HTTP port","persistence":"RE  
                                        QUIRED","configKey":{"name":"http.port","typeToken":nu  
                                        ll,"type":"org.apache.brooklyn.api.location.PortRange"  
                                        ,"description":"HTTP port","defaultValue":{"ranges":[{  
                                        "port":8080},{"start":18080,"end":65535,"delta":1}]},"  
                                        reconfigurable":false,"inheritance":null,"constraint":  
                                        "ALWAYS_TRUE"}}
nginx.log.access:                       /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2  
                                        /entities/NginxController_CZ8QUVgX/logs/access.log
nginx.log.error:                        /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2  
                                        /entities/NginxController_CZ8QUVgX/logs/error.log
nginx.pid.file:                         /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2  
                                        /entities/NginxController_CZ8QUVgX/pid.txt
nginx.url.answers.nicely:               true
proxy.domainName:
proxy.http.port:                        8000
proxy.https.port:                       8443
proxy.protocol:                         http
proxy.serverpool.targets:               {"TomcatServerImpl{id=QK6QjmrW}":"192.168.52.103:8080"}
run.dir:                                /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2  
                                        /entities/NginxController_CZ8QUVgX
service.isUp:                           true
service.notUp.diagnostics:              {}
service.notUp.indicators:               {}
service.problems:                       {}
service.process.isRunning:              true
service.state:                          RUNNING
service.state.expected:                 running @ 1449314377781 / Sat Dec 05 11:19:37 GMT 2015
softwareprocess.pid.file:
softwareservice.provisioningLocation:   {"type":"org.apache.brooklyn.api.location.Location","i  
                                        d":"zhYBc6xt"}
webapp.url:                             http://192.168.52.102:8000/

Details for an individual sensor can be shown by providing the Sensor Name as a parameter to the sensor command:

$ br app WebCluster entity CZ8QUVgX sensor service.state.expected
running @ 1449314377781 / Sat Dec 05 11:19:37 GMT 2015

Effectors

The effectors for an application or entity can be listed with the effector command:

$ br app WebCluster effector
Name      Description                                            Parameters   
restart   Restart the process/service represented by an entity      
start     Start the process/service represented by an entity     locations   
stop      Stop the process/service represented by an entity         
$ br app WebCluster entity NginxController:CZ8Q effector
Name                              Description                     Parameters   
deploy                            Deploys an archive ...
getCurrentConfiguration           Gets the current ...      
populateServiceNotUpDiagnostics   Populates the attribute ...
reload                            Forces reload of ...  
restart                           Restart the process/service ... restartChildren,restartMachine
start                             Start the process/service ...   locations
stop                              Stop the process/service ...    stopProcessMode,stopMachineMode
update                            Updates the entities ...

Details of an individual effector can be viewed by using the name as a parameter for the effector command:

$ br app WebCluster entity NginxController:CZ8Q effector update
Name:         update
Description:  Updates the entities configuration, and then forces reload of that configuration
Parameters:

An effector can be invoked by using the invoke command with an effector-scope:

$ br app WebCluster entity NginxController:CZ8Q effector update invoke

Parameters can also be passed to the effector:

$ br app WebCluster entity NginxController:CZ8Q effector restart invoke -P restartChildren=true

If a parameter value is complex or spans multiple lines, it may be provided in a file and used like this:

$ br app WebCluster effector start invoke -P locations=@data.txt

Shortcut commands are available for the 3 standard effectors of start, restart and stop. These commands can be used directly with an app-scope or entity-scope:

$ br app WebCluster entity NginxController:CZ8Q restart
$ br app WebCluster stop

Policies

The policies associated with an application or entity can be listed with the policy command:

$ br app WebCluster entity NginxController:CZ8Q policy
Id         Name                         State   
VcZ0cfeO   Controller targets tracker   RUNNING

Details of an individual policy may be viewed by using the PolicyID as a parameter to the policy command:

$ br app WebCluster entity NginxController:CZ8Q policy VcZ0cfeO
Name                 Value                                    Description   
group                DynamicWebAppClusterImpl{id=TpbkaK4D}    group   
notifyOnDuplicates   false                                    Whether to notify listeners when
                                                              a sensor is published with the
                                                              same value as last time   
sensorsToTrack       [Sensor: host.subnet.hostname            Sensors of members to be monitored
                     (java.lang.String), Sensor: http.port    (implicitly adds service-up
                     (java.lang.Integer)]                     to this list, but that
                                                              behaviour may be deleted in a
                                                              subsequent release!)

Activities

The activities for an application or entity may be listed with the activity command:

$ br app WebCluster activity
Id         Task                                   Submitted                      Status      Streams   
Wb6GV5rt   start                                  Sat Dec 19 11:08:01 GMT 2015   Completed      
q2MbyyTo   invoking start[locations] on 2 nodes   Sat Dec 19 11:08:01 GMT 2015   Completed      
$ br app WebCluster entity NginxController:CZ8Q activity
Id         Task                                       Submitted                      Status      Streams   
GVh0pyKG   start                                      Sun Dec 20 19:18:06 GMT 2015   Completed          
WJm908rA   provisioning (FixedListMachineProvisi...   Sun Dec 20 19:18:06 GMT 2015   Completed          
L0cKFBrW   pre-start                                  Sun Dec 20 19:18:06 GMT 2015   Completed              
D0Ab2esP   ssh: initializing on-box base dir ./b...   Sun Dec 20 19:18:06 GMT 2015   Completed   env,stderr,stdin,stdout
tumLAdo4   start (processes)                          Sun Dec 20 19:18:06 GMT 2015   Completed                  
YbF2czKM   copy-pre-install-resources                 Sun Dec 20 19:18:06 GMT 2015   Completed                                     
o3YdqxsQ   pre-install                                Sun Dec 20 19:18:06 GMT 2015   Completed                 
TtGw4qMZ   pre-install-command                        Sun Dec 20 19:18:06 GMT 2015   Completed        
duPvOSDB   setup                                      Sun Dec 20 19:18:06 GMT 2015   Completed       
WLtkbhgW   copy-install-resources                     Sun Dec 20 19:18:06 GMT 2015   Completed           
ZQtrImnl   install                                    Sun Dec 20 19:18:06 GMT 2015   Completed           
hzi49YD6   ssh: setting up sudo                       Sun Dec 20 19:18:06 GMT 2015   Completed   env,stderr,stdin,stdout
eEUHcpfi   ssh: Getting machine details for: Ssh...   Sun Dec 20 19:18:07 GMT 2015   Completed   env,stderr,stdin,stdout
juTe2qLG   ssh: installing NginxControllerImpl{i...   Sun Dec 20 19:18:08 GMT 2015   Completed   env,stderr,stdin,stdout
hXqwEZJl   post-install-command                       Sun Dec 20 19:18:08 GMT 2015   Completed          
vZliYwBI   customize                                  Sun Dec 20 19:18:08 GMT 2015   Completed            
O4Wwb0bP   ssh: customizing NginxControllerImpl{...   Sun Dec 20 19:18:08 GMT 2015   Completed   env,stderr,stdin,stdout
sDwMSkE2   copy-runtime-resources                     Sun Dec 20 19:18:08 GMT 2015   Completed         
yDYkdkS8   ssh: create run directory                  Sun Dec 20 19:18:08 GMT 2015   Completed   env,stderr,stdin,stdout
W7dI8r1c   pre-launch-command                         Sun Dec 20 19:18:08 GMT 2015   Completed           
OeZKwM5z   launch                                     Sun Dec 20 19:18:08 GMT 2015   Completed          
y50Gne5E   scheduled:nginx.url.answers.nicely @ ...   Sun Dec 20 19:18:08 GMT 2015   Scheduler,      
ARTninGE   scheduled:service.process.isRunning @...   Sun Dec 20 19:18:08 GMT 2015   Scheduler,      
tvZoNUTN   ssh: launching NginxControllerImpl{id...   Sun Dec 20 19:18:08 GMT 2015   Completed   env,stderr,stdin,stdout
YASrjA4w   post-launch-command                        Sun Dec 20 19:18:09 GMT 2015   Completed             
jgLYv8pE   post-launch                                Sun Dec 20 19:18:09 GMT 2015   Completed          
UN9OcWLS   post-start                                 Sun Dec 20 19:18:09 GMT 2015   Completed           
nmiv97He   reload                                     Sun Dec 20 19:18:09 GMT 2015   Completed            
FJfPbNtp   ssh: restarting NginxControllerImpl{i...   Sun Dec 20 19:18:10 GMT 2015   Completed   env,stderr,stdin,stdout
Xm1tjvKf   update                                     Sun Dec 20 19:18:40 GMT 2015   Completed        
Row67vfa   reload                                     Sun Dec 20 19:18:40 GMT 2015   Completed           
r8QZXlxJ   ssh: restarting NginxControllerImpl{i...   Sun Dec 20 19:18:40 GMT 2015   Completed   env,stderr,stdin,stdout

The detail for an individual activity can be viewed by providing the ActivityID as a parameter to the activity command (an app-scope or entity-scope is not not needed for viewing the details of an activity):

$ br activity tvZoNUTN
Id:                  tvZoNUTN   
DisplayName:         ssh: launching NginxControllerImpl{id=OxPUBk1p}   
Description:            
EntityId:            OxPUBk1p   
EntityDisplayName:   NginxController:OxPU   
Submitted:           Sun Dec 20 19:18:08 GMT 2015   
Started:             Sun Dec 20 19:18:08 GMT 2015   
Ended:               Sun Dec 20 19:18:09 GMT 2015   
CurrentStatus:       Completed   
IsError:             false   
IsCancelled:         false   
SubmittedByTask:     OeZKwM5z   
Streams:             stdin: 1133, stdout: 162, stderr: 0, env 0   
DetailedStatus:      "Completed after 1.05s

Result: 0"

The activity command output shows whether any streams were associated with it. The streams and environment for an activity can be viewed with the commands stdin, stdout, stderr and env:

$ br activity tvZoNUTN stdin
export RUN_DIR="/home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p"
mkdir -p $RUN_DIR
cd $RUN_DIR
cd /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p
{ which "./sbin/nginx" || { EXIT_CODE=$? && ( echo "The required executable \"./sbin/nginx\" does not exist" | tee /dev/stderr ) && exit $EXIT_CODE ; } ; }
nohup ./sbin/nginx -p /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/ -c conf/server.conf > /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/console 2>&1 &
for i in {1..10}
do
    test -f /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/logs/nginx.pid && ps -p `cat /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/logs/nginx.pid` && exit
    sleep 1
done
echo "No explicit error launching nginx but couldn't find process by pid; continuing but may subsequently fail"
cat /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/console | tee /dev/stderr
$ br activity tvZoNUTN stdout
./sbin/nginx
  PID TTY          TIME CMD
 6178 ?        00:00:00 nginx
Executed /tmp/brooklyn-20151220-191808796-CaiI-launching_NginxControllerImpl_.sh, result 0

The child activities of an activity may be listed by providing an activity-scope for the activity command:

$ br activity OeZKwM5z
Id:                  OeZKwM5z   
DisplayName:         launch   
Description:            
EntityId:            OxPUBk1p   
EntityDisplayName:   NginxController:OxPU   
Submitted:           Sun Dec 20 19:18:08 GMT 2015   
Started:             Sun Dec 20 19:18:08 GMT 2015   
Ended:               Sun Dec 20 19:18:09 GMT 2015   
CurrentStatus:       Completed   
IsError:             false   
IsCancelled:         false   
SubmittedByTask:     tumLAdo4   
Streams:                
DetailedStatus:      "Completed after 1.06s

No return value (null)"

$ br activity OeZKwM5z activity
Id         Task                                       Submitted                      Status      Streams   
tvZoNUTN   ssh: launching NginxControllerImpl{id...   Sun Dec 20 19:18:08 GMT 2015   Completed   env,stderr,stdin,stdout

or by using the -c (or --children) flag with the activity command:

$ br activity -c OeZKwM5z
Id         Task                                       Submitted                      Status      Streams   
tvZoNUTN   ssh: launching NginxControllerImpl{id...   Sun Dec 20 19:18:08 GMT 2015   Completed   env,stderr,stdin,stdout

YAML Blueprint

This is the YAML blueprint used for this document, based on the web cluster examples.

name: WebCluster

location:
  byon:
    user: vagrant
    password: vagrant
    hosts:
      - 192.168.52.101
      - 192.168.52.102
      - 192.168.52.103
      - 192.168.52.104
      - 192.168.52.105

services:

- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
  name: WebApp
  brooklyn.config:
    wars.root: https://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.12.0/brooklyn-example-hello-world-sql-webapp-0.12.0.war # BROOKLYN_VERSION
    java.sysprops:
      brooklyn.example.db.url: >
        $brooklyn:formatString("jdbc:%s%s?user=%s&password=%s",
        component("db").attributeWhenReady("datastore.url"),
        "visitors", "brooklyn", $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password"))
  brooklyn.policies:
  - type: org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
    brooklyn.config:
      metric: webapp.reqs.perSec.windowed.perNode
      metricLowerBound: 2
      metricUpperBound: 10
      minPoolSize: 1
      maxPoolSize: 2
      resizeUpStabilizationDelay: 1m
      resizeDownStabilizationDelay: 5m

- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
  id: db
  name: WebDB
  brooklyn.config:
    creation.script.password: $brooklyn:external("brooklyn-demo-sample", "hidden-brooklyn-password")
    creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script

AMP and Maeztro are developed and supported by Cloudsoft Corporation.