Kadeploy 3.3.10.stable REST API specifications


Introduction

Request's parameters

There is several ways to specify parameters when using the network API. Parameters can be specified in the query's URI parameter but also in the query's body. Remark: it's only possible to use String and Array data structures when specifying parameters using the query's URI to specify more advanced parameters (Numbers, Hashs, ...) it's necessary to specify the parameters using a more advanced description language (JSON/YAML) in the query's body.

The following examples are equivalent:

Specifying parameters in the query's URI

      POST /deploy?nodes=node-1.testbed.lan&nodes=node-2.testbed.lan HTTP/1.1
      Accept: */*
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend

Specifying parameters in the query's body

JSON body

      POST /deploy HTTP/1.1
      Accept: */*
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend
      Content-Type: application/json
      Content-Length: 73
      {
        "nodes": [
          "node-1.testbed.lan",
          "node-2.testbed.lan"
        ]
      }

YAML body

      POST /deploy HTTP/1.1
      Accept: */*
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend
      Content-Type: application/x-yaml
      Content-Length: 47
      ---
      nodes:
      - node-1.testbed.lan
      - node-2.testbed.lan

Output type and encoding

The Kadeploy server can respond to a request in different formats: JSON and YAML, with or without compression (gzip only).

The response format depends on the value of the 'Accept' HTTP header of the request. By default (if it's set to */*) the response will be formated in JSON otherwise it will use the specified format.

The response encoding (compression) depends on the value of the 'Accept-Encoding' HTTP header. By default (if it's not set or set to */*) the response will not be compressed, otherwise it will be compressed using the gzip algorithm.

Here are some examples:

JSON response

      GET /nodes HTTP/1.1
      Accept: application/json
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend

      HTTP/1.1 200 OK
      Content-Type: application/json
      Content-Length: 50
      [
        "node-1.testbed.lan",
        "node-2.testbed.lan"
      ]

YAML response

      GET /nodes HTTP/1.1
      Accept: application/x-yaml
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend

      HTTP/1.1 200 OK
      Content-Type: application/x-yaml
      Content-Length: 47
      ---
      - node-1.testbed.lan
      - node-2.testbed.lan

Compressed JSON response

      GET /nodes HTTP/1.1
      Accept: application/x-yaml
      Accept-Encoding: gzip
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend

      HTTP/1.1 200 OK
      Content-Type: application/json
      Content-Encoding: gzip
      Content-Length: 52
      ...BINARY_DATA...

Global parameters

Some parameters are mendatory, they have to be precised in each request as parameter. Here is a list of them: user.

Authentication

To access API resources an authentication is needed. There is four different methods to authenticate when accessing a ressource. Depending on the server's configuration it will be possible to use -at least- one of this methods.

Authentication parameters are given in the HTTP headers of the request. A prefix can be set to this parameters, this prefix default to 'X-Kadeploy' but it can be set to another value (see GET /auth_headers_prefix).

Authentication using the IDENT protocol

The first authentication method is based on the IDENT protocol. When a request will be received on the server, it will first check if the request is coming from a trusted machine then it will contact the IDENT server of this machine in order to be sure that the username specified in the 'User' request's header is actually corresponding to the user on the machine that initiated the request. The 'User' request's header is not mandatory. In order to be authenticated with this method, no extra parameters have to be providen, an IDENT server just have to be set up on the machine that is used to initiate the request. Here is an example:

      GET /nodes HTTP/1.1
      Accept: */*
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend

Authentication by password

The second authentication method is the authentication by password (from trusted machines) using the HTTP Basic Authentication method (RFC 2617). In order to authenticate with such a method it's necessary to specify the user and password as a base64 string in the 'Authorization' request's header. Here is some examples:

      GET /nodes HTTP/1.1
      Accept: */*
      Host: kadeploy.testbed.lan:25300
      Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Authentication by certificate

To be able to authenticate using a (x509) certificate it's necessary to provide a base64 encoded x509 certificate that was signed with the trusted CA private key in the 'Certificate' request's header. The username must appear in the certificate's subject CN field. The 'User' request's header is not mandatory. Here is an example:

      GET /nodes HTTP/1.1
      Accept: */*
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend
      X-Kadeploy-Certificate: MIIEIzCCAwugAwIBAgIBGTANBgkqhkiG9w0BAQUFADBiMQswCQYDVQQ...XnMuLyV1FQ==

Authentication by ACL

If your machine's hostname is in the server's Access Control List, it will be trust without any further verifications. Here is an example:

      GET /nodes HTTP/1.1
      Accept: */*
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend

Errors management

Two kind of errors will be returned by the service: classical HTTP errors (Unauthorized, Forbidden, Not Found, ...) and Kadeploy specific errors.

Classical HTTP errors will be return fitting with the HTTP 1.1 standards, an error message will be add in the body of the response.

Kadeploy errors will be returned using the HTTP return code 400 (Bad Request) plus some (non-standard) HTTP header: X-Application-Error-Code and X-Application-Error-Info. The header X-Application-Error-Code will contain a Kadeploy specific error code while the header X-Application-Error-Info contains a (Base64 encoded) error message. The Kadeploy specific error codes are described in the following.

Here is an example of a Kadeploy specific error response:

      HTTP/1.1 400 Bad Request
      X-Application-Error-Code: 6
      X-Application-Error-Info: WW91IGRvIG5vdCBoYXZlIHN1ZmZpY2llbnQgcmlnaHRzIHRvIHBlcmZvcm0gdGhlIG9wZXJhdGlvbiBvbiBhbGwgdGhlIG5vZGVz
      Content-Type: text/plain
      Content-Length: 75
      You do not have sufficient rights to perform the operation on all the nodes

Kadeploy error codes

Error #NameDescription
1INVALID_WORKFLOW_IDInvalid workflow ID
2INVALID_NODELISTInvalid node list
3INVALID_CLIENTInvalid client's export
4INVALID_OPTIONInvalid option in the request
5INVALID_FILEInvalid file
6INVALID_RIGHTSYou do not have sufficient rights to perform the operation on all the nodes
7INVALID_ENVIRONMENTInvalid environment specification
8INVALID_CUSTOMOPInvalid custom operations specification
9INVALID_VLANInvalid VLAN
10EXISTING_ELEMENTElement already exists
11CONFLICTING_ELEMENTSSome elements already exists and are conflicting
12MISSING_OPTIONSome options are missing
13CONFLICTING_OPTIONSSome options are conflicting
14NOTHING_MODIFIEDNo element has been modified
15EXECUTE_ERRORThe execution of a command failed
20DATABASE_ERRORDatabase issue
21CACHE_ERRORSomething went wront with the cache system
22CACHE_FULLThe cache is full
30DESTRUCTIVE_ENVIRONMENTCannot reboot since the last deployed environment was destructive

Workflow based operations

Since some operations take time to be executed and can't directly return a result, we implemented a common asynchronious workflow.

The idea here will be to:

Deployment, Reboot and Power operations are workflow-based. For more information please take a look at the section Workflow-based operations.

Exporting files for the server

Files can be specified to the server using different methods. To change the method, you have to use specific protocols in the URI of the file.

Here are the supported protocols:

http://

The file is hosted at the following HTTP url

local:// or nothing

The file is hosted on a dynamic location, the parameter client will be used to specify where is the file hosted.

The server will try to download the file at [client]/Base64(filename).

For sample, if the specified file is file:///home/frontend/file and client is set to http://frontend.testbed.lan:12345, the server will try to download the file http://frontend.testbed.lan:12345/L2hvbWUvZnJvbnRlbmQvZmlsZQo=.

server://

The file is hosted on the Kadeploy server

Samples:

HTTP hosted file

      POST /environments HTTP/1.1
      Accept: text/plain, application/json
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend
      Content-Type: application/json
      Content-Length: 301
      {
        "environment": {
          "name": "debian-base",
          ...
          "image": {
            "file": "http://testbed.lan/debian-base.tgz",
            "kind": "tar",
            "compression": "gzip"
          },
          ...
        }
      }

Localy hosted files

      POST /environments HTTP/1.1
      Accept: text/plain, application/json
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend
      Content-Type: application/json
      Content-Length: 731
      {
        "client": "http://frontend.testbed.lan:12345",
        "environment": {
          "name": "debian-base",
          ...
          "image": {
            "file": "/home/frontend/debian-base.tgz",
            "kind": "tar",
            "compression": "gzip"
          },
          "postinstalls": [
            {
              "archive": "/home/frontend/debian-base-postinstall.tgz",
              "compression": "gzip",
              "script": "traitement.ash /rambin"
            }
          ],
          ...
        }
      }

Server hosted files

      POST /environments HTTP/1.1
      Accept: text/plain, application/json
      Host: kadeploy.testbed.lan:25300
      X-Kadeploy-User: frontend
      Content-Type: application/json
      Content-Length: 657
      {
        "environment": {
          "name": "debian-base",
          ...
          "image": {
            "file": "server:///tmp/debian-base.fsa",
            "kind": "fsa",
            "compression": 3
          },
          ...
        }
      }

API documentation notations

When using the Network API, the data structures used to describe resources can be complex (Array, Hash, nested structured, ...), that's why we decided to use a specific formalism to describe them.

Body's type of the request/response

First of all, the type of the main structure is describe in the title, for sample:

Request/Response/Type(Hash)

Means that the request's body have to be a Hash, formated used one of the allowed Content-Type (see Request's parameters and Output type and encoding)

