Deployments API

From Grid5000
Jump to: navigation, search

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.

Note: For detailed description of the Grid'5000 API and its complete set of features, please consult here.


Technical Aspect

  • For the stability of this doc, urls are given with the /4.0 entry point, that are mapped behind /sid 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 :
    • /4.0/sites/<site>/deployment
    • /4.0/sites/<site>/environments
    • All URLs under /4.0/sites/<site>/kadeploy

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 /stable/sites or /3.0/sites.
  • 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 /sid/sites or /4.0/sites.

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 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:

  1. POST operations:
    1. Deploy a recorded environment
  2. GET operations:
    1. Gather a specific deployment status
    2. Gather information about a deployment error
    3. Gather deployment information about all nodes in a site
    4. Gather deployment information about all environments in a site
  3. 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": "debian9-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":"debian9-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.

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 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:

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:

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 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 https://api.grid5000.fr/4.0/sites/nantes/deployment/<deployment-id> 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 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":
    "debian9-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": "debian9-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 (/state, /status, /error):

   $ 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":
    "debian9-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":"debian9-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/kadeploy/nodes/'

The resulting output using the new API will be as follows:

   {
     "econome-1.nantes.grid5000.fr": {
       "state": "deployed",
       "user": "ajenkins",
       "environment": {
         "name": "debian9-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.

Functionality Operations allowed Document link
reboot POST Here
rights POST, GET, PUT, DELETE Here
stats GET Here
nodes GET Here
environments POST, GET, PUT, DELETE Here
console POST, GET, DELETE Here
power PUT, GET Here
clusters* GET Here

For usage of the exhaustive list of functionalities offered by the Kadeploy native API, the user is advised to consult the Kadeploy native API documentation.

Specific Usage of /clusters *

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 sophia, which has 4 clusters as follows:

  • 2 normal clusters : sol and suno ---> accessible to all users
  • 2 production clusters : uva and uvb ---> NOT accessible to all users


Accessing /clusters 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 /clusters 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.