Docker integration API

The Docker Integration API extends the core REST API, adding interactions that are required in the context of the Corus/Docker integration.

Listing Images

This call is similar to the docker ls command in the Corus CLI. Note that it takes optional n parameters for filtering images by name, just like the CLI.

GET
- Permission.....: READ
- Behavior.......: SYNC
- Request headers:
  - Accept......: application/json

- Resources:
  /clusters/{clusterName}/docker/images
  /clusters/{clusterName}/hosts/{host}/docker/images
  /clusters/{clusterName}/partitionsets/{partitionSetId}/partitions/{partitionIndex}/docker/images

- Path variables:
  - clusterName...: the name of the cluster to access.
  - host..........: a host literal (taking the form: ip_address:port).
  - partitionSetId: the ID of the partition set to target.
  - partitionIndex: the index of the partition in the targeted partition set.    
  
- Parameters:
  - n (optional): an image name (pattern matching supported).

Sample requests

http://saturn:33000/rest/clusters/app-01/docker/images
http://saturn:33000/rest/clusters/app-01/hosts/192.168.0.104:33000/docker/images 
http://saturn:33000/rest/clusters/app-01/docker/images?n=**memcached
http://saturn:33000/rest/clusters/app-01/partitionsets/8d450417-cbee-4e58-9533-ab7a0966042a/partitionIndex/0/docker/images

Sample response

[
  {
    "cluster": "app-01",
    "host": "192.168.0.103:33000",
    "dataType": "dockerImage",
    "data": {
      "id": "1d073211c4981d073211c4981d073211c4981d073211c498",
      "creationTimeStamp": "12883778929",
      "tags": ["latest"]
    }
  }
]