Hash

Here is an example of the description of a simple Hash and some basic elements, the {} chars are used to specify that "myhash" has the type Hash.

Example(Hash)

An example

NameTypeDescription
{myhash}HashThe sample Hash
{myhash}.userStringThe username
{myhash}.sizeIntegerThe size
{myhash}.optionBooleanEnable/Disable "option"
{myhash}.settingSetIf this field is set, no mather it's value, the option "setting" is enabled

An HTTP request's sample:

      POST /sample HTTP/1.1
      Accept: text/plain, application/json
      Content-Type: application/json
      Content-Length: 81
      {
        "myhash": {
          "size": 42,
          "option": true,
          "setting": null
        }
      }

Arrays

Here is an example of the description of a simple Array, the [] chars are used to specify that "myarray" has the type Array, the char # specify that the element that is described is the result of an iteration on the Array.

Example(Hash)

An example

NameTypeDescription
[myarray]ArrayThe sample Array
[myarray].#iStringThe element #i

An HTTP request's sample:

      POST /sample HTTP/1.1
      Accept: text/plain, application/json
      Content-Type: application/json
      Content-Length: 54
      {
        "myarray": [
          "abc",
          "def",
          "ghi"
        ]
      }

Dynamic Hash key names

Hash table's keys do not always have a static name, in some cases, the key name can be dynamic. In this case, the key name will be underlined this way. Here is an example:

Example(Hash)

An example

NameTypeDescription
{myhash}HashThe sample Hash
{myhash}.nodenameIntegerReturns the uptime of the node "nodename"

An HTTP request's sample:

      POST /sample HTTP/1.1
      Accept: text/plain, application/json
      Content-Type: application/json
      Content-Length: 83
      {
        "myhash": {
          "node-1": 12345,
          "node-2": 45678,
          "node-3": 90123
        }
      }

URI path parameters

Some parameters can be specified in the URI, in the documentation, this parameters will be underlined.

In the URI, dynamic parameters will be prefixed with a : such as :name; if the parameter is suffixed with a ?, this parameter is optional, for sample :version?. Here is an example :

GET /sample/:name/:version?( )

An example

NameTypeDescription
userStringThe user
nameStringThe name
versionStringThe version

An HTTP request's sample:

      GET /sample/thename/ HTTP/1.1
      Accept: text/plain, application/json

Nested structured

Structures can then be nested in different ways:

Example(Hash)

An example

