diff --git a/console/org.linkedin.glu.console-webapp/grails-app/conf/UrlMappings.groovy b/console/org.linkedin.glu.console-webapp/grails-app/conf/UrlMappings.groovy index 8c0e33f4..1df3d1fe 100644 --- a/console/org.linkedin.glu.console-webapp/grails-app/conf/UrlMappings.groovy +++ b/console/org.linkedin.glu.console-webapp/grails-app/conf/UrlMappings.groovy @@ -210,7 +210,7 @@ class UrlMappings ] } - name restViewCurrentDeployment: "/rest/v1/$fabric/deployments/current/$id"(controller: 'plan') { + name restViewCurrentDeployment: "/rest/v1/$fabric/deployment/current/$id"(controller: 'plan') { action = [ HEAD: 'rest_view_current_deployment', GET: 'rest_view_current_deployment', @@ -225,7 +225,7 @@ class UrlMappings ] } - name restViewArchivedDeployment: "/rest/v1/$fabric/deployments/archived/$id"(controller: 'plan') { + name restViewArchivedDeployment: "/rest/v1/$fabric/deployment/archived/$id"(controller: 'plan') { action = [ HEAD: 'rest_view_archived_deployment', GET: 'rest_view_archived_deployment' diff --git a/console/org.linkedin.glu.console-webapp/grails-app/controllers/org/linkedin/glu/console/controllers/PlanController.groovy b/console/org.linkedin.glu.console-webapp/grails-app/controllers/org/linkedin/glu/console/controllers/PlanController.groovy index d3d7a157..588cb353 100644 --- a/console/org.linkedin.glu.console-webapp/grails-app/controllers/org/linkedin/glu/console/controllers/PlanController.groovy +++ b/console/org.linkedin.glu.console-webapp/grails-app/controllers/org/linkedin/glu/console/controllers/PlanController.groovy @@ -313,6 +313,7 @@ public class PlanController extends ControllerBase mapping: 'restPlan', id: plan.id, params: [fabric: request.fabric]).toString() } + response.addHeader("X-glu-count", map.size().toString()) render prettyPrintJsonWhenRequested(map) } else diff --git a/docs/manual/src/main/sphinx/source/orchestration-engine.rst b/docs/manual/src/main/sphinx/source/orchestration-engine.rst index a421c615..9e3ca3e2 100644 --- a/docs/manual/src/main/sphinx/source/orchestration-engine.rst +++ b/docs/manual/src/main/sphinx/source/orchestration-engine.rst @@ -112,71 +112,71 @@ The important flag is ``-l`` which request the *live* model. You get an output v "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" - } - ] + "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" + "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" + "frontend", + "osx", + "webapp" ] }], "fabric": "glu-dev-1", @@ -300,13 +300,13 @@ will produce the following output (sequential):: systemId="4836742aa34f6915fae3c0f46fbcc86ea381df74" savedTime="1302892719254"> - + - - - - + + + + @@ -322,13 +322,13 @@ will produce the following output (parallel):: systemId="4836742aa34f6915fae3c0f46fbcc86ea381df74" savedTime="1302892859008"> - + - - - - + + + + @@ -371,57 +371,390 @@ The security model is simply implementing http basic authorization: every reques .. 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. +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: + + .. image:: /images/tutorial/tutorial-select-plan-2.png + :align: center + :alt: Dashboard shows the delta + + 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//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//executions/ + + is equivalent to + + GET /deployment/current/ + + and if you want to access the archived version you can issue + + GET /deployment/archived/ + +.. 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/`` (all the URIs in the following table start with the main URI) -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|Method |URI |Description |Details | -+===========+===========================================+==================================+=====================================+ -|``GET`` |``/plans`` |List all the plans |Coming soon. | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``POST`` |``/plans`` |Create a plan |:ref:`view | -| | | |` | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``GET`` |``/plan/`` |View the plan (as an xml document)|:ref:`view ` | -| | | | | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``POST`` |``/plan//execution`` |Executes the plan |:ref:`view | -| | | |` | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``HEAD`` |``/plan//execution/`` |Returns the status of the |:ref:`view | -| | |execution |` | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``GET`` |``/plan//execution/`` |Returns the execution as an xml |:ref:`view | -| | |document |` | -| | | | | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``DELETE`` |``/plan//execution/`` |Aborts the execution |:ref:`view | -| | | |`| -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``POST`` |``/model/static`` |Loads the (desired) model in the |:ref:`view | -| | |console |` | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``GET`` |``/model/static`` |Retrieves the current loaded model|:ref:`view | -| | |(aka 'desired' state) |` | -| | | | | -| | | | | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``GET`` |``/model/live`` |Retrieves the current live model |:ref:`view | -| | |coming from ZooKeeper (aka current|` | -| | |state) | | -| | | | | -| | | | | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ -|``GET`` |``/model/delta`` |Retrieves the delta between static|:ref:`view | -| | |model and live model |` | -| | | | | -| | | | | -| | | | | -+-----------+-------------------------------------------+----------------------------------+-------------------------------------+ - - -.. _goe-rest-api-post-plan: ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|Method |URI |Description |Details | ++===========+===========================================+==================================+==========================================+ +|``HEAD`` |``/agents`` |Returns the number of agents |:ref:`view ` | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/agents`` |List all the agents |:ref:`view ` | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/agent/`` |View details about the agent |:ref:`view ` | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/agents/versions`` |List all the agents versions |:ref:`view | +| | | |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``POST`` |``/agents/versions`` |Upgrade the agents |:ref:`view | +| | | |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/plans`` |List all the plans |:ref:`view ` | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``POST`` |``/plans`` |Create a plan |:ref:`view ` | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/plan/`` |View the plan (as an xml document)|:ref:`view ` | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``POST`` |``/plan//execution`` |Executes the plan |:ref:`view | +| | | |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/plan//executions`` |List all the executions for a plan|:ref:`view | +| | | |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``HEAD`` |``/plan//execution/`` |Returns the status of the |:ref:`view | +| | |execution |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/plan//execution/`` |Returns the execution as an xml |:ref:`view | +| | |document |` | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``DELETE`` |``/plan//execution/`` |Aborts the execution |:ref:`view | +| | | |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/deployments/current`` |List all current deployments |:ref:`view | +| | | |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``DELETE`` |``/deployments/current`` |Archive all current deployments |:ref:`view | +| | | |`| ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/deployment/current/`` |View details about the current |:ref:`view | +| | |deployment |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``HEAD`` |``/deployment/current/`` |View info only about the current |:ref:`view | +| | |deployment |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``DELETE`` |``/deployment/current/`` |Archive the current deployment |:ref:`view | +| | | |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``HEAD`` |``/deployments/archived`` |Returns the total count of |:ref:`view | +| | |archived deployments |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/deployments/archived`` |List the archived deployments |:ref:`view | +| | |(paginated!) |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``HEAD`` |``/deployment/archived/`` |View info about the archived |:ref:`view | +| | |deployment |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/deployment/archived/`` |View details about the archived |:ref:`view | +| | |deployment |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``POST`` |``/model/static`` |Loads the (desired) model in the |:ref:`view | +| | |console |` | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/model/static`` |Retrieves the current loaded model|:ref:`view | +| | |(aka 'desired' state) |` | +| | | | | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/model/live`` |Retrieves the current live model |:ref:`view | +| | |coming from ZooKeeper (aka current|` | +| | |state) | | +| | | | | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ +|``GET`` |``/model/delta`` |Retrieves the delta between static|:ref:`view | +| | |model and live model |` | +| | | | | +| | | | | +| | | | | ++-----------+-------------------------------------------+----------------------------------+------------------------------------------+ + +.. _goe-rest-api-head-agents: + +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 + +.. _goe-rest-api-get-agents: + +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" + }, + ... + } + +.. _goe-rest-api-get-agent: + +View agent details +"""""""""""""""""" + +* Description: View the details of a single agent + +* Request: ``GET /agent/`` + + 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" + }} + +.. _goe-rest-api-get-agents-versions: + +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" + } + +.. _goe-rest-api-post-agents-versions: + +Upgrade the agents +"""""""""""""""""" + +* Description: Create a plan to upgrade the agents. You must then execute the plan as described in :ref:`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 :ref:`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" + + + + + + + + + + + + + + + + + + + + + + + +.. _goe-rest-api-get-plans: + +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" + } + +.. _goe-rest-api-post-plans: Create deployment plan """""""""""""""""""""" @@ -472,6 +805,39 @@ Execute a deployment plan * ``404`` (``NOT_FOUND``) if no such plan +.. _goe-rest-api-get-plan-executions: + +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//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 + .. _goe-rest-api-head-plan-execution: Check status of plan execution @@ -479,13 +845,13 @@ Check status of plan execution * Description: Return the status of the execution. -* Request: ``HEAD /plan// execution/`` +* Request: ``HEAD /plan//execution/`` * N/A * Response: - * ``200`` (``OK``) with ``X-LinkedIn-GLU-Completion`` header with value: + * ``200`` (``OK``) with ``X-glu-completion`` header with value: a. if plan non completed, percentage completion (ex: ``87``) @@ -500,7 +866,7 @@ View execution plan * Description: Return the execution as an xml document. -* Request: ``GET /plan// execution/`` +* Request: ``GET /plan//execution/`` * N/A @@ -516,7 +882,7 @@ Abort execution plan * Description: Abort the execution. -* Request: ``DELETE /plan// execution/`` +* Request: ``DELETE /plan//execution/`` * N/A @@ -524,6 +890,311 @@ Abort execution plan * TBD +.. _goe-rest-api-get-deployments-current: + +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" + }, + ... + } + +.. _goe-rest-api-delete-deployments-current: + +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 + +.. _goe-rest-api-get-deployment-current: + +View current deployment (details) +""""""""""""""""""""""""""""""""" + +* Description: View the current deployment details + +* Request: ``GET /deployment/current/`` + + 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 + < + + + + + ... + + +.. _goe-rest-api-head-deployment-current: + +View current deployment (info) +"""""""""""""""""""""""""""""" + +* Description: View the current deployment info (just the headers). + + +* Request: ``HEAD /deployment/current/`` + +* 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 + +.. _goe-rest-api-delete-deployment-current: + +Archive current deployment +"""""""""""""""""""""""""" + +* Description: Archive a single current deployment. + +* Request: ``DELETE /deployment/current/`` + +* 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 + +.. _goe-rest-api-head-deployments-archived: + +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 + +.. _goe-rest-api-get-deployments-archived: + +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" + } + } + +.. _goe-rest-api-get-deployment-archived: + +View archived deployment (details) +"""""""""""""""""""""""""""""""""" + +* Description: View the archived deployment details + +* Request: ``GET /deployment/archived/`` + + 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 + < + + + + + ... + + +.. _goe-rest-api-head-deployment-archived: + +View archived deployment (info) +""""""""""""""""""""""""""""""" + +* Description: View the archived deployment info (just the headers). + + +* Request: ``HEAD /deployment/archived/`` + +* 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 + .. _goe-rest-api-post-model-static: Load static model