News: Difference between revisions

From Grid5000
Jump to navigation Jump to search
No edit summary
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:

Revision as of 10:27, 20 December 2016

This page provides some news about the Grid'5000 testbed. You can also subscribe to the RSS feed and follow Grid'5000 on Twitter.

<startFeed />

Grid'5000 News now available as rss

Because mails to the users mailing list are lost to users joining Grid'5000, the technical team will now share Grid'5000 news using a blog like format.

Grid'5000 Team 15:11, 25 October 2016 (UTC) <endFeed />


<startFeed />

Deployments API changes

The Deployment API available in the "sid" or "4.0" has slightly changed: It now uses the native Kadeploy API. See Deployment API page for more information. <endFeed />

<startFeed />

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:

  • Best presentation award to Houssem-Eddine Chihoub and Christine Collet for their work on A scalability comparaison study of smart meter data management approaches (slides)
  • Most promising experiment to Anna Giannakou for her work Towards Self Adaptable Security Monitoring in IaaS Clouds (slides)

<endFeed />

<startFeed />

10 year later, the Grid'5000 school returns to Grenoble

10 year after the first edition of the Grid'5000 school, we invite the Grid'5000 community to take part in the Grid'5000 winter School 2016, February 2-5, 2016. <endFeed />

<startFeed />

Grid'5000 co-organizing the SUCCES 2015 event

These will take place November 5-6, 2015, in Paris. Dedicated to users of grid, cloud or regional HPC centers, the SUCCES 2015 days are organised by France Grilles, Grid'5000, Groupe Calcul and GDR ASR. <endFeed />

Retrieved from "https://www.grid5000.fr/mediawiki/index.php?title=News&oldid=64647"