Note that name patterns are shown as taking double-asterisks (**): that is because Docker image name can contain forward-slashes (/) and the pattern format conforms to glob patterns. Therefore: * would match memcached, but not mini/memcached. In turn, either */* or ** would match mini/memcached.

Downloading Image Tarballs

This call is similar to the docker save command in the Corus CLI. It only suppports interaction with a single host (evidently). The resource will return the content (the bytes of a tarball) of a requested Docker image.

GET
- Permission.....: READ
- Behavior.......: SYNC
- Request headers:
  - Accept......: application/octet-stream

- Resources:
  /clusters/{clusterName}/hosts/{host}/docker/images/{imageName}/payload

- Path variables:
  - clusterName...: the name of the cluster to access.
  - imageName.....: the name of the image whose payload (tarball content) should be returned.
  - host..........: a host literal (taking the form: ip_address:port).

Sample requests

http://saturn:33000/rest/clusters/app-01/hosts/192.168.0.104:33000/docker/images/[mini/memcached:latest]/payload

Note that image names containing a forward-slash (/) must be enclosed within square brackets, in order to avoid such names being confused with paths to REST resources.

Deploying Images

This call is similar to the CLI's deploy -docker command.

PUT
- Permission......: DEPLOY
- Behavior........: SYNC/ASYNC with polling
- Request headers:
  - Accept........: application/json
  - Content-Type..: application/octet-stream
  - Content-Length: <payload_size_in_bytes>

- Resources:
  /clusters/{clusterName}/docker/images/{imageName}
  /clusters/{clusterName}/hosts/{host}/docker/images/{imageName}
  /clusters/{clusterName}/partitionsets/{partitionSetId}/partitions/{partitionIndex}/docker/images/{imageName}

- Path variables:
  - clusterName...: the name of the cluster to access.
  - imageName.....: the name to assign to the uploaded image payload.
  - host..........: a host literal (taking the form: ip_address:port).
  - partitionSetId: the ID of the partition set to target.
  - partitionIndex: the index of the partition in the targeted partition set.
  
- Parameters:
  - async (optional).........: If the value is set to true, execution will be performed asynchronously. 
  - batchSize (optional).....: If specified, indicates that graceful deployment should be performed. More 
                               precisely: tells to how many hosts at a time deployment should be done.
  - minHosts (optional)......: Used in the context of graceful deployment (see previous param): indicates
    							             at least how many hosts should be present in the cluster for the given
                               batch size to apply. If that minimum is not observed, the batch size internally
                               used will then be 1 (meaning deployment will be done to one host at a time).
  - maxErrors (optional).....: The maximum number of batch errors to tolerate before the operation is aborted.

The request's body is expected to be a stream of bytes corresponding to the tarball of the image to deploy

Pulling Images

This call is similar to the CLI's docker pull command (it triggers the pull of a given image from the Docker registry).

POST
- Permission......: DEPLOY
- Behavior........: SYNC/ASYNC with polling
- Request headers:
  - Accept........: application/json

- Resources:
  /clusters/{clusterName}/docker/images/{imageName}
  /clusters/{clusterName}/hosts/{host}/docker/images/{imageName}
  /clusters/{clusterName}/partitionsets/{partitionSetId}/partitions/{partitionIndex}/docker/images/{imageName}

- Path variables:
  - clusterName...: the name of the cluster to access.
  - imageName.....: the name of the image to pull.
  - host..........: a host literal (taking the form: ip_address:port).
  - partitionSetId: the ID of the partition set to target.
  - partitionIndex: the index of the partition in the targeted partition set.
  
- Parameters:
  - async (optional).........: If the value is set to true, execution will be performed asynchronously. 
  - batchSize (optional).....: If specified, indicates that graceful deployment should be performed. More 
                               precisely: tells to how many hosts at a time deployment should be done.
  - minHosts (optional)......: Used in the context of graceful deployment (see previous param): indicates
    							             at least how many hosts should be present in the cluster for the given
                               batch size to apply. If that minimum is not observed, the batch size internally
                               used will then be 1 (meaning deployment will be done to one host at a time).
  - maxErrors (optional).....: The maximum number of batch errors to tolerate before the operation is aborted.

http://saturn:33000/rest/clusters/app-01/docker/images/[mini/memcached:latest]
http://saturn:33000/rest/clusters/app-01/hosts/192.168.0.104:33000/docker/images/[mini/memcached:latest]
http://saturn:33000/rest/clusters/app-01/distributions?n=**
http://saturn:33000/rest/clusters/app-01/partitionsets/8d450417-cbee-4e58-9533-ab7a0966042a/partitionIndex/0/docker/images/[mini/memcached:latest]

Note that image names containing a forward-slash (/) must be enclosed within square brackets, in order to avoid such names being confused with paths to REST resources.

Undeploying Images

This call is similar to the CLI's docker rm command (it forces the removal of an image from the Docker daemon).

DELETE
- Permission.....: DEPLOY
- Behavior.......: SYNC/ASYNC with pollling
- Request headers:
  - Accept......: application/json

- Resources:
  /clusters/{clusterName}/docker/images
  /clusters/{clusterName}/hosts/{host}/docker/images
  /clusters/{clusterName}/partitionsets/{partitionSetId}/partitions/{partitionIndex}/docker/images  

- Path variables:
  - clusterName: the name of the cluster to access.
  - host.......: a host literal (taking the form: ip_address:port).
  - partitionSetId: the ID of the partition set to target.
  - partitionIndex: the index of the partition in the targeted partition set.
  
- Parameters:
  - async (optional)........: If the value is set to true, execution will be performed asynchronously. 
  - maxErrors (optional)....: The maximum number of batch errors to tolerate before the operation is aborted. 
  - n.......................: The name of the image to undeploy (pattern matching supported)

Sample requests

http://saturn:33000/rest/clusters/app-01/docker/images?n=**memcached
http://saturn:33000/rest/clusters/app-01/hosts/192.168.0.104:33000/docker/images?n=mini/memcached
http://saturn:33000/rest/clusters/app-01/distributions?n=**
http://saturn:33000/rest/clusters/app-01/partitionsets/8d450417-cbee-4e58-9533-ab7a0966042a/partitionIndex/0/docker/images?n=mini/memcached

Note that name patterns are shown as taking double-asterisks (**): that is because Docker image name can contain forward-slashes (/) and the pattern format conforms to glob patterns. Therefore: * would match memcached, but not mini/memcached. In turn, either */* or ** would match mini/memcached.