|
|
Line 11: |
Line 11: |
| <startFeed /> | | <startFeed /> |
| = Deployments API changes = | | = Deployments API changes = |
| The '''Grid'5000''' platform provides an API for reserving and subsequently, ''deploying'' different resources (nodes, storage, etc). This API encapsulates and federates different actions and functionalities that can be performed on the resources. In this tutorial, we present the new version (4.0) of the Grid'5000 Deployments API that replaces the existing API (built before Kadeploy3 had a native API) by Kadeploy3's own API. | | The [[TechTeam:Deployments_API|Deployment API]] available in the "sid" or "4.0" has slightly changed: It now uses the native Kadeploy API. See [[TechTeam:Deployments_API|Deployment API page]] for more information. |
| | |
| Note: For detailed description of the Grid'5000 API and its complete set of features, [[API|please consult here]].
| |
| | |
| | |
| '''''Technical Aspect'''''
| |
| * For the stability of this doc, urls are given with the <code class="dir">/4.0</code> entry point, that are mapped behind <code class="dir">/sid</code> at the time this is written.
| |
| * The idea is to redirect all deployment-related requests coming to the Grid'5000 API, directly towards the local kadeploy-server at each site and let the kadeploy-server handle the requests and send a response back to the user. In details, the following URLs are handled by kadeploy3's API of the corresponding site :
| |
| ** <code class="dir">/4.0/sites/<site>/deployment</code>
| |
| ** <code class="dir">/4.0/sites/<site>/nodes</code>
| |
| ** <code class="dir">/4.0/sites/<site>/environments</code>
| |
| | |
| | |
| == Context and Scope of this document ==
| |
| Currently, we are undergoing a transition of the Grid'5000 API from its current version 3.0 to next version 4.0, for introducing new deployment functionalities as offered by the Kadeploy API. Briefly, the changes will be as follows:
| |
| * '''version 3.0''' with existing deployment functionalities and behaviour.
| |
| ** It uses the deployments API of Grid'5000 that is used before the native API of Kadeploy was developed.
| |
| ** This version will still be available on the branch '''<code class="dir">/stable/sites</code>''' or '''<code class="dir">/3.0/sites</code>'''.
| |
| * '''version 4.0''' with new deployment functionalities and behaviour.
| |
| ** It will expose the native API of Kadeploy that has been developed over the last few years.
| |
| ** We consider the native API of Kadeploy to be mature enough to be exposed directly without any pre-treatment from the g5k-api.
| |
| ** This version will be available on the branch '''<code class="dir">/sid/sites</code>''' or '''<code class="dir">/4.0/sites</code>'''.
| |
| | |
| Hence, the only branch that will undergo changes is the sid branch. Therefore, we will compare the current version of the sid branch (3.0) to its new version (4.0) after the changes have been incorporated - functionalities and behaviour.
| |
| | |
| '''Scope''': This page is to help the transition of users to orient themselves to the new version (4.0) of the Grid'5000 API. Hence, the scope is limited to changes in existing functionalities and behaviour for deployment use cases. For usage of the exhaustive list of functionalities offered by the Kadeploy native API, the user is advised to consult the [http://kadeploy3.gforge.inria.fr/api.html '''Kadeploy native API documentation'''].
| |
| | |
| == Key ''Use Cases'' of the deployments API ==
| |
| We consider in this page, the changes for the principal ''Use Cases'' of the deployments API of Grid'5000. They are the following:
| |
| # POST operations:
| |
| ## Deploy a recorded environment
| |
| # GET operations:
| |
| ## Gather a specific deployment status
| |
| ## Gather information about a deployment error
| |
| ## Gather deployment information about all nodes in a site
| |
| ## Gather deployment information about all environments in a site
| |
| # DELETE operations: Cancel a specific deployment
| |
| | |
| | |
| '''Note:''' The following Use Cases are for demonstrating the new deployments functionality of the API. Hence, we assume that the following nodes are already reserved (using oarsub commands or the API itself).
| |
| econome-8.nantes.grid5000.fr
| |
| econome-9.nantes.grid5000.fr
| |
| | |
| All the use cases will be based on some or all of the above two nodes. The demonstration is nevertheless applicable to all nodes and all sites in Grid'5000.
| |
| | |
| == '''POST operations''' ==
| |
| | |
| === Use Case: Deploy a recorded environment ===
| |
| This operation is for deploying a registered Linux environment on one or more reserved nodes.
| |
| | |
| ==== Using v3.0 of the API ====
| |
| From a frontend or access, the operation using the current g5k-api is as follows:
| |
| | |
| $ curl -kni https://api.grid5000.fr/3.0/sites/nantes/deployments -H'Content-Type: application/json' -d \
| |
| '{"nodes": ["econome-8.nantes.grid5000.fr", \
| |
| "econome-9.nantes.grid5000.fr"], \
| |
| "environment": "wheezy-x64-base", \
| |
| "key": "~/.ssh/id_rsa.pub"}'
| |
| | |
| | |
| The resulting output for a '''''successful''''' deployment using the current API is as follows:
| |
| | |
| {"created_at":1467197168,
| |
| "environment":"wheezy-x64-base",
| |
| "nodes":["econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"],
| |
| "site_uid":"nantes","status":"processing",
| |
| "uid":"D-00b17a69-74eb-4da7-b058-c49b78299d53",
| |
| "updated_at":1467197168,
| |
| "user_uid":"abasu",
| |
| "links":[{"rel":"self","href":"/sid/sites/nantes/deployments/D-00b17a69-74eb-4da7-b058-c49b78299d53","type":"application/vnd.grid5000.item+json"},
| |
| {"rel":"parent","href":"/sid/sites/nantes","type":"application/vnd.grid5000.item+json"}]
| |
| }
| |
| | |
| The resulting output for an '''''unsuccessful''''' deployment using the current API (e.g. when deployment image is not known) is as follows:
| |
| | |
| Cannot launch deployment: HTTP error #500:
| |
| ---- NoMethodError ----
| |
| private method `select' called for false:FalseClass
| |
| ---- Stack trace ----
| |
| ......
| |
| | |
| '''Note:''' For the stable version of the API, the above format will still continue to work until further notice.
| |
| | |
| ==== Using v4.0 of the API ====
| |
| | |
| For the 4.0 version of the API, the user will need to modify the above POST request as follows:
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment -X POST -H'Content-Type: application/json' -d '{
| |
| "nodes": ["econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"],
| |
| "environment": {
| |
| "kind" : "database",
| |
| "name": "jessie-x64-base"
| |
| }
| |
| }'
| |
| | |
| | |
| '''''Note:''''' In the new version, the URL will use ''deployment'' in singular (not ''deployments'').
| |
| | |
| | |
| The resulting output for a '''''successful''''' deployment using the new API will be as follows:
| |
| | |
| {
| |
| "wid": "D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c",
| |
| "resources": {
| |
| "resource": "/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/",
| |
| "log": "/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/logs",
| |
| "logs": {
| |
| "econome": "/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/logs/econome?user=userid"
| |
| },
| |
| "state": "/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/state",
| |
| "status": "/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/status",
| |
| "error": "/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/error"
| |
| }
| |
| }
| |
| | |
| | |
| The resulting output for an '''''unsuccessful''''' deployment using the current API (e.g. when deployment image is not known) is as follows:
| |
| | |
| Cannot launch deployment: HTTP error #500:
| |
| ---- NoMethodError ----
| |
| private method `select' called for false:FalseClass
| |
| ---- Stack trace ----
| |
| ......
| |
| | |
| ===== Mandatory & Optional parameters =====
| |
| In the payload of the POST request for deployment, the following table gives list of mandatory & optional parameters.
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Parameter !! Type !! Description & Examples
| |
| |-
| |
| | nodes || Mandatory || Array of nodes to be deployed. E.g.
| |
| ["econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"]
| |
| |-
| |
| | environment || Mandatory || Linux environment to be deployed. The form is a structure/hash. E.g.
| |
| {"kind" : "database",
| |
| "name": "jessie-x64-base"
| |
| }
| |
| |-
| |
| | ssh_authorized_keys || Optional || The ssh keys to be used for the deployment. E.g.
| |
| "/home/userid/.ssh/authorized_keys"
| |
| |-
| |
| | client || Optional || The machine (frontend, access, local, ...) from where the deployment request will be launched. E.g.
| |
| "http://frontend.nantes.grid5000.fr:12345"
| |
| |-
| |
| | custom_operations || Optional || Hash / structure for performing a customised deployment workflow. Please check advanced kadeploy documentation. E.g.
| |
| {
| |
| "SetDeploymentEnvUntrusted": {
| |
| "mount_deploy_part": {
| |
| "substitute": [
| |
| {
| |
| "action": "exec",
| |
| "name": "test-exec",
| |
| "command": "mount ${KADEPLOY_DEPLOY_PART} ${KADEPLOY_ENV_EXTRACTION_DIR}; partprobe ${KADEPLOY_BLOCK_DEVICE}"
| |
| }
| |
| ],
| |
| "post-ops": [
| |
| {
| |
| "action": "send",
| |
| "name": "test-send",
| |
| "file": "/home/frontend/test/_TMP_KATESTSUITE",
| |
| "destination": "/mnt/dest",
| |
| "scattering": "tree"
| |
| }
| |
| ]
| |
| }
| |
| },
| |
| "BroadcastEnvKastafior": {
| |
| "send_environment": {
| |
| "pre-ops": [
| |
| {
| |
| "action": "exec",
| |
| "name": "test-exec",
| |
| "command": "echo OK > ${KADEPLOY_ENV_EXTRACTION_DIR}/TEST_EXEC"
| |
| }
| |
| ],
| |
| "post-ops": [
| |
| {
| |
| "action": "run",
| |
| "name": "test-run",
| |
| "file": "/tmp/script20131009-30803-1cv2y8m"
| |
| }
| |
| ]
| |
| }
| |
| }
| |
| |}
| |
| | |
| '''Note:''' The list of parameters here is non-exhaustive. For an exhaustive list of parameters, the user is requested to consult the [http://kadeploy3.gforge.inria.fr/api.html#POST/%OPERATION '''Kadeploy native API documentation'''].
| |
| | |
| ==== Other forms of POST requests with new API ====
| |
| It is possible to create deployments using other forms of POST request as follows:
| |
| | |
| ===== Using location for deployment image =====
| |
| It is possible to deploy a customised environment using an explicit location on Grid'5000. The user will need to modify the above POST request as follows:
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment -X POST -H'Content-Type: application/json' -d '{
| |
| "nodes": ["econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"],
| |
| "environment": {
| |
| "name": "jessie-custom",
| |
| "image": {
| |
| "file": "http://frontend.nantes.grid5000.fr/~userid/debian-base.tgz",
| |
| "kind": "tar",
| |
| "compression": "gzip"
| |
| }
| |
| }'
| |
| | |
| The explanation of the parameters in the hash / structure ''environment'' is as follows:
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Parameter !! Type !! Description
| |
| |-
| |
| | name || string || Name of the environment
| |
| |-
| |
| | image || hash / structure || Details of the Linux image
| |
| |-
| |
| | file || string || Location of the Linux image file. Possible values are:
| |
| ''file://'' , ''http://'' , ''server://'' or none.
| |
| |-
| |
| | kind || string || Type of file (tarball, dsc, ...)
| |
| |-
| |
| | compression || string || Compression type of the file. Possible values are:
| |
| ''gzip'', ''bzip2'', ''xz''
| |
| |}
| |
| | |
| '''Note:''' The list of parameters here is non-exhaustive. For an exhaustive list of parameters, the user is requested to consult the official kadeploy API documentation.
| |
| | |
| ===== Using a shared Linux image from a user =====
| |
| For the 4.0 version of the API, the user will need to modify the above POST request as follows:
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment -X POST -H'Content-Type: application/json' -d '{
| |
| "nodes": ["econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"],
| |
| "environment": {
| |
| "kind" : "database",
| |
| "user" : "userid",
| |
| "name": "jessie-x64-custom",
| |
| "version": 2
| |
| }
| |
| }'
| |
| | |
| | |
| The explanation of the parameters in the hash / structure ''environment'' is as follows:
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! Parameter !! Type !! Description
| |
| |-
| |
| | kind || string || Registered in kadeploy DB or anonymous (optional)
| |
| |-
| |
| | user || string || Userid of user who owns / shares this environment. Note: If the environment belongs to another user (not self), the environment should at least be ''shared''.
| |
| |-
| |
| | name || string || Name of the environment as registered in kadeploy DB (mandatory)
| |
| |-
| |
| | version || Integer || Version of the environment (optional)
| |
| |}
| |
| | |
| '''Note:''' The list of parameters here is non-exhaustive. For an exhaustive list of parameters, the user is requested to consult the [http://kadeploy3.gforge.inria.fr/api.html#POST/%OPERATION '''Kadeploy native API documentation'''].
| |
| | |
| ==== Absence of ''deployment notifications'' ====
| |
| In the new version of the API, the notification feature for deployments will no longer be present. For different reasons, it has been decided to drop out this feature. Therefore, it is the user's responsibility to check for the status of the deployment, from time to time (or polling using a script).
| |
| | |
| The URL to poll is <code class="dir">https://api.grid5000.fr/4.0/sites/nantes/deployment/'''<deployment-id>'''</code> as in the following:
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c
| |
| | |
| The deployment-id is recovered from the element '''''wid''''' in the response of the [[Deployments_API#Using_v4.0_of_the_API|POST request]].
| |
| | |
| In the section below, a polling mechanism is explained how to determine the successful termination of a deployment.
| |
| | |
| == '''GET operations''' ==
| |
| The GET operations are for fetching different information related to a deployment on reserved nodes. Following are some important use cases.
| |
| | |
| === Use Case: Gather a specific deployment status ===
| |
| This operation is for recovering the actual status of a deployment operation on one or more reserved nodes.
| |
| | |
| ==== Using v3.0 of the API ====
| |
| The current operation using the g5k-api is as follows:
| |
| | |
| $ curl -kns https://api.grid5000.fr/3.0/sites/nantes/deployments/D-e2e3f396-239c-4c71-a7d5-007145693d45
| |
| | |
| The resulting output using the current API is as follows:
| |
| | |
| {"created_at":1467380141,"environment":
| |
| "wheezy-x64-base",
| |
| "key":"https://api.grid5000.fr/sid/sites/nantes/files/userid-key-c493e77b3c7a4a9457864d241b67a78b524fdcb7",
| |
| "nodes":["econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"],
| |
| "site_uid":"nantes",
| |
| "status":"processing",
| |
| "uid":"D-e2e3f396-239c-4c71-a7d5-007145693d45",
| |
| "updated_at":1467380141,
| |
| "user_uid":"userid",
| |
| "links":[{"rel":"self","href":"/sid/sites/nantes/deployments/D-e2e3f396-239c-4c71-a7d5-007145693d45","type":"application/vnd.grid5000.item+json"},
| |
| {"rel":"parent","href":"/sid/sites/nantes","type":"application/vnd.grid5000.item+json"}]
| |
| }
| |
| | |
| ==== Using v4.0 of the API ====
| |
| It will be possible to recover the state of a deployment on a site. From a frontend or access:
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment/D-e2e3f396-239c-4c71-a7d5-007145693d45
| |
| | |
| The resulting output using the new API will be as follows:
| |
| | |
| {
| |
| "wid": "D-e2e3f396-239c-4c71-a7d5-007145693d45",
| |
| "user": "abasu",
| |
| "done": true,
| |
| "error": false,
| |
| "start_time": 1467380141,
| |
| "environment": {
| |
| "id": null,
| |
| "user": "deploy",
| |
| "name": "wheezy-x64-base",
| |
| "version": 12
| |
| },
| |
| "logs": true,
| |
| "nodes": {
| |
| "ok": [
| |
| "econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"
| |
| ],
| |
| "ko": [
| |
|
| |
| ]
| |
| },
| |
| "time": 174.61
| |
| }
| |
| | |
| '''Note:''' The above list of nodes is no longer as items in an ''array''. It is a collection (hash) of items.
| |
| | |
| ==== Principle of polling mechanism for new version of API ====
| |
| | |
| Here we explain the polling mechanism to establish the successful termination of an ongoing deployment. Users can likewise design their own shell-scripts for this purpose.
| |
| | |
| The URL to poll is the following:
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment/D-d5942951-577a-4b01-990f-d7f7265d5505
| |
| | |
| As long as the deployment is ongoing, the result of the above request will have the hash structure as follows:
| |
| | |
| {
| |
| "wid": "D-d5942951-577a-4b01-990f-d7f7265d5505",
| |
| "user": "abasu",
| |
| '''"done": false''',
| |
| "error": false,
| |
| "start_time": 1467383724,
| |
| "environment": {
| |
| "id": 1532,
| |
| "user": "deploy",
| |
| "name": "jessie-x64-base",
| |
| "version": 2016061415
| |
| },
| |
| "logs": true,
| |
| "nodes": {
| |
| "'''ok'''": [
| |
|
| |
| ],
| |
| "'''ko'''": [
| |
|
| |
| ],
| |
| "'''processing'''": [
| |
| "econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"
| |
| ]
| |
| },
| |
| "'''time'''": 62.11
| |
| }
| |
| | |
| Important: In the above hash / structure, the following are certain interesting elements to observe (highlighted in bold):
| |
| * '''''done''''': This element gives the current status of the deployment at the time of polling. While the deployment is still ongoing, it is set to ''false''. Once the deployment is successfully completed, it is set to ''true''.
| |
| * The level of completion of deployment on a set of nodes is given by the 3 different arrays (lists) :
| |
| ** Array '''''OK[]''''' : Gives the list of nodes where deployment has been completed successfully. This list is empty at the beginning and is expected to get filled with all nodes just before the end of the complete deployment workflow.
| |
| ** Array '''''KO[]''''' : Gives the list of nodes where deployment failed, i.e. there was a problem that could not be resolved. In a fully successful deployment, this list is expected to remain empty.
| |
| ** Array '''''processing[]''''' : Gives the list of nodes where deployment is ongoing. At the beginning of the deployment, this list contains the list of all nodes for deployment. Just before the end of the workflow, this list becomes empty.
| |
| | |
| In addition, the '''''time''''' element gives the total time elapsed at the time of polling for status.
| |
| | |
| '''''Important:''''' Finally when the deployment is complete, the result of the polling request will the following:
| |
| | |
| {
| |
| "wid": "D-d5942951-577a-4b01-990f-d7f7265d5505",
| |
| "user": "abasu",
| |
| '''"done": true''',
| |
| "error": false,
| |
| "start_time": 1467383724,
| |
| "environment": {
| |
| "id": null,
| |
| "user": "deploy",
| |
| "name": "jessie-x64-base",
| |
| "version": 2016061415
| |
| },
| |
| "logs": true,
| |
| "nodes": {
| |
| "'''ok'''": [
| |
| "econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"
| |
| ],
| |
| "ko": [
| |
|
| |
| ]
| |
| },
| |
| "time": 181.24
| |
| }
| |
| | |
| * Notice the following:
| |
| ** '''''done''''' is set to ''true''. It remains so forever until the deployment record is finally deleted from the database.
| |
| ** The array '''''OK[]''''' gets filled with the names of all nodes at the end of the complete deployment workflow. It remains so forever until the deployment record is finally deleted from the database.
| |
| | |
| Other ways of polling to check the termination of a deployment consist of checking any of the following URLs (<code class="dir">/state</code>, <code class="dir">/status</code>, <code class="dir">/error</code>):
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/state"
| |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/status"
| |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment/D-eba50da3-e666-4d1e-b884-c9d4de8a3c3c/error"
| |
| | |
| === Use Case: Gather information about a deployment error ===
| |
| This operation is for fetching the ''error status'' of an ''unsuccessful'' Linux deployment on one or more reserved nodes.
| |
| | |
| ==== Using v3.0 of the API ====
| |
| There is no specific request in the current version of the API, to fetch ONLY the error status of a deployment. Nevertheless, the error (if any) can be fetched using the following command:
| |
| | |
| $ curl -kns https://api.grid5000.fr/3.0/sites/nantes/deployments/D-e2e3f396-239c-4c71-a7d5-007145693d45
| |
| | |
| The resulting output using the current API is as follows:
| |
| | |
| {"created_at":1467380141,"environment":
| |
| "wheezy-x64-base",
| |
| "key":"https://api.grid5000.fr/sid/sites/nantes/files/userid-key-c493e77b3c7a4a9457864d241b67a78b524fdcb7",
| |
| "nodes":["econome-8.nantes.grid5000.fr",
| |
| "econome-9.nantes.grid5000.fr"],
| |
| "site_uid":"nantes",
| |
| '''"status":"processing"''',
| |
| "uid":"D-e2e3f396-239c-4c71-a7d5-007145693d45",
| |
| "updated_at":1467380141,
| |
| "user_uid":"userid",
| |
| "links":[{"rel":"self","href":"/sid/sites/nantes/deployments/D-e2e3f396-239c-4c71-a7d5-007145693d45","type":"application/vnd.grid5000.item+json"},
| |
| {"rel":"parent","href":"/sid/sites/nantes","type":"application/vnd.grid5000.item+json"}]
| |
| }
| |
| | |
| In the above response, the '''status''' element shows if the deployment had an error (or was correctly terminated). In the above response, it shows ''processing'' which means that the deployment is currently ongoing. At the end of the deployment process, if status does not achieve ''terminated'', then there was an error during the deployment.
| |
| | |
| ==== Using v4.0 of the API ====
| |
| It will be possible to recover specifically the error state (if any) using the following GET request. From a frontend or access:
| |
| | |
| $ curl -kns https://api.grid5000.fr/4.0/sites/nantes/deployment/D-e2e3f396-239c-4c71-a7d5-007145693d45/error
| |
| | |
| If the deployment was successful, the resulting output using the new API is an empty hash, as follows:
| |
| | |
| {
| |
| }
| |
| | |
| == ''New Feature'': Get the list of all environments ==
| |
| This is a new feature. It is for recovering all the standard environments as well as those environments that are publicly registered/shared by users at a site.
| |
| ==== Using v3.0 of the API ====
| |
| Currently, there is no exact similar operation using the g5k-api.
| |
| | |
| ==== Using v4.0 of the API ====
| |
| It will be possible to recover the state of each node on a site (all clusters included) with regards to the last environment deployed on each node, by a particular user. From a frontend or access:
| |
| | |
| $ curl -kns 'https://api.grid5000.fr/4.0/sites/nantes/environments/?last=true&username=userid'
| |
| | |
| The resulting output using the new API will be as follows:
| |
| | |
| [
| |
| {
| |
| "name": "1404-x64-min",
| |
| "version": 2016061010,
| |
| "description": "Ubuntu 1404 (min)",
| |
| "author": "support-staff@lists.grid5000.fr",
| |
| "visibility": "public",
| |
| "destructive": false,
| |
| "os": "linux",
| |
| "image": {
| |
| "file": "server:///grid5000/images/ubuntu-x64-1404-2016061010.tgz",
| |
| "kind": "tar",
| |
| "compression": "gzip"
| |
| },
| |
| "postinstalls": [
| |
| {
| |
| "archive": "server:///grid5000/postinstalls/users/ubuntu/ubuntu-prepost_0.2.0.tgz",
| |
| "compression": "gzip",
| |
| "script": "traitement.ash /rambin"
| |
| }
| |
| ],
| |
| "boot": {
| |
| "kernel": "/vmlinuz",
| |
| "initrd": "/initrd.img"
| |
| },
| |
| "filesystem": "ext4",
| |
| "partition_type": 131,
| |
| "multipart": false,
| |
| "user": "deploy"
| |
| },
| |
|
| |
| .....
| |
| ]
| |
| | |
| '''Note:''' The above list is an ''array'' of hash items. If the filter username is not used, then the result is a list of environments deployed by ALL users.
| |
| | |
| === ''New Feature'': Get the status of ALL nodes in a site ===
| |
| This operation is for recovering the state of each node on a site (all clusters included) with regards to the last environment deployed on each node.
| |
| | |
| ==== Using v3.0 of the API ====
| |
| There is no exact similar operation using the g5k-api. The nearest similar to this command is the following, which gives the list of ALL deployments on a site. From a frontend or access:
| |
| | |
| $ curl -kns 'https://api.grid5000.fr/3.0/sites/nantes/deployments/'
| |
| | |
| The resulting output using the current API is as follows:
| |
| | |
| {"total":3453,
| |
| "offset":0,
| |
| "items":[{"created_at":1467355945,
| |
| '''"environment":"wheezy-x64-min"''',
| |
| "key":"https://api.grid5000.fr/sid/sites/nantes/files/ajenkins-key-327c569054f9a0e05533317edcecc766aa294385",
| |
| "nodes":["econome-3.nantes.grid5000.fr"],
| |
| "result":{"econome-3.nantes.grid5000.fr":{"macro":null,"micro":null,"state":"OK"}},
| |
| "site_uid":"nantes",
| |
| '''"status":"terminated"''',
| |
| "uid":"D-3479691c-df5f-4521-b3a5-ff828caf81f4",
| |
| "updated_at":1467356111,
| |
| "user_uid":"ajenkins",
| |
| "links":[{"rel":"self","href":"/sid/sites/nantes/deployments/D-3479691c-df5f-4521-b3a5-ff828caf81f4","type":"application/vnd.grid5000.item+json"},
| |
| {"rel":"parent","href":"/sid/sites/nantes","type":"application/vnd.grid5000.item+json"}]
| |
| },
| |
| ......
| |
| ]
| |
| }
| |
| | |
| ==== Using v4.0 of the API ====
| |
| It will be possible to recover the state of each node on a site (all clusters included) with regards to the last environment deployed on each node. From a frontend or access:
| |
| | |
| $ curl -kns 'https://api.grid5000.fr/4.0/sites/nantes/nodes/'
| |
| | |
| The resulting output using the new API will be as follows:
| |
| | |
| {
| |
| "econome-1.nantes.grid5000.fr": {
| |
| "state": "deployed",
| |
| "user": "ajenkins",
| |
| "environment": {
| |
| "name": "wheezy-x64-min",
| |
| "version": 12,
| |
| "user": "deploy"
| |
| }
| |
| },
| |
| .....
| |
| }
| |
| | |
| '''Note:''' The above list is not as items in an ''array''. It is a collection (hash) of items.
| |
| | |
| == '''DELETE operations''' ==
| |
| === Use Case: Cancel a specific deployment ===
| |
| This operation is for cancelling an existing deployment on one or more reserved nodes.
| |
| | |
| ==== Using v3.0 of the API ====
| |
| From a frontend or access, the operation using the current g5k-api is as follows:
| |
| | |
| $ curl -kni https://api.grid5000.fr/3.0/sites/nantes/deployments/D-160533e9-8a20-4a5b-89c5-d8c76a91a4ab -X DELETE
| |
| | |
| For a '''''successful''''' DELETE request for deployment, the response has HTTP status '''202 Accepted''' and an empty message (only HTTP header), as follows:
| |
| | |
| '''HTTP/1.1 202 Accepted'''
| |
| Date: Mon, 04 Jul 2016 09:14:15 GMT
| |
| Server: thin 1.2.11 codename Bat-Shit Crazy
| |
| Location: https://api.grid5000.fr/sid/sites/nantes/deployments/D-0e8812ff-e3f6-4ac8-a67c-b33fcda32de7
| |
| Content-Type: text/html; charset=utf-8
| |
| Cache-Control: no-cache
| |
| X-UA-Compatible: IE=Edge,chrome=1
| |
| X-Runtime: 4.100872
| |
| Vary: Accept-Encoding
| |
| X-Cache: MISS from api-proxy.sophia.grid5000.fr
| |
| X-Cache-Lookup: MISS from api-proxy.sophia.grid5000.fr:3128
| |
| Via: 1.0 api-server-devel.nantes.grid5000.fr:4444, 1.1 api-proxy.sophia.grid5000.fr:3128 (squid/2.7.STABLE9)
| |
| Transfer-Encoding: chunked
| |
|
| |
|
| |
| | |
| For an '''''unsuccessful''''' DELETE request for deployment (e.g. invalid deployment uid), the response has HTTP status '''404 Not Found''' and the error message is as follows:
| |
| | |
| '''HTTP/1.1 404 Not Found'''
| |
| Date: Mon, 04 Jul 2016 08:49:19 GMT
| |
| Server: thin 1.2.11 codename Bat-Shit Crazy
| |
| Allow: GET,DELETE,PUT
| |
| Vary: accept,Accept-Encoding
| |
| Content-Type: text/plain; charset=utf-8
| |
| Cache-Control: max-age=60, private
| |
| X-UA-Compatible: IE=Edge,chrome=1
| |
| X-Runtime: 0.004358
| |
| X-Cache: MISS from api-proxy.sophia.grid5000.fr
| |
| X-Cache-Lookup: MISS from api-proxy.sophia.grid5000.fr:3128
| |
| Via: 1.0 api-server-devel.nantes.grid5000.fr:4444, 1.1 api-proxy.sophia.grid5000.fr:3128 (squid/2.7.STABLE9)
| |
| Transfer-Encoding: chunked
| |
|
| |
| Couldn't find Grid5000::Deployment with ID=D-160533e9-8a20-4a5b-89c5-d8c76a91a4ac
| |
| | |
| ==== Using v4.0 of the API ====
| |
| | |
| For the 4.0 version of the API, the user will need to modify the above POST request as follows:
| |
| | |
| $ curl -kni https://api.grid5000.fr/4.0/sites/nantes/deployment/D-fe2f2b5d-c7ac-40a4-9780-c9653ee40bd3 -X DELETE
| |
| | |
| | |
| '''''Note:''''' In the new version, the URL will use ''deployment'' in singular (not ''deployments''). This is the ONLY modification necessary in the syntax of the DELETE request.
| |
| | |
| | |
| For a '''''successful''''' DELETE request for deployment, the response body gives only the ID of the deployment request. The HTTP status is '''200 OK'''. For e.g. if the deployment ID was ''D-fe2f2b5d-c7ac-40a4-9780-c9653ee40bd3'' the following success response is received.
| |
| | |
| HTTP/1.1 200 OK
| |
| Date: Mon, 04 Jul 2016 08:54:27 GMT
| |
| Server: WEBrick/1.3.1 (Ruby/2.1.2/2014-05-08) OpenSSL/1.0.1e
| |
| ETag:
| |
| Cache-Control: no-store, no-cache
| |
| Pragma: no-cache
| |
| Content-Type: application/json; charset="UTF-8"
| |
| Content-Encoding:
| |
| Content-Length: 53
| |
| X-Cache: MISS from api-proxy.sophia.grid5000.fr
| |
| X-Cache-Lookup: MISS from api-proxy.sophia.grid5000.fr:3128
| |
| Via: 1.1 api-proxy.sophia.grid5000.fr:3128 (squid/2.7.STABLE9)
| |
| Vary: Accept-Encoding
| |
|
| |
| {
| |
| '''"wid": "D-fe2f2b5d-c7ac-40a4-9780-c9653ee40bd3"'''
| |
| }
| |
| | |
| For an '''''unsuccessful''''' DELETE request for deployment (e.g. invalid deployment uid), the HTTP status is '''405 Method Not Allowed'''. The error message is as follows:
| |
| | |
| HTTP/1.1 405 Method Not Allowed
| |
| Date: Mon, 04 Jul 2016 08:58:16 GMT
| |
| Server: WEBrick/1.3.1 (Ruby/2.1.2/2014-05-08) OpenSSL/1.0.1e
| |
| Content-Type: text/plain; charset="UTF-8"
| |
| Allow: POST,PUT,GET,HEAD
| |
| Content-Length: 19
| |
| Vary: Accept-Encoding
| |
| X-Cache: MISS from api-proxy.sophia.grid5000.fr
| |
| X-Cache-Lookup: MISS from api-proxy.sophia.grid5000.fr:3128
| |
| Via: 1.1 api-proxy.sophia.grid5000.fr:3128 (squid/2.7.STABLE9)
| |
|
| |
| '''Method Not Allowed'''
| |
| | |
| | |
| '''Important:''' It is NOT possible to create a deployment (POST request) using the new version (4.0) of the API and DELETE it using the current version (stable) of the API. And vice-versa.
| |
| | |
| == Other functionalities ==
| |
| The exposure of the kadeploy native API brings many new functionalities, currently offered by kareboot3, stats, rights management, etc on the command-line.
| |
| | |
| === Table of new functionalities & references ===
| |
| The list of possibilities is given in the table below. For the detailed usage of each functionality please check the corresponding link.
| |
|
| |
| {| class="wikitable"
| |
| |-
| |
| ! Functionality !! Operations allowed !! Document link
| |
| |-
| |
| | <code class="command">reboot</code> || POST || [http://kadeploy3.gforge.inria.fr/api.html#Reboot%20operations Here]
| |
| |-
| |
| | <code class="command">rights</code> || POST, GET, PUT, DELETE || [http://kadeploy3.gforge.inria.fr/api.html#Rights%20management Here]
| |
| |- | |
| | <code class="command">stats</code> || GET || [http://kadeploy3.gforge.inria.fr/api.html#Statistics Here]
| |
| |-
| |
| | <code class="command">nodes</code> || GET || [http://kadeploy3.gforge.inria.fr/api.html#Nodes%20information Here]
| |
| |-
| |
| | <code class="command">environments</code> || POST, GET, PUT, DELETE || [http://kadeploy3.gforge.inria.fr/api.html#Environments%20management Here]
| |
| |-
| |
| | <code class="command">console</code> || POST, GET, DELETE || [http://kadeploy3.gforge.inria.fr/api.html#Console Here]
| |
| |-
| |
| | <code class="command">power</code> || PUT, GET || [http://kadeploy3.gforge.inria.fr/api.html#Power%20operations Here]
| |
| |-
| |
| | <code class="command">clusters</code>'''*''' || GET || [http://kadeploy3.gforge.inria.fr/api.html#GET/clusters Here]
| |
| |}
| |
| | |
| For usage of the exhaustive list of functionalities offered by the Kadeploy native API, the user is advised to consult the [http://kadeploy3.gforge.inria.fr/api.html '''Kadeploy native API documentation'''].
| |
| | |
| === Specific Usage of <code class="command">/clusters</code> '''*''' ===
| |
| This functionality requires specific attention as explained here. The g5k-api supports in the /stable and /3.0 version a GET operation on clusters in a site. This will continue to be supported in the new versions, i.e. /sid and /4.0 Nevertheless, the kadeploy3 native API also offers a GET operation on clusters, with a slightly different result output. We will demonstrate this below using the site <code class="command">sophia</code>, which has 4 clusters as follows:
| |
| * 2 normal clusters : <code class="command">sol</code> and <code class="command">suno</code> ---> accessible to all users
| |
| * 2 production clusters : <code class="command">uva</code> and <code class="command">uvb</code> ---> NOT accessible to all users
| |
| | |
| | |
| ==== Accessing <code class="command">/clusters</code> with the g5k-api ====
| |
| As before, from a frontend or access:
| |
| | |
| $ curl -kns 'https://api.grid5000.fr/3.0/sites/sophia/clusters/'
| |
| ... OR ...
| |
| $ curl -kns 'https://api.grid5000.fr/4.0/sites/sophia/clusters/'
| |
| | |
| The resulting output lists ''all'' the clusters as follows:
| |
| | |
| {
| |
| "total": 4,
| |
| "offset": 0,
| |
| "items": [
| |
| {
| |
| "created_at": "Thu, 22 Feb 2007 23:00:00 GMT",
| |
| "kavlan": true,
| |
| "model": "Sun Fire X2200 M2",
| |
| "queues": [
| |
| "default",
| |
| "admin"
| |
| ],
| |
| "type": "cluster",
| |
| "uid": "sol",
| |
| "version": "d89fda99e2e59936662091d032b76db6be11dbd5",
| |
| "links": [
| |
| {
| |
| "rel": "nodes",
| |
| "href": "/sid/sites/sophia/clusters/sol/nodes",
| |
| "type": "application/vnd.grid5000.collection+json"
| |
| },
| |
| {
| |
| "rel": "self",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/sol"
| |
| },
| |
| {
| |
| "rel": "parent",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia"
| |
| },
| |
| {
| |
| "rel": "version",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/sol/versions/d89fda99e2e59936662091d032b76db6be11dbd5"
| |
| },
| |
| {
| |
| "rel": "versions",
| |
| "type": "application/vnd.grid5000.collection+json",
| |
| "href": "/sid/sites/sophia/clusters/sol/versions"
| |
| },
| |
| {
| |
| "rel": "status",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/sol/status"
| |
| }
| |
| ]
| |
| },
| |
| {
| |
| "created_at": "Tue, 26 Jan 2010 23:00:00 GMT",
| |
| "kavlan": true,
| |
| "model": "Dell PowerEdge R410",
| |
| "queues": [
| |
| "default",
| |
| "admin"
| |
| ],
| |
| "type": "cluster",
| |
| "uid": "suno",
| |
| "version": "d89fda99e2e59936662091d032b76db6be11dbd5",
| |
| "links": [
| |
| {
| |
| "rel": "nodes",
| |
| "href": "/sid/sites/sophia/clusters/suno/nodes",
| |
| "type": "application/vnd.grid5000.collection+json"
| |
| },
| |
| {
| |
| "rel": "self",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/suno"
| |
| },
| |
| {
| |
| "rel": "parent",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia"
| |
| },
| |
| {
| |
| "rel": "version",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/suno/versions/d89fda99e2e59936662091d032b76db6be11dbd5"
| |
| },
| |
| {
| |
| "rel": "versions",
| |
| "type": "application/vnd.grid5000.collection+json",
| |
| "href": "/sid/sites/sophia/clusters/suno/versions"
| |
| },
| |
| {
| |
| "rel": "status",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/suno/status"
| |
| }
| |
| ]
| |
| },
| |
| {
| |
| "created_at": "Thu, 30 Jun 2016 22:00:00 GMT",
| |
| "kavlan": true,
| |
| "model": "Dell PowerEdge R900",
| |
| "queues": [
| |
| "default",
| |
| "admin"
| |
| ],
| |
| "type": "cluster",
| |
| "uid": "uva",
| |
| "version": "d89fda99e2e59936662091d032b76db6be11dbd5",
| |
| "links": [
| |
| {
| |
| "rel": "nodes",
| |
| "href": "/sid/sites/sophia/clusters/uva/nodes",
| |
| "type": "application/vnd.grid5000.collection+json"
| |
| },
| |
| {
| |
| "rel": "self",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/uva"
| |
| },
| |
| {
| |
| "rel": "parent",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia"
| |
| },
| |
| {
| |
| "rel": "version",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/uva/versions/d89fda99e2e59936662091d032b76db6be11dbd5"
| |
| },
| |
| {
| |
| "rel": "versions",
| |
| "type": "application/vnd.grid5000.collection+json",
| |
| "href": "/sid/sites/sophia/clusters/uva/versions"
| |
| },
| |
| {
| |
| "rel": "status",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/uva/status"
| |
| }
| |
| ]
| |
| },
| |
| {
| |
| "created_at": "Thu, 30 Jun 2016 22:00:00 GMT",
| |
| "kavlan": true,
| |
| "model": "Dell C6100",
| |
| "queues": [
| |
| "default",
| |
| "admin"
| |
| ],
| |
| "type": "cluster",
| |
| "uid": "uvb",
| |
| "version": "d89fda99e2e59936662091d032b76db6be11dbd5",
| |
| "links": [
| |
| {
| |
| "rel": "nodes",
| |
| "href": "/sid/sites/sophia/clusters/uvb/nodes",
| |
| "type": "application/vnd.grid5000.collection+json"
| |
| },
| |
| {
| |
| "rel": "self",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/uvb"
| |
| },
| |
| {
| |
| "rel": "parent",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia"
| |
| },
| |
| {
| |
| "rel": "version",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/uvb/versions/d89fda99e2e59936662091d032b76db6be11dbd5"
| |
| },
| |
| {
| |
| "rel": "versions",
| |
| "type": "application/vnd.grid5000.collection+json",
| |
| "href": "/sid/sites/sophia/clusters/uvb/versions"
| |
| },
| |
| {
| |
| "rel": "status",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia/clusters/uvb/status"
| |
| }
| |
| ]
| |
| }
| |
| ],
| |
| "version": "d89fda99e2e59936662091d032b76db6be11dbd5",
| |
| "links": [
| |
| {
| |
| "rel": "self",
| |
| "type": "application/vnd.grid5000.collection+json",
| |
| "href": "/sid/sites/sophia/clusters"
| |
| },
| |
| {
| |
| "rel": "parent",
| |
| "type": "application/vnd.grid5000.item+json",
| |
| "href": "/sid/sites/sophia"
| |
| }
| |
| ]
| |
| }
| |
| | |
| ==== Accessing <code class="command">/clusters</code> with the native kadeploy API ====
| |
| From a frontend or access:
| |
| | |
| $ curl -kns 'https://api.grid5000.fr/4.0/sites/sophia/internal/kadeployapi/clusters/'
| |
| | |
| The resulting output lists ''only the normal clusters'' as follows:
| |
| | |
| [
| |
| "sol",
| |
| "suno"
| |
| ]
| |
| | |
| As can be seen from the above, the output using the g5k-api is more detailed. The output using kadeploy native API is more concise and can be used to list in a simple ''array'', ONLY those clusters in a site that are accessible to ''all'' users.
| |
| <endFeed /> | | <endFeed /> |
|
| |
|
| <startFeed /> | | <startFeed /> |
| | |
| = [[Grid5000:School2016|Grid'5000 winter school]] now finished = | | = [[Grid5000:School2016|Grid'5000 winter school]] now finished = |
| The Grid'5000 spring school took place between February 2nd, 2016 and February 5th, 2016 in Grenoble. Two awards were given for presentation entries: | | The Grid'5000 spring school took place between February 2nd, 2016 and February 5th, 2016 in Grenoble. Two awards were given for presentation entries: |