REST Endpoints

REST stands for representational state transfer and is one of many ways to expose API’s as a web service. REST allows “requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations. [...] Using HTTP, as is most common, the kind of operations available include those predefined by the HTTP verbs GET, POST, PUT, DELETE and so on.” (Wikipedia)

For more information on REST see the original dissertation.

Cluster

Endpoint: /api/v0/cluster/{NAME}

(Internal model name: Cluster)

Changed in version 0.1.0: type has been removed in favor of container_manager.

GET

Retrieve the status of the cluster.

{
    "name": string,
    "status" string,
    "network": string,
    "container_manager": str,
    "hosts": {
        "total": int,
        "available": int,
        "unavailable": int
    }
}

Example

{
    "name": "mycluster",
    "status": "ok",
    "network": "default",
    "container_manager": "prod_openshift",
    "hosts": {
        "total": 3,
        "available": 2,
        "unavailable": 1
    }
}

PUT

Creates a new cluster.

Deprecated since version 0.0.1: Provide a network when creating a new Cluster.

{
    "container_manager": string // (Optional) Name of the container manager to use
    "network": string     // The name of the network
}

Example

{
    "container_manager": "prod_openshift",
    "network": "default"
}

DELETE

Deletes an existing cluster.

Example Response

[]

Cluster Members

Endpoint: /api/v0/cluster/{NAME}/hosts

GET

Retrieve the host list for a cluster.

[
    host_address,...
]

Example

[
    "192.168.100.50",
    "192.168.100.51"
]

PUT

Replace the host list for a cluster. The “old” list must match the current host list.

{
    "old": [host_address,...]
    "new": [host_address,...]
}

Example

{
    "old": ["192.168.100.50"],
    "new": ["192.168.100.50", "192.168.100.51"]
}

Cluster Members (Individual)

Endpoint: /api/v0/cluster/{NAME}/hosts/{IP}

GET

Membership test. Returns 200 if host {IP} is in cluster, else 404.

Example Response

['192.168.100.50']

PUT

Adds host {IP} to cluster and returns the host added in a list. (Idempotent)

No body.

Example Response

['192.168.100.50']

DELETE

Removes host {IP} from cluster returning an empty list. (Idempotent)

No body.

Example Response

[]

Cluster Operations: Deploy

Endpoint: /api/v0/cluster/{NAME}/deploy

(Internal model name: ClusterDeploy)

GET

Retrieve the current status of an OSTree tree deployment.

{
    "status": string,
    "version": string,
    "deployed": HOST_LIST,
    "in_process": HOST_LIST,
    "started_at": string,
    "finished_at": string
}

Example

{
    "status": "in_process",
    "version": "7.2.6",
    "deployed": [{...}],
    "in_process": [{...}],
    "started_at": "2015-12-17T15:48:18.710454",
    "finished_at": null
}

PUT

Start a new OSTree tree deployment.

{
    "version": string  // Which OSTree tree to deploy
}

Example

{
    "version": "7.2.6"
}

Example Response

{
    "status": "in_process",
    "version": "7.2.6",
    "deployed": [{...}],
    "in_process": [{...}],
    "started_at": "2015-12-17T15:48:18.710454",
    "finished_at": null
}

Cluster Operations: Upgrade

Endpoint: /api/v0/cluster/{NAME}/upgrade

(Internal model name: ClusterUpgrade)

GET

Retrieve the current status of upgrades.

{
    "status": string,
    "upgraded": HOST_LIST,
    "in_process": HOST_LIST,
    "started_at": string,
    "finished_at": string
}

Example

{
    "status": "in_process",
    "upgraded": [{...}],
    "in_process": [{...}],
    "started_at": "2015-12-17T15:48:18.710454",
    "finished_at": null
}

PUT

Start a new upgrade.

No body.

Example Response

{
    "status": "in_process",
    "upgraded": [{...}],
    "in_process": [{...}],
    "started_at": "2015-12-17T15:48:18.710454",
    "finished_at": null
}

Cluster Operations: Restart

Endpoint: /api/v0/cluster/{NAME}/restart

(Internal model name: ClusterRestart)

GET

Retrieve the status of a restart.

{
    "status": string,
    "restarted": HOST_LIST,
    "in_process": HOST_LIST,
    "started_at": string,
    "finished_at": string
}

Example

{
    "status": "in_process",
    "restarted": [{...}],
    "in_process": [{...}],
    "started_at": "2015-12-17T15:48:18.710454",
    "finished_at": null
}

PUT

Create a new restart.

No body.

Example Response

{
    "status": "in_process",
    "restarted": [{...}],
    "in_process": [{...}],
    "started_at": "2015-12-17T15:48:18.710454",
    "finished_at": null
}

Clusters

Endpoint: /api/v0/cluster/

(Internal model name: Clusters)

GET

Retrieve a list of all clusters.

[
    string,...
]

Example

[
   "mycluster",
]

ContainerManagers

Endpoint: /api/v0/containermanagers/

(Internal model name: ContainerManagerConfig)

GET

Retrieve a list of all configured ContainerManagers.

[
    string,...
]

Example

[
   "prod_openshift",
]

ContainerManagerConfig

Endpoint: /api/v0/containermanager/{name}

(Internal model name: ContainerManagerConfig)

GET

Retrieve a specific ContainerManagerConfig record.

{
    "name": string,        // The name of the ContainerManagerConfig
    "type":  enum(string), // The type of the ContainerManagerConfig
    "options": dict        // Options to configure a ContainerManagerConfig
}

Note

See ContainerManager Types for a list and description of ContainerManager types.

Example

