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"
}
Cluster Members¶
Endpoint: /api/v0/cluster/{NAME}/hosts
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']
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
}
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
}
Cluster Operations: Restart¶
Endpoint: /api/v0/cluster/{NAME}/restart
(Internal model name: ClusterRestart)
ContainerManagers¶
Endpoint: /api/v0/containermanagers/
(Internal model name: ContainerManagerConfig)
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/"
},
}
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"
}
]
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"
},
}