NameTypeDescription
{myhash}HashThe sample Hash
versionStringThe version
{myhash}.{anotherhash}HashThe first hash
{myhash}.{anotherhash}.{nodename}HashDescription of the node "nodename"
{myhash}.{anotherhash}.{nodename}.userStringThe username
{myhash}.{anotherhash}.{nodename}.optionBooleanEnable/Disable "option"
{myhash}.[myarray]ArrayThe first array
{myhash}.[myarray].{#i}HashThe element #i
{myhash}.[myarray].{#i}.sizeIntegerThe size
{myhash}.[myarray].{#i}.settingSetIf this field is set, no mather it's value, the option "setting" is enabled

An HTTP request's sample:

      POST /sample HTTP/1.1
      Accept: text/plain, application/json
      Content-Type: application/json
      Content-Length: 351
      {
        "myhash": {
          "anotherhash": {
            "node-1": {
              "user": "user1",
              "option": true
            },
            "node-2": {
              "user": "user2",
              "option": false
            }
          },
          "myarray": [
            {
              "size": 4,
              "setting": null
            },
            {
              "size": 2
            },
            {
              "size": 8
            }
          ]
        }
      }


Workflow-based operations

Resources

Return types

Workflow(Hash)

The information related to the workflow of an operation (deployment,reboot,power)

NameTypeDescription
idStringThe id# of the operation (prefixed by "D-" for deployment, "R-" for reboot, "P-" for power and "C-" for console)
userStringThe user that initiated the operation
doneBooleanSet to true if the operation is done. Once an operation is done it's information should be removed from the API using the DELETE method.
errorBooleanSet to true if an error was encountered. The error message can be obtained by getting /%OPERATION/:id/error.
start_timeIntegerThe start time (POSIX time) of the operation
logsBooleanNew logs available for polling (see /%OPERATION/:id/logs). Only available to the users that have the rights to consult the information about this operation.
debugsBooleanNew debugs available for polling (see /%OPERATION/:id/debugs). Only available to the users that have the rights to consult the information about this operation.
timeFloatThe time elapsed since the start of the operation. Only available to the users that have the rights to consult the information about this operation.
{environment}HashThe environment that is currently being deployed. Only displayed when the operation uses an environment. Only available to the users that have the rights to consult the information about this operation.
{environment}.idStringThe id# of the environment
{environment}.userStringThe owner of the environment
{environment}.nameStringThe name of the environment
{environment}.versionIntegerThe version of the environment
nodesHash/ArrayIf the user have the rights to consult the information, a list of nodes ordered by state will be returned otherwise an Array of the nodes involved in the operation will be returned
nodes.[ok]ArrayThe list of nodes that have finish the operation successfully
nodes.[ko]ArrayThe list of nodes that have finish the operation with an error. The error message of each node can be obtained by getting /%OPERATION/:id/state.
nodes.[processing]ArrayThe list of nodes that are still processing the operation

Example #1

{
  "id": "D-b9401264-4383-4401-a548-1f881ea14acb",
  "user": "frontend",
  "done": false,
  "error": false,
  "environment": {
    "id": -1,
    "user": "frontend",
    "name": "debian-anon",
    "version": 1
  },
  "logs": false,
  "nodes": {
    "ok": [
    ],
    "ko": [
    ],
    "processing": [
      "node-2.testbed.lan"
    ]
  },
  "time": 30.92
},

Example #2

{
  "id": "D-75105d91-777a-4e3b-bf4e-2690a544031a",
  "user": "root",
  "done": false,
  "error": false,
  "nodes": [
    "node-1.testbed.lan"
  ]
}

Example #3

{
  "id": "R-4d657bda-1cad-4739-ab3d-e58879a3d962",
  "user": "frontend",
  "done": false,
  "error": false,
  "nodes": [
    "node-1.testbed.lan",
    "node-2.testbed.lan"
  ]
}

Example #4

{
  "id": "P-bf447aae-1fd5-4062-b1ff-03e72d5de6ba",
  "user": "frontend",
  "done": false,
  "error": false,
  "logs": true,
  "nodes": {
    "ok": [
    ],
    "ko": [
    ],
    "processing": [
      "node-1.testbed.lan",
      "node-2.testbed.lan"
    ]
  },
  "time": 1.01
}

POST /%OPERATION

Launch an operation

Request (Hash, application/json)

Parameters

NameTypeKindDescription
...Deployment/Reboot/PowerMandatoryThe operation's parameters
breakpointStringOptionalThe name of a step to breakpoint on (can be MacrostepName or MacrostepName:MicrostepName)
{custom_operations}HashOptionalAdd some custom steps to the operation's workflow
debugSetOptionalEnable the command's debugging
forceSetOptionalForce the operation, even if the nodes seems to be already involved in another one
hookSetOptionalEnable the server-side hook at the end of the operation
verbose_levelIntegerOptionalThe verbose level of the logs
Expected values: 1, 2, 3, 4, 5
{custom_operations}.{macrostepname}HashMandatoryThe macro-step the custom-step has to be added to
{custom_operations}.{macrostepname}.{microstepname}HashMandatoryThe micro-step the custom-step has to be added to
{custom_operations}.{macrostepname}.{microstepname}.overwriteBooleanOptionalOverwrite the custom-steps that were add in the configuration by the administrators
Default value: false
{custom_operations}.{macrostepname}.{microstepname}.[where]ArrayOptionalA list of actions to be substitued/pre/post to this step
Expected values: substitute, pre-ops, post-ops
{custom_operations}.{macrostepname}.{microstepname}.[where].actionStringOptionalThe action that have to be performed
Expected values: run, send, exec
{custom_operations}.{macrostepname}.{microstepname}.[where].commandStringOptional(To be specified if the action is "exec") The command to be executed. If you want to call a script, dont forget to add a "." (or use "source") before the script name to be able to use Kadeploy3 environment variables inside of it (example: "command: . /myscript.sh").
{custom_operations}.{macrostepname}.{microstepname}.[where].destinationStringOptional(To be specified if the action is "send") The destination directory on the nodes (Kadeploy3 environment variables are substitued in the path)
{custom_operations}.{macrostepname}.{microstepname}.[where].fileStringOptional(To be specified if the action is "send" or "run") The path to the file to be send/executed (if the action is "send" the file name will remains the same, if the action is "run" this file need to contain a script)
{custom_operations}.{macrostepname}.{microstepname}.[where].nameStringOptionalThe name of the custom operation
{custom_operations}.{macrostepname}.{microstepname}.[where].paramsStringOptional(To be specified if the action is "run") The parameters of the script.
Default value: empty string
{custom_operations}.{macrostepname}.{microstepname}.[where].retriesIntegerOptionalThe number of retries for this custom operation
Default value: 0
{custom_operations}.{macrostepname}.{microstepname}.[where].scatteringStringOptionalThe scattering kind for this custom operation
Expected values: tree, chain
Default value: tree
{custom_operations}.{macrostepname}.{microstepname}.[where].timeoutIntegerOptionalThe timeout (seconds) of this custom operation
Default value: 0

Response (Hash, application/json)

Fields

NameTypeDescription
{resources}HashThe resources associated with the workflow and their URL
{resources}.debugStringConcatenated debugs
{resources}.{debugs}HashDebugs by node
{resources}.{debugs}.nodenameStringDebug of node nodename
{resources}.errorStringError message
{resources}.outputStringConcatenated outputs
{resources}.{outputs}HashOutputs by cluster
{resources}.{outputs}.clusternameStringOutput of cluster clustername
{resources}.stateStringDeployment state of nodes
{resources}.statusStringStatus of operation's instances (one instance by cluster)
widStringThe id# of the workflow that was initiated

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Deploy a recorded environment

Example #2 Perform a simple reboot

Example #3 Perform a power-off

Example #4 Launch a deployment with some custom operations


GET /%OPERATION

Get the workflow information of every running operation of the kind OPERATION

Request (Hash, application/json)

Parameters

NameTypeKindDescription

Response (Hash, application/json)

Fields

NameTypeDescription
#iWorkflowThe list of current operation's worklow information

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Get the list of current deployments


GET /%OPERATION/:id

Get the workflow information (polling) of an operation

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation

Response (Hash, application/json)

Fields

NameTypeDescription
WorkflowThe workflow information related to the operation #:id

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

Example #1 Gather a specific deployment status


GET /%OPERATION/:id/logs/:cluster?

Get logs of a running operation (the "logs" field was set to true on the workflow's info)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation
clusterStringOptionalThe name of the specific cluster to get the logs for

Response (String, text/plain)

Fields

NameTypeDescription
StringThe logs of the current operation prefixed by the timestamp of each line plus '|' in order to be able to sort them

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

Example #1 Gather a specific deployment logs

Example #2 Gather logs of a specific cluster


GET /%OPERATION/:id/debugs/:node?

Gather the command's debugs of some/every nodes (the "debugs" field was set to true on the workflow's info)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation
nodeStringOptionalThe name of the specific node to get the debugs for

Response (String, text/plain)

Fields

NameTypeDescription
StringThe logs of the current operation prefixed by the timestamp of each line plus '|' in order to be able to sort them

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

Example #1 Get debugs of every nodes

Example #2 Get debugs of a specific node


GET /%OPERATION/:id/state

Get the state of every nodes in a specific operation. Available when the operation is done.

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation

Response (Hash, application/json)

Fields

NameTypeDescription
{nodename}HashThe state of the node nodename
{nodename}.errorStringIf the node is KO, contains the error message
{nodename}.macroStringThe macro-step operation the node is performing
{nodename}.microStringThe micro-step operation the node is performing
{nodename}.stateStringThe state of the node

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

Example #1 Get state of a specific deployment

Example #2 Get state of a specific power operation

Example #3 Get state of a deployment that failed


GET /%OPERATION/:id/status

Get the global status of an operation (where are every nodes in the operation)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation

Response (Hash, application/json)

Fields

NameTypeDescription
{clustername}HashThe status of the cluster clustername
{clustername}.{macrostepname}HashThe status of the macro-step macroname
{clustername}.{macrostepname}.{microstepname}HashThe status of the micro-step microname
{clustername}.{macrostepname}.{microstepname}.{nodes}HashThe status of the nodes (of clustername) in the step macroname-microname
{clustername}.{macrostepname}.{microstepname}.{nodes}.[**]ArrayThe nodes that are processing the step
{clustername}.{macrostepname}.{microstepname}.{nodes}.[KO]ArrayThe nodes that have failed the step
{clustername}.{macrostepname}.{microstepname}.{nodes}.[OK]ArrayThe nodes that have successfully done the step

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

Example #1 Get the status of a specific deployment

Example #2 Get the status of a specific power operation


GET /%OPERATION/:id/error

Get the error of an operation (the "error" field was set to true on the workflow's info)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation

Response (String, text/plain)

Fields

NameTypeDescription
StringThe error message

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

Example #1 Gather information about a deployment error


DELETE /%OPERATION/:id

Cancel a running operation or delete information about one that encountered an error

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operatiooperationn

Response (Hash, application/json)

Fields

NameTypeDescription
widStringThe id# of the operation that was deleted

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

Example #1 Cancel a specific deployment



Reboot operations

Resources


POST /reboot

Launch a reboot operation

Request (Hash, application/json)

Parameters

NameTypeKindDescription
kindStringMandatoryThe kind of reboot to be performed
Expected values: set_pxe, simple, deploy_env, recorded_env
[nodes]ArrayMandatoryThe list of nodes the operation should be applied on
_generic_parameter_...OptionalSome workflow-based operation's generic parameter (see more here)
block_deviceStringOptionalThe block device the environment has been installed on
check_destructiveSetOptionalCheck if the last deployed environment has the destructive flag, if it does, do not perform the reboot operation
clientStringOptionalThe client used to export files to the server, useful for local:// files (see more here)
deploy_partitionIntegerOptionalThe partition the environment has been installed on
{environment}HashOptionalThe environment that has been deployed. This field is mandatory when using the kind "recorded_env".
levelStringOptionalThe level of the command that will be performed
Expected values: soft, hard, very_hard
Default value: soft
{pxe}HashOptionalSpecify some custom netboot parameters. This field is mandatory when using the kind "set_pxe".
ssh_authorized_keysStringOptionalThe path to a ssh authorized_keys file that have to be copied in the root directory of the deployed environment (see more here)
timeout_reboot_classicalIntegerOptionalOverwrite the default value for the reboot timeout
vlanStringOptionalSpecify the VLAN the nodes should be reboot in
{environment}.nameStringMandatoryThe name of the environment
{environment}.userStringOptionalThe owner of the environment
{environment}.versionStringOptionalThe version of the environment
{pxe}.[files]ArrayOptionalA list of path to files that have to be exported in the PXE repository's directory (see more here)
{pxe}.pxeStringOptionalA custom PXE profile, the string FILES_PREFIX-- will be replaced by the prefix to some exported files
{pxe}.{singularities}HashOptionalSpecify a substitution pattern for each node in the PXE profile (the NODE_SINGULARITY pattern must be used in the PXE profile)
{pxe}.{singularities}.nodenameStringOptionalThe substitution pattern for the node "nodename"

Response (Hash, application/json)

Fields

NameTypeDescription
WorkflowInformation related to the workflow of the reboot operation

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Perform a simple hard reboot on nodes (do not re-write the PXE profile)

Example #2 Reboot nodes on the deployment environment and send the user's SSH authorized_keys file

Example #3 Reboot nodes on a (previously installed) recorded environment and check if the partition table was destroyed

Example #4 Reboot nodes on a specified kernel using a custom PXE profile with some nodes singularities



Rights management

Resources

Return types

Rights(Hash)

Rights of a specific user on some disks/partitions of some nodes

NameTypeDescription
{username}HashThe user the rights are related to
{username}.[nodename]ArrayThe node the rights are applied on. If "nodename" is *, the rights are applied on every nodes
{username}.[nodename].#iStringPartitions the rights are granted to. If "partitions" is *, the rights are applied on every disks/partitions

POST /rights

Grant the permession to deploy to a specific user on some node's partitions

Request (Hash, application/json)

Parameters

NameTypeKindDescription
[nodes]ArrayOptionalThe list of nodes the rights should be added to. If not specified, rights will be added on all the nodes
overwriteBooleanOptionalOverwrite if some rights are already set for this user
[partitions]ArrayOptionalThe partitions/disks the rights should be added to. If the array contains *, rights will be added on every partition/disk
usernameStringOptionalThe name of the user the rights should be granted. Defaults to "user"

Response (Hash, application/json)

Fields

NameTypeDescription
RightsThe rights that was added for the user "username"

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
400-11Some elements of the request are conflicting
400-12No element has been modified

Example #1 Grant privileges on every partitions of a specific node

Example #2 Grant privileges on a specific partition of some nodes


GET /rights/:username?/:node?

Gather information about someone's deploy permission on nodes

Request (Hash, application/json)

Parameters

NameTypeKindDescription
nodeStringOptionalThe node to check the rights on
usernameStringOptionalThe name of the user to check the rights for. If not specified, returns the rights of every users
[nodes]ArrayOptionalThe list of nodes the rights should be checked on. If nor "node" or "nodes" are specified, rights of all the nodes will be returned. If both "node" and "nodes" are specified, the rights of [nodes]+node will be returned

Response (Hash, application/json)

Fields

NameTypeDescription
RightsThe rights of the user "username"

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, username or node not found

Example #1 Get the rights of every users

Example #2 Get the rights of a specific user

Example #3 Get the rights of a specific user on a specific node

Example #4 Get the rights of a specific user on several nodes



DELETE /rights/:username/:node?/:partition?

Remove some rights on some nodes.
If no more rights are remaining on some of the nodes, every operations (workflows) involving this nodes will be killed.

Request (Hash, application/json)

Parameters

NameTypeKindDescription
usernameStringMandatoryThe name of the username to remove the rights to
nodeStringOptionalThe node to remove the rights from
partitionStringOptionalThe partitions to remove the rights from (should be urlencoded)
[nodes]ArrayOptionalThe list of nodes the rights should removed from. If nor "node" or "nodes" are specified, rights of all the nodes will be removed. If both "node" and "nodes" are specified, the rights of [nodes]+node will be removed

Response (Hash, application/json)

Fields

NameTypeDescription
RightsThe rights that was removed

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, username or node not found
400-11Some elements of the request are conflicting
400-12No element has been modified

Example #1 Remove the rights on every nodes from a specific user

Example #2 Remove the rights on a specific node from a specific user

Example #3 Remove the rights on several nodes from a specific user

Example #4 Remove the rights on a specific partition of a specific node from a specific user



Statistics


GET /stats/%OPERATION?

Gather statistics. The operation can be set to deploy, reboot, power or an empty value

Request (Hash, application/json)

Parameters

NameTypeKindDescription
date_maxStringMandatoryStatistics to a specific date date (RFC 2616 format)
date_minStringMandatoryStatistics from a specific date date (RFC 2616 format)
fieldsArrayMandatoryThe fields to be displayed
Expected values: wid, user, hostname, step1, step2, step3, timeout_step1, timeout_step2, timeout_step3, retry_step1, retry_step2, retry_step3, start, step1_duration, step2_duration, step3_duration, env, md5, success, error
Default value: ["wid", "user", "hostname", "step1", "step2", "step3", "timeout_step1", "timeout_step2", "timeout_step3", "retry_step1", "retry_step2", "retry_step3", "start", "step1_duration", "step2_duration", "step3_duration", "env", "md5", "success", "error"]
kindStringMandatoryThe kind of statistics
Expected values: all, failure_rates
Default value: all
min_failure_rateFloatMandatoryThe list of nodes which have a specified minimum failure-rate (between 0 and 1). This filter have to be used with the kind failure_rates
min_retriesIntegerMandatoryStatistics about the nodes that need at least NB attempts to perform specific steps
[nodes]ArrayMandatoryThe list of nodes to gather the statistics about
sortArrayMandatoryThe fields to sort results by
Expected values: wid, user, hostname, step1, step2, step3, timeout_step1, timeout_step2, timeout_step3, retry_step1, retry_step2, retry_step3, start, step1_duration, step2_duration, step3_duration, env, md5, success, error
Default value: ["wid", "user", "hostname", "step1", "step2", "step3", "timeout_step1", "timeout_step2", "timeout_step3", "retry_step1", "retry_step2", "retry_step3", "start", "step1_duration", "step2_duration", "step3_duration", "env", "md5", "success", "error"]
[step_retries]ArrayMandatoryApply the retry filter on the given steps
widStringMandatorySpecify the workflow #id

Response (String, gzipped text/csv or application/json)

Fields

NameTypeDescription
#lineStringA line in the format specified by the fields parameter

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, invalid operation

Example #1 Gather all statistics

Example #2 Gather deployments statistics

Example #3 Gather the list of nodes with a specific failure rate

Example #4 Gather all statistics to a specific date



Nodes information

Resources

Return types

NodeStatus(Hash)

Status of nodes

NameTypeDescription
{nodename}HashThe status of the node nodename
{nodename}.stateStringThe current state of the node
Possible values: 1, 2, 3, ...
{nodename}.userStringThe last user that deployed the node
{nodename}.{environment}HashThe last environment that was deployed on the node
{nodename}.{environment}.userStringThe owner of the environment
{nodename}.{environment}.nameStringThe name of the environment
{nodename}.{environment}.versionStringThe version of the environment

GET /nodes/:nodename?

Gather nodes information

Request (Hash, application/json)

Parameters

NameTypeKindDescription
nodenameStringOptionalGather information of a specific node
listBooleanOptionalAsk to return an Array of node names corresponding to the nodes that are managed by the server

Response (Hash/Array, application/json)

Fields

NameTypeDescription
NodeStatusStatus of the nodes

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, nodename not found

Example #1 Get the status of every nodes

Example #2 Get the status of a specific node

Example #3 Get the list of nodes



Environments management

Resources

Return types

Environment(Hash)

The description of an environment

NameTypeDescription
userStringThe owner of the environment
nameStringThe name of the environment
osStringThe operating system of the environment
Possible values: linux, xen, other
{image}HashThe image file that contains the environment
{image}.fileStringThe path to the image file (see more here)
{image}.kindStringThe kind of image
Possible values: tar, dd, fsa
{image}.compressionStringThe compression algorithm used to compress the image
Possible values: gzip, bzip2, xz
versionIntegerThe version of the environment
descriptionStringThe description of the environment
authorStringThe author of the environment
visibilityStringThe visibility of the environment
Possible values: public, private, shared
destructiveBooleanThe environment destruct the disk partitioning
multipartBooleanThe environment image is a multi-partitioned archive
{preinstall}HashA preinstall script archive
{preinstall}.fileStringThe path to the archive file (see more here)
{preinstall}.compressionStringThe compression algorithm used to compress the archive
Possible values: gzip, bzip2, xz
{preinstall}.scriptStringPath to a script (inside the archive) that will be launched during the pre-install step
[postinstalls]ArrayA list of postinstall script archives
[postinstalls].{#i}HashA postinstall script archive
[postinstalls].{#i}.fileStringThe path to the archive file (see more here)
[postinstalls].{#i}.compressionStringThe compression algorithm used to compress the archive
Possible values: gzip, bzip2, xz
[postinstalls].{#i}.scriptStringPath to a script (inside the archive) that will be launched during the post-install step
{boot}HashThe environment's boot parameters
{boot}.kernelStringPath to the kernel file (inside the environment\s image)
{boot}.initrdStringPath to the initrd file (inside the environment\s image)
{boot}.kernel_paramsStringThe parameters to be given to the kernel at launch time
{boot}.hypervisorStringPath to the hypervisor file (inside the environment\s image), useful when deploying Xen environments
{boot}.hypervisor_paramsStringThe parameters to be given to the hypervisor at launch time, useful when deploying Xen environments
{boot}.block_deviceStringThe block device environment should be installed on, useful for multi-partitioned environments
{boot}.deploy_partStringThe partition the environment should be installed on, useful for multi-partitioned environments
partition_typeStringThe partition type that will be set when partitioning the disk
filesystemStringThe filesystem type of the environment, useful for tar environments
optionsStringCustom options
options.[partitions]ArrayA list of id/partition association
options.[partitions].idIntegerThe id of the partition inside the compressed archive
options.[partitions].deviceStringThe physical device this archive part should be installed on

Example #1

{
  "name": "debian-custom",
  "version": 2,
  "visibility": "private",
  "destructive": false,
  "os": "linux",
  "image": {
    "file": "http://testbed.lan/debian-base.tgz",
    "kind": "tar",
    "compression": "gzip"
  },
  "boot": {
    "kernel": "/boot/vmlinuz",
    "initrd": "/boot/initrd.img"
  },
  "filesystem": "ext4",
  "partition_type": 0,
  "multipart": false,
}

Example #2

{
  "name": "debian-base",
  "version": 2,
  "description": "My custom Debian 7",
  "author": "frontend@testbed.lan",
  "visibility": "shared",
  "destructive": false,
  "os": "linux",
  "image": {
    "file": "/home/frontend/debian-base.tgz",
    "kind": "tar",
    "compression": "gzip"
  },
  "postinstalls": [
    {
      "archive": "/home/frontend/debian-base-postinstall.tgz",
      "compression": "gzip",
      "script": "traitement.ash /rambin"
    }
  ],
  "boot": {
    "kernel": "/vmlinuz",
    "initrd": "/initrd.img"
  },
  "filesystem": "ext3",
  "partition_type": 83,
  "multipart": false
}

Example #3

{
  "environment": {
    "name": "debian-base",
    "version": 2,
    "multipart": true,
    "os": "linux",
    "image": {
      "file": "server:///tmp/debian-base.fsa",
      "kind": "fsa",
      "compression": 3
    },
    "boot": {
      "kernel": "/vmlinuz",
      "initrd": "/initrd.img",
      "block_device": "/dev/sda",
      "partition": 2
    },
    "filesystem": "ext3",
    "options": {
      "partitions": [
        {
          "id": 0,
          "device": "/dev/sda1"
        },
        {
          "id": 1,
          "device": "/dev/sda2"
        },
        {
          "id": 2,
          "device": "/dev/sda3"
        }
      ]
    }
  }
}

POST /environments

Request (Hash, application/json)

Parameters

NameTypeKindDescription
{environment}HashMandatoryThe environment to add
clientStringOptionalThe client used to export files to the server, useful for local:// files (see more here)
{environment}.{image}HashMandatoryThe image file that contains the environment
{environment}.nameStringMandatoryThe name of the environment
{environment}.osStringMandatoryThe operating system of the environment
Expected values: linux, xen, other
{environment}.authorStringOptionalThe author of the environment
Default value: empty string
{environment}.{boot}HashOptionalThe environment's boot parameters
{environment}.descriptionStringOptionalThe description of the environment
Default value: empty string
{environment}.destructiveBooleanOptionalThe environment destruct the disk partitioning
Default value: false
{environment}.filesystemStringOptionalThe filesystem type of the environment, useful for tar environments
Default value: empty string
{environment}.multipartBooleanOptionalThe environment image is a multi-partitioned archive
Default value: false
{environment}.optionsStringOptionalCustom options
{environment}.partition_typeStringOptionalThe partition type that will be set when partitioning the disk
Default value: 0
{environment}.[postinstalls]ArrayOptionalA list of postinstall script archives
{environment}.{preinstall}HashOptionalA preinstall script archive
{environment}.versionIntegerOptionalThe version of the environment
Default value: 1
{environment}.visibilityStringOptionalThe visibility of the environment
Expected values: public, private, shared
Default value: private
{environment}.{boot}.block_deviceStringOptionalThe block device environment should be installed on, useful for multi-partitioned environments
Default value: empty string
{environment}.{boot}.deploy_partStringOptionalThe partition the environment should be installed on, useful for multi-partitioned environments
Default value: empty string
{environment}.{boot}.hypervisorStringOptionalPath to the hypervisor file (inside the environment\s image), useful when deploying Xen environments
Default value: empty string
{environment}.{boot}.hypervisor_paramsStringOptionalThe parameters to be given to the hypervisor at launch time, useful when deploying Xen environments
Default value: empty string
{environment}.{boot}.initrdStringOptionalPath to the initrd file (inside the environment\s image)
Default value: empty string
{environment}.{boot}.kernelStringOptionalPath to the kernel file (inside the environment\s image)
Default value: empty string
{environment}.{boot}.kernel_paramsStringOptionalThe parameters to be given to the kernel at launch time
Default value: empty string
{environment}.{image}.compressionStringMandatoryThe compression algorithm used to compress the image
Expected values: gzip, bzip2, xz
{environment}.{image}.fileStringMandatoryThe path to the image file (see more here)
{environment}.{image}.kindStringMandatoryThe kind of image
Expected values: tar, dd, fsa
{environment}.options.[partitions]ArrayOptionalA list of id/partition association
{environment}.options.[partitions].deviceStringMandatoryThe physical device this archive part should be installed on
{environment}.options.[partitions].idIntegerMandatoryThe id of the partition inside the compressed archive
{environment}.[postinstalls].{#i}.compressionStringMandatoryThe compression algorithm used to compress the archive
Expected values: gzip, bzip2, xz
{environment}.[postinstalls].{#i}.fileStringMandatoryThe path to the archive file (see more here)
{environment}.[postinstalls].{#i}.scriptStringMandatoryPath to a script (inside the archive) that will be launched during the post-install step
Default value: none
{environment}.[postinstalls].{#i}HashOptionalA postinstall script archive
{environment}.{preinstall}.compressionStringMandatoryThe compression algorithm used to compress the archive
Expected values: gzip, bzip2, xz
{environment}.{preinstall}.fileStringMandatoryThe path to the archive file (see more here)
{environment}.{preinstall}.scriptStringMandatoryPath to a script (inside the archive) that will be launched during the pre-install step
Default value: none

Response (Hash, application/json)

Fields

NameTypeDescription
EnvironmentThe environment that was added

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
400-6Invalid environment, something went wrong with the environment description checking, check the error message
400-9Invalid content, check your JSON's structure
400-10Already existing element, an environment with the same user/name/version already exists
400-12Nothing modified

Example #1 Create a basic environment (the image's archive is exported from the client to the server)

Example #2 Create a minimal environment (the image's archive is accessible on HTTP)

Example #3 Create a multi-partitioned environment (the image's archive is stored on the server)


GET /environments?username=:username?&name=:name?&version=:version?

Gather the description of environments. If no user is given, the public environment will be displayed, otherwise a list of all environments that are public or owned by the user will be returned. The :username or the :name fields have to be encoded following the RFC 3986 specifications (non-ASCII characters are encoded with a percent notation)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
nameStringOptionalThe name of the environment
usernameStringOptionalThe owner of the environment
versionStringOptionalThe version of the environment
lastSetOptionalShow the last version of environments (by default every versions are returned)

Response (Array, application/json)

Fields

NameTypeDescription
#iEnvironmentOne of the environment that were matching the request's parameters

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the resource you are looking for cannot be found

Example #1 Get the list of all visible environments

Example #2 Get the list of the environments a specified user can see

Example #3 Get the description of a specific environment

Example #4 Get the description of a specific version of a specific environment

Example #5 Get the description of every debian-custom


PUT /environments/:username/:name/:version?

Modify some environment(s) properties, returns the modified environment. If no version is specified, modify the last version. The :username or the :name fields have to be encoded following the RFC 3986 specifications (non-ASCII characters are encoded with a percent notation)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
nameStringOptionalThe name of the environment, mandatory if the operation is not update_file
usernameStringOptionalThe owner of the environment, mandatory if the operation is not update_file
versionStringOptionalThe version of the environment
clientStringOptionalThe client used to export files to the server, needed to update the checksum of local:// files (see more here)
toggle_destructiveSetOptionalToggle the destructive flag
update_image_checksumSetOptionalUpdate the checksum of the image's archive in the database (the server will get the checksum of the recorded archive file)
update_postinstalls_checksumSetOptionalUpdate the checksum of the preinstall's archive(s) in the database (the server will get the checksum of the recorded archive file)
update_preinstall_checksumSetOptionalUpdate the checksum of the preinstall's archive in the database (the server will get the checksum of the recorded archive file)
visibilityStringOptionalSet the visibility of the environment

Response (Hash/Array, application/json)

Fields

NameTypeDescription
EnvironmentThe environment that was modified

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
400-9Invalid content, check your JSON's structure
400-12Nothing modified

Example #1 Change the visibility flag of an environment

Example #2 Tell the server to gather the new checksum of the image's archive


PUT /environments/:username?/:name?/:version?

Modify some environment(s) properties, returns the modified environment. If no version is specified, modify the last version. The :username or the :name fields have to be encoded following the RFC 3986 specifications (non-ASCII characters are encoded with a percent notation)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
nameStringOptionalThe name of the environment, mandatory if the operation is not update_file
usernameStringOptionalThe owner of the environment, mandatory if the operation is not update_file
versionStringOptionalThe version of the environment
clientStringOptionalThe client used to export files to the server, needed to update the checksum of local:// files (see more here)
{update_files}HashOptionalBatch renaming of file's paths, admins only
{update_files}.old_path_prefixStringMandatoryThe new path prefix

Response (Hash/Array, application/json)

Fields

NameTypeDescription
EnvironmentThe environment that was modified

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
400-9Invalid content, check your JSON's structure
400-12Nothing modified

Example #1 Change the path to some files on all the environments


DELETE /environments/:username/:name/:version?

Delete a specific environment, returns the resources that was deleted. The :username or the :name fields have to be encoded following the RFC 3986 specifications (non-ASCII characters are encoded with a percent notation)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
nameStringOptionalThe name of the environment
usernameStringOptionalThe owner of the environment
versionStringOptionalThe version of the environment

Response (Hash/Array, application/json)

Fields

NameTypeDescription
EnvironmentThe environment(s) that was deleted

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
400-12Nothing modified, no environment was deleted (none were matching the conditions)

Example #1 Delete every versions of a specific environment

Example #2 Delete a specific version of an environment



Global information


GET /clusters

Get the list of clusters

Request (Hash, application/json)

Parameters

NameTypeKindDescription

Response (Array, application/json)

Fields

NameTypeDescription
#iStringThe name of the cluster #i

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Get the list of clusters


GET /auth_headers_prefix

Get information about the authentication HTTP headers of the running service

Request (Hash, application/json)

Parameters

NameTypeKindDescription

Response (String, text/plain)

Fields

NameTypeDescription
StringThe prefix that have to be specified in the HTTP headers when doing a request (for authentication purpose)

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

GET /info

Get information about the configuration of the running service

Request (Hash, application/json)

Parameters

NameTypeKindDescription

Response (Hash, application/json)

Fields

NameTypeDescription
{automata}HashThe configuration of the deployment automata
{automata}.{clustername}HashThe configuration of the deployment automata for the cluster "clustername"
{automata}.{clustername}.[macrostepkind]ArrayThe configuration of the instances of the step "macrostepkind"
{automata}.{clustername}.[macrostepkind].{#i}HashThe configuration of the instances #i
{automata}.{clustername}.[macrostepkind].{#i}.nameStringThe name of the instance
{automata}.{clustername}.[macrostepkind].{#i}.retriesIntegerThe number of retries for the instance
{automata}.{clustername}.[macrostepkind].{#i}.timeoutIntegerThe timeout of the instance
pxeStringThe netboot method configured on the server
{supported_fs}HashThe filesystem format supported by the deployment environment of the different clusters
{supported_fs}.[clustername]ArrayThe filesystem format supported by the deployment environment of the cluster "clustername"
{supported_fs}.[clustername].#formatStringThe filesystem format name
[vars]ArrayThe environment variables exported by the deployment environment when running custom scripts
[vars].#nameStringThe variable name

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Get information about the service's configuration


GET /version

Get the version of the server

Request (Hash, application/json)

Parameters

NameTypeKindDescription

Response (String, text/plain)

Fields

NameTypeDescription
StringThe version of the server

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Get the version of the server "kadeploy.testbed.lan"



Deployment


POST /deployment

Launch a deployment

Request (Hash, application/json)

Parameters

NameTypeKindDescription
{environment}HashMandatoryThe environment that have to be deployed
[nodes]ArrayMandatoryThe list of nodes the operation should be applied on
_generic_parameter_...OptionalSome workflow-based operation's generic parameter (see more here)
{automata}HashOptional...
block_deviceStringOptionalThe block device the environment should be installed on
boot_partitionIntegerOptionalThe partition the node have to boot on (useful when deploying an image of the whole disk
clientStringOptionalThe client used to export files to the server, useful for local:// files (see more here)
deploy_partitionIntegerOptionalThe partition the environment should be installed on
disable_bootloader_installSetOptionalDisable the install of a bootloader on the partition the image is installed on
disable_disk_partitioningSetOptionalDisable the disk partitioning step
{pxe}HashOptionalSpecify some custom netboot parameters
reformat_tmp_partitionStringOptionalReformat the partition that was defined as the tmp partition with the specified format
ssh_authorized_keysStringOptionalThe path to a ssh authorized_keys file that have to be copied in the root directory of the deployed environment (see more here)
timeout_reboot_classicalIntegerOptionalOverwrite the default value for the reboot timeout
timeout_reboot_kexecIntegerOptionalOverwrite the default value for the kexec timeout
vlanStringOptionalSpecify the VLAN the nodes should be reboot in
{environment}.kindStringMandatoryThe kind of environment, recorded or anonymous
Expected values: anon, database
{environment}.nameStringMandatoryThe name of the environment
{environment}.fieldsEnvironmentOptionalOther fields that are used to describe an anonymous environment
{environment}.userStringOptionalThe owner of the environment
{environment}.versionStringOptionalThe version of the environment
{pxe}.[files]ArrayOptionalA list of path to files that have to be exported in the PXE repository's directory (see more here)
{pxe}.profileStringOptionalA custom PXE profile, the string FILES_PREFIX-- will be replaced by the prefix to some exported files
{pxe}.{singularities}HashOptionalSpecify a substitution pattern for each node in the PXE profile (the NODE_SINGULARITY pattern must be used in the PXE profile)
{pxe}.{singularities}.nodenameStringOptionalThe substitution pattern for the node "nodename"

Response (Hash, application/json)

Fields

NameTypeDescription
WorkflowInformation related to the workflow of the deployment

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Deploy a recorded environment using the user specified key file

Example #2 Deploy an anonymous local environment

Example #3 Deploy an anonymous HTTP environment

Example #4 Deploy a recorded environment and reboot the nodes on a custom kernel with some nodes singularities

Example #5 Deploy an environment and overwrite the automata's steps



Console


POST /console

Create a console binding. The server will create a TCP channel to bind the console inputs/outputs.
To create an interactive shell, you can use a command such as:
stty raw -echo; nc HOST PORT; stty -raw echo

Request (Hash, application/json)

Parameters

NameTypeKindDescription
nodeStringMandatoryThe node to establish the console to

Response (Hash, application/json)

Fields

NameTypeDescription
idStringThe id# of the operation (prefixed by "C-")
{resources}HashResources related to the workflow
{resources}.consoleStringURI to the TCP channel used to bind the console inputs/outputs
{resources}.errorStringURI to the error
{resources}.resourceStringURI to the resource

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Require a console connection on node-1. You can then


GET /console

Get the workflow information of every running operation of the kind console

Request (Hash, application/json)

Parameters

NameTypeKindDescription

Response (Hash, application/json)

Fields

NameTypeDescription
{#i}HashInformation about the workflow #i
{#i}.attachedBooleanSet to true if the TCP channel is in use. Only available to the users that have the rights to consult the information about this operation.
{#i}.console_uriStringURI to the TCP channel used to bind the console inputs/outputs. Only available to the users that have the rights to consult the information about this operation.
{#i}.errorBooleanSet to true if an error was encountered. The error message can be obtained by getting /console/:id/error. Only available to the users that have the rights to consult the information about this operation.
{#i}.idStringThe id# of the operation (prefixed by "C-")
{#i}.nodeStringThe node the console is open to
{#i}.timeFloatThe time elapsed since the start of the operation.
{#i}.userStringThe user that initiated the operation

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Get the list of consoles


GET /console/:id

Get the workflow information of an operation

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation

Response (Hash, application/json)

Fields

NameTypeDescription
attachedBooleanSet to true if the TCP channel is in use. Only available to the users that have the rights to consult the information about this operation.
console_uriStringURI to the TCP channel used to bind the console inputs/outputs. Only available to the users that have the rights to consult the information about this operation.
errorBooleanSet to true if an error was encountered. The error message can be obtained by getting /console/:id/error. Only available to the users that have the rights to consult the information about this operation.
idStringThe id# of the operation (prefixed by "C-")
nodeStringThe node the console is open to
timeFloatThe time elapsed since the start of the operation.
userStringThe user that initiated the operation

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Get information about a console


GET /console/:id/error

Get the error of an operation (the "error" field was set to true on the workflow's info)

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation

Response (String, text/plain)

Fields

NameTypeDescription
StringThe error message

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body
404File not found, the workflow :id cannot be found

DELETE /console/:id

Destroy a console binding (the TCP channel will be closed).

Request (Hash, application/json)

Parameters

NameTypeKindDescription
idStringMandatoryThe id# of the operation

Response (Hash, application/json)

Fields

NameTypeDescription
idStringThe id# of the operation (prefixed by "C-")

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Destroy a console binding



Power operations


PUT /power

Launch a power operation

Request (Hash, application/json)

Parameters

NameTypeKindDescription
[nodes]ArrayMandatoryThe list of nodes the operation should be applied on
statusStringMandatoryThe status to be applied
Expected values: on, off
_generic_parameter_...OptionalSome workflow-based operation's generic parameter (see more here)
levelStringOptionalThe level of the command that will be performed
Expected values: soft, hard, very_hard
Default value: soft

Response (Hash, application/json)

Fields

NameTypeDescription
WorkflowInformation related to the workflow of the power operation

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Perform a power-on on some nodes

Example #2 Perform a hard power-off on some nodes


GET /power

Get the power status of some nodes

Request (Hash, application/json)

Parameters

NameTypeKindDescription
[nodes]ArrayMandatoryThe list of nodes the power status should be returned

Response (Hash, application/json)

Fields

NameTypeDescription
WorkflowInformation related to the workflow of the power operation

Return codes

Code#Description
200OK, the request is successful
500Internal Server Error, an uncatched exception was thrown on the server
400Bad Request, Kadeploy Error: please check the X-Application-Error-Code and X-Application-Error-Code headers
401Unauthorized, you need to be authenticated
403Forbidden, you do not the rights to perform this operation. Unlike a 401 Unauthorized response, authenticating will make no difference.
415Unsupported Media Type, check the Content-Type of your request's body

Example #1 Get the power-status of some nodes