{
    "name": "prod_openshift",
    "type": "openshift",
    "options": {
        "apiserver": "https://192.168.152.101:8080/api/"
    },
}

PUT

Creates a new ContainerManagerConfig record.

{
    "name": str,           // Name of the ContainerManagerConfig
    "type":  enum(string), // The type of the ContainerManagerConfig
    "options": dict        // Options to explain a ContainerManagerConfig
}

Note

See ContainerManager Types for a list and description of ContainerManager types.

Example

{
    "type": "openshift",
    "options": {
        "apiserver": "https://192.168.152.101:8080/api/"
    },
}

DELETE

Deletes a ContainerManagerConfig record. (Idempotent)

No body.

Example Response

[]

Host

Endpoint: /api/v0/host/{IP}

(Internal model name: Host)

GET

Retrieve a specific host record.

{
    "address": string,       // The IP address of the cluster host
    "status":  enum(string), // The status of the cluster host
    "os": enum(string),      // The OS name
    "cpus": int,             // The number of CPUs on the cluster host
    "memory": int,           // The memory of the cluster host in kilobytes
    "space": int,            // The diskspace on the cluster host
    "last_check": string,    // ISO date format the cluster host was last checked
    "source": string         // (optional) External source for host information
}

Note

See Host Statuses for a list and description of host statuses.

Note

See OS’s for a list and description of host statuses.

The source value, if defined, names a storage plugin which can provide information for this particular Host record. If omitted, host information is obtained from the default storage plugin defined by Commissaire’s storage configuration.

Example

A host owned by Commissaire.

{
    "address": "192.168.100.50",
    "status": "active",
    "os": "atomic",
    "cpus": 4,
    "memory": 11989228,
    "space": 487652,
    "last_check": "2015-12-17T15:48:18.710454",
    "source": ""
}

A host owned by an external provider (note the "source" field).

{
    "address": "192.168.100.50",
    "status": "active",
    "os": "fedora",
    "cpus": 4,
    "memory": 2048,
    "space": 51475068,
    "last_check": "2016-11-28T22:10:11.851787",
    "source": "cloudforms"
}

PUT

Creates a new host record.

{
    "ssh_priv_key": string, // base64 encoded ssh private key
    "remote_user": string,  // Optional name of ssh user to use (default=root)
    "cluster": string      // Optional cluster the host should be associated with
}

Note

The rest of the host record will be filled out once the data has been pulled from the cluster host.

Note

As a convenience to hosts wishing to add themselves as part of a boot script, the endpoint /api/v0/host (without the {IP}) also accepts PUT requests. Here, the host address is inferred from the request itself but otherwise works the same: creates a new host record accessible at /api/v0/host/{IP}.

Example

{
    "cluster": "default",
    "remote_user": "root",
    "ssh_priv_key": "dGVzdAo..."
}

DELETE

Deletes a host record.

HostCreds

Endpoint: /api/v0/host/{IP}/creds

GET

Retrieve a specific hosts credentials.

{
    "ssh_priv_key": string, // base64 encoded ssh private key
    "remote_user":  string, // name of ssh user to use for connections
}

HostStatus

Endpoint: /api/v0/host/{IP}/status

(Internal model name: HostStatus)

GET

Retrieve a specific hosts status.

{
    "type":               string, // type of status
    "host":               dict,   // status elements from the Host instance
    "container_manager":  dict,   // status elements reported from the Container Manager
}

Example: Default

{
    "type": "host_only",
    "host": {
        "last_check": "2016-07-29T19:54:57.204671",
        "status": "active",
    },
    "container_manager": {...}
}

Hosts

Endpoint: /api/v0/hosts

(Internal model name: Hosts)

GET

Retrieve a list of hosts.

[
    {
        "address": string,       // The IP address of the cluster host
        "status":  enum(string), // The status of the cluster host
        "os": enum(string),      // The OS name
        "cpus": int,             // The number of CPUs on the cluster host
        "memory": int,           // The memory of the cluster host in kilobytes
        "space": int,            // The diskspace on the cluster host
        "last_check": string     // ISO date format the cluster host was last checked
    }...
]

Note

See Host Statuses for a list and description of host statuses.

Note

See OS’s for a list and description of host statuses.

Example

[
    {
        "address": "192.168.100.50",
        "status": "active",
        "os": "atomic",
        "cpus": 4,
        "memory": 11989228,
        "space": 487652,
        "last_check": "2015-12-17T15:48:18.710454"
    },
    {
        "address": "192.168.100.51",
        "status": "active",
        "os": "atomic",
        "cpus": 3,
        "memory": 11989228,
        "space": 487652,
        "last_check": "2015-12-17T15:48:30.401090"
    }
]

Networks

Endpoint: /api/v0/networks/

(Internal model name: Networks)

GET

Retrieve a list of all networks.

[
    string,...
]

Example

[
   "mynetwork",
]

Network

Endpoint: /api/v0/network/{name}

(Internal model name: Network)

GET

Retrieve a specific network record.

{
    "name": string,        // The name of the network
    "type":  enum(string), // The type of the network
    "options": dict        // Options to explain a network
}

Note

See network-types for a list and description of network types.

Example

{
    "name": "mynetwork",
    "type": "flannel_server",
    "options": {
        "address": "192.168.152.101:8080"
    },
}

PUT

Creates a new network record.

{
    "type":  enum(string), // The type of the network
    "options": dict        // Options to explain a network
}

Note

See network-types for a list and description of network types.

Example

{
    "type": "flannel_server",
    "options": {
        "address": "192.168.152.101:8080"
    },
}

DELETE

Deletes a network record. (Idempotent)

No body.

Example Response

[]