| --- |
| title: CLI Usage Guide |
| --- |
| |
| This document provides a brief overview of using the most common Brooklyn 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 Brooklyn server. This example assumes that the Brooklyn server |
| is running on `localhost`; change the URL and credentials as necessary. |
| |
| ```text |
| $ br login http://localhost:8081 admin |
| Enter Password: * |
| Connected to Brooklyn version 0.9.0-SNAPSHOT at http://localhost:8081 |
| ``` |
| |
| The version of the connected Brooklyn server may be viewed with the `version` command: |
| |
| ```text |
| $ br version |
| 0.9.0-SNAPSHOT |
| ``` |
| |
| ## Applications |
| Deploy the application; on success the Id of the new application is displayed: |
| |
| ```text |
| $ 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`: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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 |
| ``` |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ br app WebCluster entity NginxController:CZ8Q effector update invoke |
| ``` |
| |
| Parameters can also be passed to the effector: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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 |
| ``` |
| |
| ```text |
| $ 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): |
| |
| ```text |
| $ 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`: |
| |
| ```text |
| $ 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 |
| ``` |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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: |
| |
| ```text |
| $ 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]({{book.path.docs}}/blueprints/clusters-and-policies.md) examples. |
| |
| ```text |
| 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: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war |
| 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 |
| ``` |
