Orchestration engine¶

The orchestration engine is the heart of the whole system. Its responsibility is to listen to ZooKeeper events (coming from the glu agents), compute the delta and orchestrate the deployment plans.

Note

Currently the orchestration engine is bundled with the console and is not running as a separate process. Please check the console documentation regarding installation and configuration.

Key Components¶

Tracker¶

The role of the tracker is to listen to ZooKeeper events. Under the cover, the tracker uses ZooKeeper watches. This makes the tracker very leightweight and efficient as it receives notifications only when something changes in the system.

For example, it gets notified immediately when:

a new agent is added (case when a new node is added to the system)
an agent disappears (case when a node crashes or reboot for example)
a script state changes
...

From the information collected (and updated real-time) by the tracker, the orchestration engine can compute the live model.

Live Model¶

The live model is computed by the orchestration engine from the information collected by the tracker. The live model is the representation of the live state which is used for computing the delta. Besides being used as an input to the delta service in order to compute the delta, the live model has several representation that you have access to:

From the console¶

If you navigate to an agent view page in the console, and for any given entry you click on the View Details (toggle), you will see something like this:

The information displayed here is exactly what the tracker has captured from ZooKeeper.

Note

In this screenshot you can even see how the script running on the remote agent has detected a failure and reported it. Thanks to ZooKeeper watches, the failure is propagated real-time and made available so that the user can fix the problem.

From the command line¶

From a shell terminal, you can issue:

./bin/console-cli.sh -f glu-dev-1 -u admin -x admin -b -l status

The important flag is -l which request the live model. You get an output very similar to the one in the console (more detailed though):

{
  "entries": [{
    "agent": "agent-1",
    "initParameters": {
      "port": 9000,
      "skeleton": "http://localhost:8080/glu/repository/tgzs/jetty-distribution-7.2.2.v20101205.tar.gz",
      "webapps": [
        {
          "contextPath": "/cp1",
          "monitor": "/monitor",
          "war": "http://localhost:8080/glu/repository/wars/org.linkedin.glu.samples.sample-webapp-2.2.0.war"
        },
        {
          "contextPath": "/cp2",
          "monitor": "/monitor",
          "war": "http://localhost:8080/glu/repository/wars/org.linkedin.glu.samples.sample-webapp-2.2.0.war"
        }
      ]
    },
    "metadata": {
      "cluster": "c1",
      "container": {"name": "sample"},
      "currentState": "stopped",
      "error": "Server down detected. Check the log file for errors.",
      "modifiedTime": 1302883875857,
      "product": "product1",
      "scriptState": {
        "script": {
          "gcLog": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/logs/gc.log",
          "logsDir": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/logs/",
          "port": 9000,
          "serverCmd": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/bin/jetty-ctl.sh",
          "serverLog": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/logs/start.log",
          "serverRoot": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/",
          "version": "2.2.0",
          "webapps": {
            "/cp1": {
              "context": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/contexts/_cp1.xml",
              "contextPath": "/cp1",
              "localWar": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/wars/_cp1.war",
              "monitor": "/monitor",
              "remoteWar": "http://localhost:8080/glu/repository/wars/org.linkedin.glu.samples.sample-webapp-2.2.0.war"
            },
            "/cp2": {
              "context": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/contexts/_cp2.xml",
              "contextPath": "/cp2",
              "localWar": "file:/export/content/glu/org.linkedin.glu.packaging-all-2.2.0/apps/sample/i001/wars/_cp2.war",
              "monitor": "/monitor",
              "remoteWar": "http://localhost:8080/glu/repository/wars/org.linkedin.glu.samples.sample-webapp-2.2.0.war"
            }
          }
        },
        "stateMachine": {
          "currentState": "stopped",
          "error": "Server down detected. Check the log file for errors."
        },
        "timers": [{
          "repeatFrequency": "15s",
          "timer": "serverMonitor"
        }]
      },
      "version": "1.0.0"
    },
    "mountPoint": "/sample/i001",
    "script": "http://localhost:8080/glu/repository/scripts/org.linkedin.glu.script-jetty-2.2.0/JettyGluScript.groovy",
    "tags": [
      "frontend",
      "osx",
      "webapp"
    ]
  }],
  "fabric": "glu-dev-1",
  "metadata": {
    "accuracy": "ACCURATE",
    "emptyAgents": []
  }
}

Note

without any filter (see Filtering), you will get the entire model, not just the single entry. In order to select a single entry you can use the filter shortcut -I agent-1:/sample/i001 like this:

./bin/console-cli.sh -f glu-dev-1 -u admin -x admin -b -l -I agent-1:/sample/i001 status

Static Model¶

The static model is an input to the orchestration engine. It describes the state of the entire system (for a given fabric). The static model gets loaded in the orchestration engine either from the console web application, REST api or command line (-m option). Once loaded, the static model remains the current model until a new one is loaded.

Tip

Check out the separate entry about the static model for more information.

Delta Service¶

The delta service is in charge of computing the delta between the live model and the static model. As mentionned previously, the static model used is the latest one that was loaded (or selected as current). The live model is coming from the tracker.

Note

In the event that there is an issue with the connection to ZooKeeper, the delta service will still be able to generate deltas but they will be flagged accordingly because the live model is no longer real-time. In the output of the live model you can see this in action (in this case there was no problem):

"metadata": {
  "accuracy": "ACCURATE",
  ...
}

Delta¶

The delta is the result of the computation done by the delta service. The delta is fed into the visualizer and/or the planner.

Note

At this moment, the delta is an internal concept not directly available but as it is driving the visualizer and planner, you have the ability to see different representations of it.

Visualizer¶

The visualizer is in charge of turning the delta into a visual representation. This is represented in the console by the dashboard:

In this screenshot which represents 3 applications deployed on 1 agent (coming from the tutorial) you can directly see the delta in action:

when a row is green (2nd row), it means that there is actually no delta: the static model and the live model are identical (or another way to say it, is that the desired state matches the live state)
when a row is red (1st and 3rd row), it means that there is a discrepancy between the static model and the live model. The last column (status) is giving more information about what kind of delta was detected:
- for row 1, the application is actually deployed but is not running (this is what you can see in the screenshot for the live model): the entry appears in the live model but with a mismatching state
- for row 3, the application is not deployed at all: the entry is totally absent from the live model

Planner¶

The planner is in charge of turning the delta into a deployment plan.

Deployment Plan¶

The deployment plan is the set of instructions (generated by the planner) which can be fed to the deployer in order to fix the delta computed by the delta service. The idea is that if all instructions get executed successfully, then there won’t be any delta anymore.

An instruction is (usually) a call (using the secure REST api) to an agent to perform a particular action (as described in the section “glu Script Engine”).

Note

As mentionned in the What is glu? section, the plan is never executed unless you give your explicit approval.

The deployment plan has several representations:

From the Console¶

Using the same delta you could visualize on the dashboard, the planner can compute various plans depending on what you instruct it to do.

From the console, you have the ability to

select a sequential plan:
select a parallel plan:

Note

the numbers in front of each instruction show you in which order they will be executed. A parallel plan will execute much faster than a sequential plan since the instructions will run in parallel so you don’t have to wait for previous instructions to complete. In a sequential plan, an error in an instruction will abort the entire remaining of the plan.

From the Command Line¶

The exact same data is also available from the command line (hence the REST api):

./bin/console-cli.sh -f glu-dev-1 -u admin -x admin -a -n deploy

will produce the following output (sequential):

<?xml version="1.0"?>
<plan name="origin=rest - action=deploy - filter=all - SEQUENTIAL" fabric="glu-dev-1"
      systemId="4836742aa34f6915fae3c0f46fbcc86ea381df74" savedTime="1302892719254">
  <sequential origin="rest" action="deploy" filter="all">
    <sequential agent="agent-1" mountPoint="/sample/i001">
      <leaf name="Start agent-1:/sample/i001 on agent-1" />
    </sequential>
    <sequential agent="agent-1" mountPoint="/sample/i003">
      <leaf name="Install script for installation agent-1:/sample/i003 on agent-1" />
      <leaf name="Install agent-1:/sample/i003 on agent-1" />
      <leaf name="Configure agent-1:/sample/i003 on agent-1" />
      <leaf name="Start agent-1:/sample/i003 on agent-1" />
    </sequential>
  </sequential>
</plan>

And the command (-p means parallel):

./bin/console-cli.sh -f glu-dev-1 -u admin -x admin -a -n -p deploy

will produce the following output (parallel):

<?xml version="1.0"?>
<plan name="origin=rest - action=deploy - filter=all - PARALLEL" fabric="glu-dev-1"
      systemId="4836742aa34f6915fae3c0f46fbcc86ea381df74" savedTime="1302892859008">
  <parallel origin="rest" action="deploy" filter="all">
    <sequential agent="agent-1" mountPoint="/sample/i001">
      <leaf name="Start agent-1:/sample/i001 on agent-1" />
    </sequential>
    <sequential agent="agent-1" mountPoint="/sample/i003">
      <leaf name="Install script for installation agent-1:/sample/i003 on agent-1" />
      <leaf name="Install agent-1:/sample/i003 on agent-1" />
      <leaf name="Configure agent-1:/sample/i003 on agent-1" />
      <leaf name="Start agent-1:/sample/i003 on agent-1" />
    </sequential>
  </parallel>
</plan>

Note

The -n option means dry-run and it allows you to display the deployment plan instead of executing it!

Deployer¶

The deployer is responsible to execute the deployment plan computed by the planner. The deployer knows how to deploy arbitrarily complex deployment plans (sequential / parallel nested at any level) and reports its progress as it goes along, allowing the very dynamic view available in the console:

Note

as you can see on the screenshot, every running action can be cancelled in the event there is a need for it.

Note

the command line is also using the reporting capabilities of the deployer to display a progress bar:

REST api¶

The orchestration engine offers a REST api (served by the console webapp).

Note

You do not have to use the REST api directly: there is a convenient command line interface (cli) which is already using it. You would use the REST api directly, in cases when the cli is not enough or you want to have more control for example.

Security / Authorization¶

The security model is simply implementing http basic authorization: every request needs to come with an Authorization header with the following format:

Authorization: Basic <base64(username:password)>

Note

The username and password are only slightly obfuscated (base 64) but it is not an issue because the cli talks to the console over https and as a result the headers are never traveling over an insecure channel.

Tip

You can change the way authentication and authorization are handled entirely by writing your own plugin!

A few concepts¶

You may wonder what is the difference between the 3 notions exposed by the REST API: plans, current deployments and archived deployments.

A plan (as exposed by the /plans* APIs) simply represents a list of instructions that glu will execute. If you use the console, you can get a good idea of what a plan looks like:

Currently a plan only lives (for a short time) in memory, between the time it gets created (POST /plans) and the time it gets executed. There is no persistent storage.

Note

this may change in the future as it would be convenient to create a plan just once and execute it at a later time or repeatedly.
Once the plan is created and you execute it (POST /plan/<planId>/execution), it becomes a deployment and 2 things happen:
1. a memory representation of the deployment is created: the current deployment
2. a database entry is created for this deployment: the archived deployment
The current deployment lives in memory because it is used by the orchestration engine to execute the steps that needs to happen. It is dynamically updated as steps complete. The current deployment will remain in memory (even after it completes) until either you shutdown the console (so the memory is gone...) or you archive it. The current deployment contains more details than the archived one and can be seen in the console when clicking on the Plans tab.
The archived deployment is created (in the database) when the plan starts executing and then it is updated again only when the current deployment completes (whether it was successful or not). The archived deployment is permanent (because it is stored in the database) and can be seen in the console when clicking on the Plans/Archived tab.

Tip

There is a relationship between a plan execution and the current and archived plan: the executionId is in fact the deploymentId:

GET /plans/<planId>/executions/<executionId>

is equivalent to

GET /deployment/current/<executionId>

and if you want to access the archived version you can issue

GET /deployment/archived/<executionId>

Warning

Currently, the /plans* APIs are only dealing with the plans that have been created through the REST API. The plans created and executed from the web interface use a different mechanism and won’t appear in those calls. This will be adressed in an upcoming release. The /deployments* calls work whether the REST API or the web interface was used.

API¶

Main URI: /console/rest/v1/<fabric> (all the URIs in the following table start with the main URI)

Method	URI	Description	Details
`GET`	None	Returns details for fabric	view
`PUT`	None	Add/Update a fabric	view
`DELETE`	None	Delete a fabric	view
`HEAD`	`/agents`	Returns the number of agents	view
`GET`	`/agents`	List all the agents	view
`GET`	`/agent/<agentName>`	View details about the agent	view
`DELETE`	`/agent/<agentName>`	Remove all knowledge of an agent	view
`PUT`	`/agent/<agentName>/fabric`	Sets the fabric for the agent	view
`DELETE`	`/agent/<agentName>/fabric`	Clears the fabric for the agent	view
`GET`	`/agents/versions`	List all the agents versions	view
`POST`	`/agents/versions`	Upgrade the agents	view
`GET`	`/plans`	List all the plans	view
`POST`	`/plans`	Create a plan	view
`GET`	`/plan/<planId>`	View the plan (as an xml document)	view
`POST`	`/plan/<planId>/execution`	Executes the plan	view
`GET`	`/plan/<planId>/executions`	List all the executions for a plan	view
`HEAD`	`/plan/<planId>/execution/<executionId>`	Returns the status of the execution	view
`GET`	`/plan/<planId>/execution/<executionId>`	Returns the execution as an xml document	view
`DELETE`	`/plan/<planId>/execution/<executionId>`	Aborts the execution	view
`GET`	`/deployments/current`	List all current deployments	view
`DELETE`	`/deployments/current`	Archive all current deployments	view
`GET`	`/deployment/current/<deploymentId>`	View details about the current deployment	view
`HEAD`	`/deployment/current/<deploymentId>`	View info only about the current deployment	view
`DELETE`	`/deployment/current/<deploymentId>`	Archive the current deployment	view
`HEAD`	`/deployments/archived`	Returns the total count of archived deployments	view
`GET`	`/deployments/archived`	List the archived deployments (paginated!)	view
`HEAD`	`/deployment/archived/<deploymentId>`	View info about the archived deployment	view
`GET`	`/deployment/archived/<deploymentId>`	View details about the archived deployment	view
`POST`	`/model/static`	Loads the (desired) model in the console / Set as current	view
`GET`	`/model/static`	Retrieves the current loaded model (aka ‘desired’ state)	view
`GET`	`/model/static/<modelId>`	Retrieves the model given its id	view
`HEAD`	`/models/static`	Return the total count of static models	view
`GET`	`/models/static`	Retrieve a (paginated) list of previously loaded static models	view
`GET`	`/model/live`	Retrieves the current live model coming from ZooKeeper (aka current state)	view
`GET`	`/model/delta`	Retrieves the delta between static model and live model	view
`POST`	`/agent/<agentName>/commands`	Executes a shell command	view
`GET`	`/command/<commandId>/streams`	Retrieves the streams (=result) of the command execution	view

Any fabric related URI: /console/rest/v1/- (all the URIs in the following table start with this URI)

Method	URI	Description	Details
`GET`	`/`	Returns the list of fabrics	view
`GET`	`/agents`	Returns the map of associations agent -> fabric	view
`HEAD`	`/audit/logs`	Returns the count of audit logs	view
`GET`	`/audit/logs`	Returns the list of audit logs (paginated!)	view

Fabric details¶

Description: Retrieve the details about the fabric
Request: GET

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
- body: json map with the details of the fabric
- 404 (NOT FOUND) when there is no such fabric

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1?prettyPrint=true"
< HTTP/1.1 200 OK
{
  "color": "#005a87",
  "name": "glu-dev-1",
  "zkConnectString": "localhost:2181",
  "zkSessionTimeout": "30s"
}

Add/Update a fabric¶

Description: Add (or update if already exists) a fabric
Request: PUT

request parameters:
- zkConnectString=localhost:2181 the connection string to your ZooKeeper setup
- zkSessionTimeout=30s the timeout for ZooKeeper sessions
- color=%23ff00ff the color (for the ui top navigation bar), can be anything that is useable as a color in css (ex of valid input: red, #ff00ff (which must be properly query string encoded => # gets encoded into %23))
Response:
- 200 (OK) when the update was successful
- 400 (BAD REQUEST) when the parameters are not valid (body will contain details about the error)

Example:

curl -v -u "glua:password" -X PUT "http://localhost:8080/console/rest/v1/glu-dev-3?zkConnectString=localhost:2181&zkSessionTimeout=30s&color=%23ff00ff"
> PUT /console/rest/v1/glu-dev-3?zkConnectString=localhost:2181&zkSessionTimeout=30s&color=%23ff00ff HTTP/1.1
< HTTP/1.1 200 OK

Delete a fabric¶

Description: Delete a fabric
Request: DELETE
Response:
- 200 (OK) when the delete was successful
- 404 (NOT FOUND) when the fabric was already deleted

Example:

curl -v -u "glua:password" -X DELETE "http://localhost:8080/console/rest/v1/glu-dev-3"
> DELETE /console/rest/v1/glu-dev-3 HTTP/1.1
< HTTP/1.1 200 OK

Agents count¶

Description: Returns the number of agents (in the fabric specified in the URL)
Request: HEAD /agents
Response:
- 200 (OK) with:
  - headers: X-glu-count with the number of agents
- 204 (NO CONTENT) when there is no agent

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/agents" --head
< HTTP/1.1 200 OK
< X-glu-count: 4

List all the agents¶

Description: List all the agents
Request: GET /agents

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-count with the number of agents
  - body: json map where key is agent name and value is another map with all the agents properties (as can be seen in the console when looking at an individual agent and clicking View Details).
- 204 (NO CONTENT) when there is no agent

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/agents?prettyPrint=true"
< HTTP/1.1 200 OK
< X-glu-count: 4
{
  "agent-1": {
    "glu.agent.apps": "/export/content/glu/devsetup/apps/agent-1",
    "glu.agent.configURL": "zookeeper:/org/glu/agents/fabrics/glu-dev-1/config/config.properties",
    "glu.agent.dataDir": "/export/content/glu/devsetup/agent-1/data",
    "glu.agent.fabric": "glu-dev-1",
    ...
    "viewURL": "http://localhost:8080/console/rest/v1/glu-dev-1/agent/agent-1"
  },
  "agent-10": {
    ...
    "viewURL": "http://localhost:8080/console/rest/v1/glu-dev-1/agent/agent-10"
  },
  ...
}

View agent details¶

Description: View the details of a single agent
Request: GET /agent/<agentName>

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
- body: json map with a single key details containing another map with all the agents properties (as can be seen in the console when looking at an individual agent and clicking View Details). .. note:: In an upcoming release there will be other keys in the map to represent also the entries deployed on the agent (as can be seen in the console when looking at an individual agent)
- 404 (NOT FOUND) when there is no such agent

Example:

 curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/agent/agent-1?prettyPrint=true"
 < HTTP/1.1 200 OK
 {"details": {
   "glu.agent.apps": "/export/content/glu/devsetup/apps/agent-1",
   "glu.agent.configURL": "zookeeper:/org/glu/agents/fabrics/glu-dev-1/config/config.properties",
   "glu.agent.dataDir": "/export/content/glu/devsetup/agent-1/data",
   "glu.agent.fabric": "glu-dev-1",
   "glu.agent.homeDir": "/export/content/glu/devsetup/agent-1",
   "glu.agent.hostname": "192.168.0.150",
   "glu.agent.hostnameFactory": ":ip",
   "glu.agent.keystoreChecksum": "JSHZAn5IQfBVp1sy0PgA36fT_fD",
   "glu.agent.keystorePath": "zookeeper:/org/glu/agents/fabrics/glu-dev-1/config/agent.keystore",
   "glu.agent.logDir": "/export/content/glu/devsetup/agent-1/data/logs",
   "glu.agent.name": "agent-1",
   "glu.agent.persistent.properties": "/export/content/glu/devsetup/agent-1/data/config/agent.properties",
   "glu.agent.pid": "4641",
   "glu.agent.port": "13906",
   "glu.agent.rest.nonSecure.port": "12907",
   "glu.agent.rest.server.defaultThreads": "3",
   "glu.agent.scriptRootDir": "/export/content/glu/devsetup/apps/agent-1",
   "glu.agent.scriptStateDir": "/export/content/glu/devsetup/agent-1/data/scripts/state",
   "glu.agent.sslEnabled": "true",
   "glu.agent.tempDir": "/export/content/glu/devsetup/agent-1/data/tmp",
   "glu.agent.truststoreChecksum": "qUFMIePiJhz8i7Ow9lZmN5pyZjl",
   "glu.agent.truststorePath": "zookeeper:/org/glu/agents/fabrics/glu-dev-1/config/console.truststore",
   "glu.agent.version": "3.2.0-SNAPSHOT",
   "glu.agent.zkConnectString": "localhost:2181",
   "glu.agent.zkProperties": "/export/content/glu/devsetup/agent-1/data/config/zk.properties",
   "glu.agent.zkSessionTimeout": "5s",
   "glu.agent.zookeeper.root": "/org/glu"
}}

Remove all knowledge of an agent¶

Description: This call should be used in the scenario when you want to decommission a node: all data stored in ZooKeeper in regards to this agent will be wiped out.
Request: DELETE /agent/<agentName>
Response:
- 200 (OK) if the agent was succesfully cleaned
- 404 (NOT FOUND) if the agent did not exist in the first place
- 409 (CONFLICT) if the agent is still up and running!

Example:

curl -v -u "glua:password" -X DELETE "http://localhost:8080/console/rest/v1/glu-dev-1/agent/agent-1"
> DELETE /console/rest/v1/glu-dev-1/agent/agent-1 HTTP/1.1
< HTTP/1.1 200 OK

Assign a fabric to an agent¶

Description: Assigns a fabric to an agent (and optionally configures it)
Request: PUT /agent/<agentName>/fabric

optional request parameters:
- host=<ip or hostname> for configuring the agent using the ip or the hostname of the agent (this assumes that the configuration port is 12907)
- uri=<configuration uri> for configuring the agent using the given uri (this form allows you to use a different port (ex: http://x.x.x.x:13906/config))
Response:
- 200 (OK)
- 400 (BAD REQUEST) if missing or unknown fabric
- 409 (CONFLICT) when the configuration phase failed

Example:

curl -v -u "glua:password" -X PUT "http://localhost:8080/console/rest/v1/glu-dev-1/agent/xeon/fabric?host=127.0.0.1"
< HTTP/1.1 200 OK

Tip

“Configuring” the agent means that the orchestration engine will issue a REST call to the agent with its own ZooKeeper connect string as configuration. This allows the use case where the agent is started without a ZooKeeper at all, so the agent is simply waiting for somebody to tell it where is his ZooKeeper. This is what you see in the agent log:

Waiting for glu.agent.zkConnectString (rest:put:http://xeon.local:12907)

Clears the fabric for an agent¶

Description: Simply clears the fabric previously associated to an agent
Request: DELETE /agent/<agentName>/fabric
Response:
- 200 (OK) if it worked
- 404 (NOT FOUND) if there was already no fabric
- 400 (BAD REQUEST) if missing or unknown fabric

Example:

curl -v -u "glua:password" -X DELETE "http://localhost:8080/console/rest/v1/glu-dev-1/agent/xeon/fabric"
< HTTP/1.1 200 OK

List all the agents versions¶

Description: List all the agents versions
Request: GET /agents/versions

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-count with the number of agents
  - body: json map where key is agent name and value is the agent version
- 204 (NO CONTENT) when there is no agent

Example:

 curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/agents/versions?prettyPrint=true"
 < HTTP/1.1 200 OK
 < X-glu-count: 4
 {
   "agent-1": "3.2.0",
   "agent-10": "3.1.0",
   "agent-4": "3.2.0",
   "agent-7": "3.2.0"
}

Upgrade the agents¶

Description: Create a plan to upgrade the agents. You must then execute the plan as described in Executing a plan
Request: POST /agents/versions

The post content type should be application/x-www-form-urlencoded

The body of the post should be a well formed query string containing the following parameters:

version: the version of the new agent

coordinates: the url of the agent upgrade tarball

agents: 1 per agent name you want to upgrade

Response:
- 201 (Created) with:
  - headers: Location containing the url to POST to in order to execute the plan (see Executing a plan)
- 204 (NO CONTENT) when there is nothing to do
- 400 (BAD REQUEST) when missing version or coordinates

Example:

# 1. create the upgrade plan
curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/agents/versions" --data "agents=agent-1&agents=agent-4&version=3.1.0&coordinates=https://github.com/downloads/linkedin/glu/org.linkedin.glu.agent-server-upgrade-3.1.0.tgz"
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 201 Created
< Location: http://localhost:8080/console/rest/v1/glu-dev-1/plan/49e69ef4-7c84-4f9b-9838-fce131b69028

# 2. view the upgrade plan. You can then execute it...
curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/plan/49e69ef4-7c84-4f9b-9838-fce131b69028?prettyPrint=true"
<?xml version="1.0"?>
<plan fabric="glu-dev-1" id="49e69ef4-7c84-4f9b-9838-fce131b69028" origin="rest" action="upgradeAgents" version="3.1.0" name="origin=rest - action=upgradeAgents - version=3.1.0 - PARALLEL" savedTime="1312126425812">
  <parallel origin="rest" action="upgradeAgents" version="3.1.0">
    <sequential agent="agent-1" mountPoint="/self/upgrade">
      <leaf agent="agent-1" fabric="glu-dev-1" initParameters="{agentTar=https://github.com/downloads/linkedin/glu/org.linkedin.glu.agent-server-upgrade-3.1.0.tgz, newVersion=3.1.0}" mountPoint="/self/upgrade" name="Install script for [/self/upgrade] on [agent-1]" script="{scriptClassName=org.linkedin.glu.agent.impl.script.AutoUpgradeScript}" scriptLifecycle="installScript" />
      <leaf agent="agent-1" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [install] phase for [/self/upgrade] on [agent-1]" scriptAction="install" toState="installed" />
      <leaf agent="agent-1" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [prepare] phase for [/self/upgrade] on [agent-1]" scriptAction="prepare" toState="prepared" />
      <leaf agent="agent-1" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [commit] phase for [/self/upgrade] on [agent-1]" scriptAction="commit" toState="upgraded" />
      <leaf agent="agent-1" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [uninstall] phase for [/self/upgrade] on [agent-1]" scriptAction="uninstall" toState="NONE" />
      <leaf agent="agent-1" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Uninstall script for [/self/upgrade] on [agent-1]" scriptLifecycle="uninstallScript" />
    </sequential>
    <sequential agent="agent-4" mountPoint="/self/upgrade">
      <leaf agent="agent-4" fabric="glu-dev-1" initParameters="{agentTar=https://github.com/downloads/linkedin/glu/org.linkedin.glu.agent-server-upgrade-3.1.0.tgz, newVersion=3.1.0}" mountPoint="/self/upgrade" name="Install script for [/self/upgrade] on [agent-4]" script="{scriptClassName=org.linkedin.glu.agent.impl.script.AutoUpgradeScript}" scriptLifecycle="installScript" />
      <leaf agent="agent-4" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [install] phase for [/self/upgrade] on [agent-4]" scriptAction="install" toState="installed" />
      <leaf agent="agent-4" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [prepare] phase for [/self/upgrade] on [agent-4]" scriptAction="prepare" toState="prepared" />
      <leaf agent="agent-4" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [commit] phase for [/self/upgrade] on [agent-4]" scriptAction="commit" toState="upgraded" />
      <leaf agent="agent-4" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Run [uninstall] phase for [/self/upgrade] on [agent-4]" scriptAction="uninstall" toState="NONE" />
      <leaf agent="agent-4" fabric="glu-dev-1" mountPoint="/self/upgrade" name="Uninstall script for [/self/upgrade] on [agent-4]" scriptLifecycle="uninstallScript" />
    </sequential>
  </parallel>
</plan>

List all the plans¶

Description: List all the plans (that have been created through POST /plans).
Request: GET /plans

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-count => number of plans
  - body: json map where key is plan id and value is a link to view it
- 204 (NO CONTENT) when there is no plan to list

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/plans?prettyPrint=true"
< HTTP/1.1 200 OK
< X-glu-count: 2
< Content-Type: text/json
< Content-Length: 262
{
  "03714d11-7b44-4717-b426-85d4cbf6c5d4": "http://localhost:8080/console/rest/v1/glu-dev-1/plan/03714d11-7b44-4717-b426-85d4cbf6c5d4",
  "b553f8de-62bc-4000-9c43-2fe869bdb3c4": "http://localhost:8080/console/rest/v1/glu-dev-1/plan/b553f8de-62bc-4000-9c43-2fe869bdb3c4"
}

Create deployment plan¶

Description: Create a plan.
Request: POST /plans
- view details below for the content of body of the POST
Response:
- 201 (CREATED) with Location header to access the plan (/plan/<planId>)
- 204 (NO CONTENT) when no plan created because there is nothing to do

Example:

curl -v -u "glua:password" --data "state=stopped&planType=transition" http://localhost:8080/console/rest/v1/glu-dev-1/plans
> POST /console/rest/v1/glu-dev-1/plans HTTP/1.1
> Authorization: Basic Z2x1YTpwYXNzd29yZA==
> Content-Length: 33
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 201 Created
< Location: http://localhost:8080/console/rest/v1/glu-dev-1/plan/8283e25e-f68d-4bbd-8a71-5149f23466ec

View a deployment plan¶

Description: View the plan (as an xml document)
Request: GET /plan
- N/A
Response:
- 200 (OK) with an xml representation of the plan
- 404 (NOT_FOUND) if no such plan

Execute a deployment plan¶

Description: Execute the plan.
Request: POST /plan/<planId>/execution
- N/A
Response:
- 201 (CREATED) with Location header to access the plan execution (/plan/<planId>/ execution/<executionId>).
  
  Note
  
  it is a non blocking call and it returns right away and you can check the progress thus allowing to have a progress bar!
- 404 (NOT_FOUND) if no such plan

List all the plan executions¶

Description: List all the plan excutions. Once a plan has been created (POST /plans) it is possible to execute it multiple times. This call allows you to list all the executions of a previously created plan.
Request: GET /plan/<planId>/executions

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-count => number of executions
  - body: json map where key is execution id and value is a link to view it
- 204 (NO CONTENT) when no execution

Example:

 curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/plan/03714d11-7b44-4717-b426-85d4cbf6c5d4/executions"
 < HTTP/1.1 200 OK
 < X-glu-count: 1
 < Content-Type: text/json
 <
{"3":"http://localhost:8080/console/rest/v1/glu-dev-1/plan/03714d11-7b44-4717-b426-85d4cbf6c5d4/execution/3"}

Tip

The execution id is in fact a deployment id and can be used directly in the /deployments* APIs

Check status of plan execution¶

Description: Return the status of the execution.
Request: HEAD /plan/<planId>/execution/<executionId>
- N/A
Response:
- 200 (OK) with X-glu-completion header with value:
  1. if plan non completed, percentage completion (ex: 87)
  2. if completed: 100:<completion status> (ex: 100:FAILED or 100:COMPLETED)
- 404 (NOT_FOUND) if no such execution

View execution plan¶

Description: Return the execution as an xml document.
Request: GET /plan/<planId>/execution/<executionId>
- N/A
Response:
- 200 (OK) with an xml representation of the execution (equivalent to the view in the console)
- 404 (NOT_FOUND) if no such execution

Abort execution plan¶

Description: Abort the execution.
Request: DELETE /plan/<planId>/execution/<executionId>
- N/A
Response:
- 200 (OK) if the execution was aborted
- 204 (NO_CONTENT) if the execution was already completed
- 404 (NOT_FOUND) if no such execution

List all current deployments¶

Description: List all current deployments.
Request: GET /deployments/current

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-count => number of current deployments
  - body: json map where key is deployment id and value is another map with some details about the deployment (equivalent to what you see on the Plans tab in the console)
- 204 (NO CONTENT) when there is no deployment to list

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployments/current?prettyPrint=true"
< HTTP/1.1 200 OK
< X-glu-count: 4
< Content-Type: text/json
{
  "1": {
    "completedSteps": 16,
    "description": "Deploy - Fabric [glu-dev-1] - PARALLEL",
    "endTime": 1312038165459,
    "startTime": 1312038160946,
    "status": "COMPLETED",
    "totalSteps": 16,
    "username": "glua",
    "viewURL": "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/current/1"
  },
  ...
}

Archive all current deployments¶

Description: Archive all current deployments.
Request: DELETE /deployments/current
Response:
- 200 (OK) with:
  - headers: X-glu-archived => number of deployments that were archived

Example:

curl -v -X DELETE -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployments/current"
< HTTP/1.1 200 OK
< X-glu-archived: 3

View current deployment (details)¶

Description: View the current deployment details
Request: GET /deployment/current/<deploymentId>

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-startTime, X-glu-endTime, X-glu-username, X-glu-status, X-glu-description, X-glu-completedSteps, X-glu-totalSteps
  - body: xml representation of the plan showing the details
- 404 (NOT FOUND) when there is no such deployment

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/current/1?prettyPrint=true"
< HTTP/1.1 200 OK
< X-glu-startTime: 1312038160946
< X-glu-endTime: 1312038165459
< X-glu-username: glua
< X-glu-status: COMPLETED
< X-glu-description: Deploy - Fabric [glu-dev-1] - PARALLEL
< X-glu-completedSteps: 16
< X-glu-totalSteps: 16
< Content-Type: text/xml
<
<?xml version="1.0"?>
<plan fabric="glu-dev-1" systemId="47d37bb288b3908f2f3fe5d8b382053e7b13719b" id="f84e4f59-476d-4c17-bf3d-534b975cebf1" name="Deploy - Fabric [glu-dev-1] - PARALLEL">
  <parallel name="Deploy - Fabric [glu-dev-1] - PARALLEL">
    <sequential agent="agent-1" mountPoint="/m1/i001">
  ...
</plan>

View current deployment (info)¶

Description: View the current deployment info (just the headers).
Request: HEAD /deployment/current/<deploymentId>
Response:
- 200 (OK) with:
  - headers: X-glu-startTime, X-glu-endTime, X-glu-username, X-glu-status, X-glu-description, X-glu-completedSteps, X-glu-totalSteps
- 404 (NOT FOUND) when there is no such deployment

Example:

curl -v --head -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/current/1"
< HTTP/1.1 200 OK
< X-glu-startTime: 1312038160946
< X-glu-endTime: 1312038165459
< X-glu-username: glua
< X-glu-status: COMPLETED
< X-glu-description: Deploy - Fabric [glu-dev-1] - PARALLEL
< X-glu-completedSteps: 16
< X-glu-totalSteps: 16

Archive current deployment¶

Description: Archive a single current deployment.
Request: DELETE /deployment/current/<deploymentId>
Response:
- 200 (OK) with:
  - headers: X-glu-archived => true if the deployment was archived, false if already archived

Example:

curl -v -X DELETE -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/current/1"
< HTTP/1.1 200 OK
< X-glu-archived: true

Archived deployments count¶

Description: Return the total count of archived deployments.
Request: HEAD /deployments/archived
Response:
- 200 (OK) with:
  - headers: X-glu-totalCount

Example:

curl -v --head -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployments/archived"
< HTTP/1.1 200 OK
< X-glu-totalCount: 4

List archived deployments (paginated)¶

Description: List archived deployments according to the parameters provided to determine which page to return.
Request: GET /deployments/archived

optional request parameters:
- prettyPrint=true for human readable output
- max=xxx how many entries to return max (max cannot exceed a limit which defaults to 25 which is also the value used if not provided)
- offset=xxx which entry to start (default is 0)
  
  Note
  
  offset represents the index in the list (not a deployment id!). To go from page to page, the offset simply increments by max. Example with max=10, offset=0 will return page 1, offset=10 will return page 2, etc...
- sort which column to sort on (default is startDate)
- order which order to sort the list (default is desc)
Response:
- 200 (OK) with:
  - headers: X-glu-max, X-glu-offset, X-glu-sort, X-glu-order, which are the values provided/defaulted/adjusted from the request and X-glu-count which is the number of entries returned and X-glu-totalCount which is the total number of archived deployments
  - body: json map where key is deployment id and value is another map with some details about the deployment (equivalent to what you see on the Plans/Archived tab in the console)
- 204 (NO CONTENT) when there is no deployment to list

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployments/archived?prettyPrint=true&max=2"
< HTTP/1.1 200 OK
< X-glu-count: 2
< X-glu-totalCount: 4
< X-glu-max: 2
< X-glu-offset: 0
< X-glu-sort: startDate
< X-glu-order: desc
< Content-Type: text/json
{
  "3": {
    "description": "origin=rest - action=bounce - filter=all - SEQUENTIAL",
    "endTime": 1312039222813,
    "startTime": 1312039220934,
    "status": "COMPLETED",
    "username": "glua",
    "viewURL": "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/archived/3"
  },
  "4": {
    "description": "origin=rest - action=bounce - filter=all - PARALLEL",
    "endTime": 1312039238723,
    "startTime": 1312039237598,
    "status": "COMPLETED",
    "username": "glua",
    "viewURL": "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/archived/4"
  }
}

View archived deployment (details)¶

Description: View the archived deployment details
Request: GET /deployment/archived/<deploymentId>

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-startTime, X-glu-endTime, X-glu-username, X-glu-status, X-glu-description
  - body: xml representation of the plan showing the details
- 404 (NOT FOUND) when there is no such deployment

Example:

 curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/archived/1?prettyPrint=true"
 < HTTP/1.1 200 OK
 < X-glu-startTime: 1312038160946
 < X-glu-endTime: 1312038165459
 < X-glu-username: glua
 < X-glu-status: COMPLETED
 < X-glu-description: Deploy - Fabric [glu-dev-1] - PARALLEL
< Content-Type: text/xml
 <
 <?xml version="1.0"?>
 <plan fabric="glu-dev-1" systemId="47d37bb288b3908f2f3fe5d8b382053e7b13719b" id="f84e4f59-476d-4c17-bf3d-534b975cebf1" name="Deploy - Fabric [glu-dev-1] - PARALLEL">
   <parallel name="Deploy - Fabric [glu-dev-1] - PARALLEL">
     <sequential agent="agent-1" mountPoint="/m1/i001">
   ...
 </plan>

View archived deployment (info)¶

Description: View the archived deployment info (just the headers).
Request: HEAD /deployment/archived/<deploymentId>
Response:
- 200 (OK) with:
  - headers: X-glu-startTime, X-glu-endTime, X-glu-username, X-glu-status, X-glu-description
- 404 (NOT FOUND) when there is no such deployment

Example:

curl -v --head -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/deployment/archived/1"
< HTTP/1.1 200 OK
< X-glu-startTime: 1312038160946
< X-glu-endTime: 1312038165459
< X-glu-username: glua
< X-glu-status: COMPLETED
< X-glu-description: Deploy - Fabric [glu-dev-1] - PARALLEL

Load static model / Set as current¶

Description: Load the (desired) model in the console or set a previously loaded one as current
Request: POST /model/static

Body can be of 3 types depending on the Content-Type header:
1. application/x-www-form-urlencoded with body containing modelUrl=xxx where the url is pointing to the model (the console will ‘download’ it)
2. application/x-www-form-urlencoded with body containing id=xxx where id is the model id to set as current
3. text/json or text/json+groovy then body should be the model itself (example)
Response:
- 200 (OK) when model is successfully set as current
- 201 (CREATED) when loaded successfully
- 204 (NO_CONTENT) if model was loaded successfully and is equal to the previous one
- 400 (BAD_REQUEST) if the model is not valid (should be a properly json formatted document)
- 404 (NOT_FOUND) when error (note error handling needs to be revisited)

Example:

# 1. using modelUrl
curl -v -u "glua:password" --data "modelUrl=file%3A%2FUsers%2Fypujante%2Fgithub%2Forg.pongasoft%2Fglu%2Fconsole%2Forg.linkedin.glu.console-server%2Fsrc%2Fcmdline%2Fresources%2Fglu%2Frepository%2Fsystems%2Fhello-world-system.json" http://localhost:8080/console/rest/v1/glu-dev-1/model/static
> POST /console/rest/v1/glu-dev-1/model/static HTTP/1.1
> Content-Type: application/x-www-form-urlencoded
> ...
>
< HTTP/1.1 201 Created
< ...
id=facc4ef65539a5c558436f034b5e63e5ba1fd0ef

# 2. using id (set as current)
curl -v -u "glua:password" --data "id=34879db4fbe0afed9755e70bb2a392a3a93938fd" http://localhost:8080/console/rest/v1/glu-dev-1/model/static
> POST /console/rest/v1/glu-dev-1/model/static HTTP/1.1
> Content-Type: application/x-www-form-urlencoded
> ...
>
< HTTP/1.1 200 OK
< ...

# 3. using input stream
curl -v -u "glua:password" -H "Content-Type: text/json" --data-binary @/Users/ypujante/github/org.pongasoft/glu/console/org.linkedin.glu.console-server/src/cmdline/resources/glu/repository/systems/hello-world-system.json http://localhost:8080/console/rest/v1/glu-dev-1/model/static
> POST /console/rest/v1/glu-dev-1/model/static HTTP/1.1
> Content-Type: text/json
> ...
>
< HTTP/1.1 201 Created
< ...
id=facc4ef65539a5c558436f034b5e63e5ba1fd0ef

View static model¶

Description: Retrieve the current loaded model (aka expected state) if no id specified, otherwise the specified model.

Note

this is what you loaded using POST /model/static
Request: GET /model/static for the current loaded model or GET /model/static/<id> for a specific model

optional request parameters:
- prettyPrint=true for human readable output
- systemFilter=... for filtering (see Filter syntax for the syntax)
Response:
- 200 (OK) with a json representation of the model
  - headers: X-glu-timeCreated, X-glu-createdBy and if the model requested is the current one, X-glu-timeSetAsCurrent, X-glu-setAsCurrentBy
- 404 (NOT_FOUND) if the id does not match a previously loaded model

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/model/static?prettyPrint=true"
< HTTP/1.1 200 OK
< Etag: 11c1038e9cea43b6bf59276de8063db09d5fa496
< X-glu-timeCreated: 1429050416211
< X-glu-createdBy: <bootstrap>
< X-glu-timeSetAsCurrent: 1429053507297
< X-glu-setAsCurrentBy: glur
<
{
  "fabric": "glu-dev-1",
  "id": "7328fb4bdffcac106a189f38416fb03502aca68f",
  "metadata": {
    "name": "Empty System Model"
  }
}

Static models count¶

Description: Return the total count of static models.
Request: HEAD /models/static
Response:
- 200 (OK) with:
  - headers: X-glu-totalCount and X-glu-current which contains the id of the currently selected model

Example:

curl --head -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/models/static"
< HTTP/1.1 200 OK
< X-glu-current: 34879db4fbe0afed9755e70bb2a392a3a93638fd
< X-glu-totalCount: 5

List static models¶

Description: Retrieve a (paginated) list of previously loaded static models
Request: GET /models/static

optional request parameters:
- prettyPrint=true for human readable output
- max=xxx how many entries to return max (max cannot exceed a limit which defaults to 10 which is also the value used if not provided)
- offset=xxx which entry to start (default is 0)
  
  Note
  
  offset represents the index in the list (not a model id!). To go from page to page, the offset simply increments by max. Example with max=10, offset=0 will return page 1, offset=10 will return page 2, etc...
- sort which column to sort on (default is timeCreated)
- order which order to sort the list (default is desc)
Response:
- 200 (OK) with:
  - headers: X-glu-max, X-glu-offset, X-glu-sort, X-glu-order, which are the values provided/defaulted/adjusted from the request and X-glu-count which is the number of entries returned and X-glu-totalCount which is the total number of models. X-glu-current contains the id of the currently selected model (which may not be on the page returned).
  - body: json array of maps with some details about each model (equivalent to what you see on the Model/List tab in the console)

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/models/static?prettyPrint=true&max=2"
< HTTP/1.1 200 OK
< X-glu-current: 34879db4fbe0afed9755e70bb2a392a3a93638fd
< X-glu-count: 2
< X-glu-totalCount: 5
< X-glu-max: 2
< X-glu-offset: 0
< X-glu-sort: timeCreated
< X-glu-order: desc
< Content-Type: text/json;charset=ISO-8859-1
< Content-Length: 582
<
[
  {
    "fabric": "glu-dev-1",
    "id": "c036278ff0a47f5bbe9a695809af1515855a686a",
    "name": "Empty System Model 5",
    "setAsCurrentBy": "glur",
    "size": 113,
    "timeCreated": 1409167185742,
    "timeSetAsCurrent": 1409167185742,
    "viewURL": "http://192.168.0.117:8080/console/rest/v1/glu-dev-1/model/static/c036278ff0a47f5bbe9a695809af1515855a686a"
  },
  {
    "fabric": "glu-dev-1",
    "id": "21aee08eee129f99d88e9e617ecb01415f67a74c",
    "name": "Empty System Model 4",
    "size": 113,
    "timeCreated": 1409167182596,
    "viewURL": "http://192.168.0.117:8080/console/rest/v1/glu-dev-1/model/static/21aee08eee129f99d88e9e617ecb01415f67a74c"
  }
]

View live model¶

Description: Retrieve the current live model coming from ZooKeeper (aka current state).
Request: GET /model/live

optional request parameters:
- prettyPrint=true for human readable output
- systemFilter=... for filtering (see Filter syntax for the syntax)
Response:
- 200 (OK) with a json representation of the live model
  
  Note
  
  the metadata contains information like currentState

View delta¶

Description: Retrieve the delta (similar to what can be seen on the dashboard) which is the difference between the static and live model (expected vs current)
Request: GET /model/delta

optional request parameters:
- prettyPrint=true for human readable output
- systemFilter=... for filtering (see Filter syntax for the syntax)
- errorsOnly=true filter to show only errors
- flatten=true flatten the output (similar to dashboard view)
Response:
- 200 (OK) with a json representation of the delta

List all the fabrics¶

Description: List all the fabrics
Request: GET /

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-count with the number of fabrics
  - body: json array of fabric names

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/-?prettyPrint=true"
< HTTP/1.1 200 OK
< X-glu-count: 2
< Content-Type: text/json
[
  "glu-dev-1",
  "glu-dev-2"
]

List all the agents fabrics¶

Description: Returns the map of association agent -> fabric
Request: GET /agents

optional request parameters:
- prettyPrint=true for human readable output
Response:
- 200 (OK) with:
  - headers: X-glu-count with the number of entries in the map
  - body: json map where the key is agent name and the value is the fabric

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/-/agents?prettyPrint=true"
< HTTP/1.1 200 OK
< X-glu-count: 2
< Content-Type: text/json
{
  "agent-1": "glu-dev-1",
  "xeon.local": "glu-dev-1"
}

Warning

This api (/rest/v1/-/agents) which returns a map of association agent -> fabric should not be mistaken with the api /rest/v1/<fabric>/agents which specifies the fabric and list all agents in a given fabric!

Execute a shell command¶

Description: Execute a shell command on the agent. Note that this call is non blocking and return right away. In order to wait for the command to complete and read the result of the command, you need to use the other api
Request: POST /agent/<agentName>/commands

required request parameters:
- command=...: the command to execute (ex: uptime)
optional request parameters:
- type=shell the type of command to run (at this moment only shell is supported)
- redirectStderr=true whether stderr should be redirected to stdout (default to false)
optional input stream: if you want to provide stdin to your command, simply put it in the body of the post
Response:
- 201 (Created) with:
  - headers: X-glu-command-id the id of the command created
  - body: json map containing the same id
- 404 (Not found) if no such agent

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/agent/agent-1/commands?command=cat%20-" -H "Content-Type: application/octet-stream" --data-binary 'abcdef'
> POST /console/rest/v1/glu-dev-1/agent/agent-1/commands?command=cat%20- HTTP/1.1
> ...
> Content-Type: application/octet-stream
> Content-Length: 6
>
* upload completely sent off: 6 out of 6 bytes
< HTTP/1.1 201 Created
< ...
< X-glu-command-id: 13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536
< Content-Type: text/json
< Content-Length: 57
<
{"id":"13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536"}

Read/Wait for command result¶

Once a command has been started, this api will retrieve the result(s) and optionally wait. If you request more than one stream, then you will get a muliplexed stream of results (the format is fairly simple and you can take a look at the java code on how to demultiplex it. TODO: add python code for demultiplexing/example).
Request: GET /commands/<commandId>/streams

optional request parameters:
- stdoutStream=true include stdout stream (default: false)
- stdoutOffset=... where to start in stdout stream in number of bytes (negative number counts backward) (default: 0)
- stdoutLen=... how many bytes max to read for stdout (default: -1 => read all)
- stderrStream=true include stderr stream (default: false)
- stderrOffset=... where to start in stderr stream in number of bytes (negative number counts backward) (default: 0)
- stderrLen=... how many bytes max to read for stderr (default: -1 => read all)
- stdinStream=true include stdin stream (default: false)
- stdinOffset=... where to start in stdin stream in number of bytes (negative number counts backward) (default: 0)
- stdinLen=... how many bytes max to read for stdin (default: -1 => read all)
- exitValueStream=true include the exit value (which is what the shell command returned: $?) (default: false)
- exitValueStreamTimeout=... if the command is not completed yet, how long to wait (meaning block) until the result is returned (0 means wait until completed). Can be any timespan (ex: 5s, 10m, 50 for 50 milliseconds) (default: don’t wait!)
- exitErrorStream=true include the error stream (when an exception is generated for any reason, usually communication) (default: false)
Response:
- 200 (OK) with:
  - headers:
    - X-glu-command-id the id of the command
    - X-glu-command-startTime the time when the command was started
    - X-glu-command-completionTime the time when the command was completed (if completed)
  - body: the stream(s) requested
- 404 (Not found) if no such command

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/command/13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536/streams?stdoutStream=true"
> GET /console/rest/v1/glu-dev-1/command/13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536/streams?stdoutStream=true HTTP/1.1
> ...
>
< HTTP/1.1 200 OK
< X-glu-command-id: 13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536
< X-glu-command-startTime: 1353009232768
< X-glu-command-completionTime: 1353009232917
< Content-Type: application/octet-stream
< ...
<
abcdef

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/glu-dev-1/command/13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536/streams?stdoutStream=true&exitValueStream=true"
> GET /console/rest/v1/glu-dev-1/command/13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536/streams?stdoutStream=true&exitValueStream=true HTTP/1.1
> ...
>
< HTTP/1.1 200 OK
< X-glu-command-id: 13b05a27b80-d527ccf3-166a-4986-90b2-41be8c2ba536
< X-glu-command-startTime: 1353009232768
< X-glu-command-completionTime: 1353009232917
< Content-Type: application/octet-stream
< ...
<
MISV1.0=V=O

V=1
0

O=6
abcdef

Audit Logs Count¶

Description: Returns the total count of audit logs
Request: HEAD /audit/logs
Response:
- 200 (OK) with:
  - headers: X-glu-totalCount which is the total number of audit log entries.

Example:

curl -u "glua:password" "http://localhost:8080/console/rest/v1/-/audit/logs" --head
HTTP/1.1 200 OK
X-glu-totalCount: 5
...

List Audit Logs¶

Description: Returns the (paginated) list of audit logs
Request: GET /audit/logs

optional request parameters:
- prettyPrint=true for human readable output
- max=xxx how many entries to return max (default to 100)
- offset=xxx which entry to start (default is 0)
  
  Note
  
  offset represents the index in the list (not an id!). To go from page to page, the offset simply increments by max. Example with max=10, offset=0 will return page 1, offset=10 will return page 2, etc...
- sort which column to sort on (default is id)
- order which order to sort the list (default is desc)
Response:
- 200 (OK) with:
  - headers: X-glu-max, X-glu-offset, X-glu-sort, X-glu-order, which are the values provided/defaulted/adjusted from the request and X-glu-count which is the number of entries returned and X-glu-totalCount which is the total number of audit log entries.
  - body: json list of audit log entries
- 204 (NO CONTENT) when there is no audit log entries (which should not happen).

Example:

curl -v -u "glua:password" "http://localhost:8080/console/rest/v1/-/audit/logs?prettyPrint=true"
< HTTP/1.1 200 OK
< X-glu-count: 5
< X-glu-totalCount: 5
< X-glu-max: 100
< X-glu-offset: 0
< X-glu-sort: id
< X-glu-order: desc
< Content-Type: text/json;charset=ISO-8859-1
...
[
  {
    "dateCreated": 1394839512550,
    "id": 5,
    "type": "login",
    "username": "glua"
  },
  {
    "dateCreated": 1394839368174,
    "details": "fabric: glu-dev-2, systemId: 71236129b3a55f84ca8904914209f980627abf02",
    "id": 4,
    "type": "system.change",
    "username": "<bootstrap>"
  },
...

Note

This api (/rest/v1/-/audit/logs) does not reference a fabric because the audit log is not fabric dependent.

API Examples¶

Sending the model to glu in java
Python example (part of the cli)

Delta Formal Definition¶

TBD: add formal delta definition

Note

In the meantime, you may want to check this forum thread

Representing a plan¶

Query String based¶

The POST you issue must be of Content-Type application/x-www-form-urlencoded

The body then contains a query string with the following parameters:

name	value	required	example
`planAction`	`start`, `stop`, `bounce`, `deploy`, `undeploy`, `redeploy`	One of `planAction` or `planType`	`planAction=start`
`planType`	`deploy`, `undeploy`, `redeploy`, `bounce`, `transition` or anything custom	One of `planAction` or `planType`	`planType=transition&state=stopped`
`systemFilter`	a system filter as described in the previous section (remember that it must be properly url encoded.	No. It simply means don’t filter at all.	`systemFilter=and%7bagent%3d'ei2-app3-zone5.qa'%7d`
`order`	`parallel` or `sequential`	No. Default to `sequential`	`order=parallel`
`maxParallelStepsCount`	a positive integer	No.	`maxParallelStepsCount=2` defines parallel plan with no more than 2 steps in parallel

Note

planAction=stop is equivalent to planType=transition&state=stopped. The planType notation is more generic and should be used when using your own state machine or creating your own custom plan types (in which case you can also pass as many parameters as you want).

Note

maxParallelStepsCount only makes sense when order is set to parallel. Setting this value to 1 is equivalent to defining order=sequential.

Json/DSL Based¶

Coming soon

Plugins¶

The orchestration engine offers a plugin mechanism which allows you to hook into some specific phases to tweak and/or change the behavior. For example, the UserService_pre_authenticate hook allows you to bypass entirely the login/authentication mechanism that comes built-in and instead provide your own.

What is a plugin?¶

A plugin is simply a class with (groovy) closures, each of them defining a specific hook. You can define as many or as little of those closures as you want and you can spread them accross different classes (for example, you can have a plugin class handling only the deployment related plugin hooks, and another handling the hooks for a different part of the system). If a closure is missing, then it will simply not be called.

Tip

The class DocumentationPlugin is meant to be an hexaustive list of all the hooks available as well as a documentation on how to use them. It also serves as an example of how to write a plugin!

How do you install a plugin?¶

In order to install your plugins(s), you need to first package them as jar file(s). Then it is just a matter of editing the appropriate section in the meta model to let glu know where they are. For example:

consoles << [
  host: 'localhost',
  plugins: [
    [
      fqcn: 'org.acme.glu.plugin.MyPlugin',
      classPath: ['http://repository/myplugin.jar', 'http://repository/dependency.jar']
    ],
    // ... more plugins
  ],
]

fqcn is the fully qualified class name of your plugin

Note

The class of your plugin must be present in one of the jar files specified in the classPath section
classPath is a list of URIs containing the various jars comprising your plugin (base class + dependencies).

List of hooks available¶

Tip

For full documentation and typical use cases, refer to the class DocumentationPlugin.

Initialization
- PluginService_initialize: called for initializing your plugin
User management
- UserService_pre_authenticate: called before authentication
- UserService_post_authenticate: called after authentication
- UserService_pre_authorize: called before authorization
- UserService_post_authorize: called after authorization
- UserService_pre_restAuthenticateAndAuthorize: called before REST authentication and authorization flow
- UserService_post_restAuthenticateAndAuthorize: called after REST authentication and authorization flow
Model
- SystemService_pre_parseSystemModel: called before parsing the system model
- SystemService_post_parseSystemModel: called after parsing the system model
Plans
- PlannerService_pre_computePlans: called before computing a deployment plan
- PlannerService_post_computePlans: called after computing a deployment plan
Deployment
- DeploymentService_pre_executeDeploymentPlan: called before executing a deployment plan
- DeploymentService_onStart_executeDeploymentPlan: called when the deployment plan starts executing
- DeploymentService_post_executeDeploymentPlan: called after executing a deployment plan
Commands
- CommandsService_pre_executeCommand: called before executing a command
- CommandsService_post_executeCommand: called when the command is complete
- FileSystemCommandExecutionIOStorage_createInputStream: called to create the input stream to read the IO of the command from the filesystem
- FileSystemCommandExecutionIOStorage_createOutputStream:called to create the output stream to write the IO of the command from the filesystem

Future hooks¶

Now that the plugin mechanism is in place, adding new hooks is not very complicated. If you have specific requirements for a new hook, please open a ticket on the glu ticketing system.

Command Line¶

The orchestration engine also comes with a cli which is essentially a wrapper around the REST api which can be used in several ways:

directly to issue commands
to build higher level cli(s) which use this cli as a base
as an example for how to talk to the REST api directly

The cli currently requires python 2.6 to run.

Help¶

This is the output when using the -h option

Usage:

console-cli.py -f <fabric> <start|stop|bounce|deploy|undeploy|redeploy|load|status> [flags]

Note

The orchestration engine cli is currently called console-cli because of the fact that the orchestration engine is currently running inside the console.

Options:

--version¶: show program’s version number and exit

-h, --help¶: show this help message and exit

-d, --debug¶: Turn on debug output

-c CONSOLEURL, --console=CONSOLEURL¶: Url to glu Console for the given fabric.

-f FABRIC, --fabric=FABRIC¶: Perform action on a fabric

-u USER, --user=USER¶: glu user to use for authentication, defaults to $USER

-x PASSWORD, --xpassword=PASSWORD¶: Password. Warning password will appear in clear in ps output. Use only for testing.

-X PASSWORDFILE, --xpasswordfile=PASSWORDFILE¶: Read user password from passwordfile specified. Make sure to protect this file using unix permissions

-a, --all¶: Perform action on all entries

-A AGENT, --agent=AGENT¶: Perform action on one or more agent(s)

-t ALLTAGS, --allTags=ALLTAGS¶: Shortcut for querying by tags (all tags must be present): frontend;backend

-T ANYTAG, --anyTag=ANYTAG¶: Shortcut for querying by tags (any of the tags need to be present): frontend;backend

-I INSTANCE, --instance=INSTANCE¶: Perform action on one or more instance(s)

-p, --parallel¶: Perform action on all instances in parallel. Default is serial.

-n, --dryrun¶: Do a dry run of your plan. No changes will be made. Default is false.

-s FILTER, --systemFilter=FILTER¶: Filter in DSL sytax for filtering the model. Applicable only with ‘status’ command. See Filter syntax.

-S FILTERFILE, --systemFilterFile=FILTERFILE¶: Filter file with filters in DSL sytax for filtering the model. Applicable only with ‘status’ command. See Filter syntax.

-m MODEL, --model=MODEL¶: Loads the model pointed to by model (should be a url!)

-M MODELFILE, --modelFile=MODELFILE¶: Loads the model from the file

-l, --live¶: Show current model instead of expected model. Applicable only with ‘status’ command.

-b, --beautify¶: Pretty print the model.

Unless you run the cli on the same host as the console you will need to specify its location:

Example:

-c https://glu.console.host:8443/console

Here are some examples of usage:

# View the current loaded model (and format it for readability):
./bin/console-cli.py -f glu-dev-1 -u admin -x admin -b status

# View the live model only for applications in cluster cluster-1 (and format it for readability):
./bin/console-cli.py -f glu-dev-1 -u admin -x admin -b -l -s "metadata.cluster='cluster-1'" status

# Show me what will happen if I bounce all applcations in cluster cluster-1 (but don't do it!):
./bin/console-cli.py -f glu-dev-1 -u admin -x admin -s "metadata.cluster='cluster-1'" -n bounce

# Bounce all applcations in cluster cluster-1:
./bin/console-cli.py -f glu-dev-1 -u admin -x admin -s "metadata.cluster='cluster-1'" bounce

Orchestration engine¶

Key Components¶

Tracker¶

Live Model¶

From the console¶

From the command line¶

Static Model¶

Delta Service¶

Delta¶

Visualizer¶

Planner¶

Deployment Plan¶

From the Console¶

From the Command Line¶

Deployer¶

REST api¶

Security / Authorization¶

A few concepts¶

API¶

Fabric details¶

Add/Update a fabric¶

Delete a fabric¶

Agents count¶

List all the agents¶

View agent details¶

Remove all knowledge of an agent¶

Assign a fabric to an agent¶

Clears the fabric for an agent¶

List all the agents versions¶

Upgrade the agents¶

List all the plans¶

Create deployment plan¶

View a deployment plan¶

Execute a deployment plan¶

List all the plan executions¶

Check status of plan execution¶

View execution plan¶

Abort execution plan¶

List all current deployments¶

Archive all current deployments¶

View current deployment (details)¶

View current deployment (info)¶

Archive current deployment¶

Archived deployments count¶

List archived deployments (paginated)¶

View archived deployment (details)¶

View archived deployment (info)¶

Load static model / Set as current¶

View static model¶

Static models count¶

List static models¶

View live model¶

View delta¶

List all the fabrics¶

List all the agents fabrics¶

Execute a shell command¶

Read/Wait for command result¶

Audit Logs Count¶

List Audit Logs¶

API Examples¶

Delta Formal Definition¶

Representing a plan¶

Query String based¶

Json/DSL Based¶

Plugins¶

What is a plugin?¶

How do you install a plugin?¶

List of hooks available¶

Future hooks¶

Command Line¶

Help¶

Table Of Contents

Quick Links

Technologies

Twitter