Container Infrastructure Management API

updated: 'Fri Jun 16 16:14:28 2017, commit 907415c'

Container Infrastructure Management API

API Versions

In order to bring new features to users over time, the Magnum API supports versioning. There are two kinds of versions in Magnum.

  • ”major versions”, which have dedicated urls
  • ”microversions”, which can be requested through the use of the OpenStack-API-Version.

Beginning with the Newton release, all API requests support the OpenStack-API-Version header. This header SHOULD be supplied with every request; in the absence of this header, each request is treated as though coming from an older pre-Newton client. This was done to preserve backwards compatibility as we introduced new features.

The Version APIs work differently from other APIs as they do not require authentication.

GET
/

List API Versions

This fetches all the information about all known major API versions in the deployment. Links to more specific information will be provided for each API version, as well as information about supported min and max microversions.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
503 - Service Unavailable Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
versions body string The version.
status body string

The status of this API version. This can be one of:

  • CURRENT: this is the preferred version of the API to use
  • SUPPORTED: this is an older, but still supported version of the API
  • DEPRECATED: a deprecated version of the API that is slated for removal
min_version body string If this version of the API supports microversions, the minimum microversion that is supported. This will be the empty string if microversions are not supported.
max_version body string If this version of the API supports microversions, the maximum microversion that is supported. This will be the empty string if microversions are not supported.
id body string A common name for the version in question. Informative only, it has no real semantic meaning.
links body array Links to the resources in question.
name body string Name of the resource.
description body string Descriptive text about the Magnum service.

Response Example

{
   "versions":[
      {
         "status":"CURRENT",
         "min_version":"1.1",
         "max_version":"1.4",
         "id":"v1",
         "links":[
            {
               "href":"http://10.164.180.104:9511/v1/",
               "rel":"self"
            }
         ]
      }
   ],
   "name":"OpenStack Magnum API",
   "description":"Magnum is an OpenStack project which aims to provide container management."
}
GET
/v1/

Show v1 API Version

Show all the resources within the Magnum v1 API.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
503 - Service Unavailable Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
id body string A common name for the version in question. Informative only, it has no real semantic meaning.
links body array Links to the resources in question.

Note

The media-types parameters in the response are vestigial and provide no useful information. They will probably be deprecated and removed in the future.

Response Example

{
   "media_types":[
      {
         "base":"application/json",
         "type":"application/vnd.openstack.magnum.v1+json"
      }
   ],
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/",
         "rel":"self"
      },
      {
         "href":"http://docs.openstack.org/developer/magnum/dev/api-spec-v1.html",
         "type":"text/html",
         "rel":"describedby"
      }
   ],
   "mservices":[
      {
         "href":"http://10.164.180.104:9511/v1/mservices/",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/mservices/",
         "rel":"bookmark"
      }
   ],
   "bays":[
      {
         "href":"http://10.164.180.104:9511/v1/bays/",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/bays/",
         "rel":"bookmark"
      }
   ],
   "clustertemplates":[
      {
         "href":"http://10.164.180.104:9511/v1/clustertemplates/",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/clustertemplates/",
         "rel":"bookmark"
      }
   ],
   "certificates":[
      {
         "href":"http://10.164.180.104:9511/v1/certificates/",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/certificates/",
         "rel":"bookmark"
      }
   ],
   "clusters":[
      {
         "href":"http://10.164.180.104:9511/v1/clusters/",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/clusters/",
         "rel":"bookmark"
      }
   ],
   "baymodels":[
      {
         "href":"http://10.164.180.104:9511/v1/baymodels/",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/baymodels/",
         "rel":"bookmark"
      }
   ],
   "id":"v1"
}

Magnum Base URLs

All API calls through the rest of this document require authentication with the OpenStack Identity service. They also required a url that is extracted from the Identity token of type container-infra. This will be the root url that every call below will be added to build a full path.

Note that if using OpenStack Identity service API v2, url can be represented via adminURL, internalURL or publicURL in endpoint catalog. In Identity service API v3, url is represented with field interface including admin, internal and public.

For instance, if the url is http://my-container-infra.org/magnum/v1 then the full API call for /clusters is http://my-container-infra.org/magnum/v1/clusters.

Depending on the deployment the container infrastructure management service url might be http or https, a custom port, a custom path, and include your project id. The only way to know the urls for your deployment is by using the service catalog. The container infrastructure management URL should never be hard coded in applications, even if they are only expected to work at a single site. It should always be discovered from the Identity token.

As such, for the rest of this document we will be using short hand where GET /clusters really means GET {your_container_infra_url}/clusters.

Manage Bay

Lists, creates, shows details for, updates, and deletes Bay.

POST
/v1/bays

Create new bay

Create new bay based on bay model.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
name body string Name of the resource.
discovery_url body string

The custom discovery url for node discovery. This is used by the COE to discover the servers that have been created to host the containers. The actual discovery mechanism varies with the COE. In some cases, Magnum fills in the server info in the discovery service. In other cases, if the discovery_url is not specified, Magnum will use the public discovery service at:

https://discovery.etcd.io

In this case, Magnum will generate a unique url here for each bay and store the info for the servers.
master_count body integer The number of servers that will serve as master for the bay/cluster. The default is 1. Set to more than 1 master to enable High Availability. If the option master-lb-enabled is specified in the baymodel/cluster template, the master servers will be placed in a load balancer pool.
baymodel_id body UUID The UUID of the baymodel.
node_count body integer The number of servers that will serve as node in the bay/cluster. The default is 1.
bay_create_timeout body integer The timeout for bay creation in minutes. The value expected is a positive integer and the default is 60 minutes. If the timeout is reached during bay creation process, the operation will be aborted and the bay status will be set to CREATE_FAILED.

Note

Request for creating bay is asynchronous from Newton.

Request Example

{
   "name":"k8s",
   "discovery_url":null,
   "master_count":2,
   "baymodel_id":"0562d357-8641-4759-8fed-8173f02c9633",
   "node_count":2,
   "bay_create_timeout":60
}

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
uuid body UUID The UUID of the bay.

Response Example

{
   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
}
GET
/v1/bays/

List all bays

List all bays in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
bays body array The list of all bays in Magnum. The list of all clusters in Magnum.
status body string The current state of the bay/cluster.
uuid body UUID The UUID of the bay.
links body array Links to the resources in question.
stack_id body UUID The reference UUID of orchestration stack from Heat orchestration service.
master_count body integer The number of servers that will serve as master for the bay/cluster. The default is 1. Set to more than 1 master to enable High Availability. If the option master-lb-enabled is specified in the baymodel/cluster template, the master servers will be placed in a load balancer pool.
baymodel_id body UUID The UUID of the baymodel.
node_count body integer The number of servers that will serve as node in the bay/cluster. The default is 1.
bay_create_timeout body integer The timeout for bay creation in minutes. The value expected is a positive integer and the default is 60 minutes. If the timeout is reached during bay creation process, the operation will be aborted and the bay status will be set to CREATE_FAILED.
name body string Name of the resource.

Response Example

{
   "bays":[
      {
         "status":"CREATE_COMPLETE",
         "uuid":"746e779a-751a-456b-a3e9-c883d734946f",
         "links":[
            {
               "href":"http://10.164.180.104:9511/v1/bays/746e779a-751a-456b-a3e9-c883d734946f",
               "rel":"self"
            },
            {
               "href":"http://10.164.180.104:9511/bays/746e779a-751a-456b-a3e9-c883d734946f",
               "rel":"bookmark"
            }
         ],
         "stack_id":"9c6f1169-7300-4d08-a444-d2be38758719",
         "master_count":1,
         "baymodel_id":"0562d357-8641-4759-8fed-8173f02c9633",
         "node_count":1,
         "bay_create_timeout":60,
         "name":"k8s"
      }
   ]
}
GET
/v1/bays/{bay_ident}

Show details of a bay

Get all information of a bay in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
bay_ident path string The UUID or name of bays in Magnum.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
status body string The current state of the bay/cluster.
uuid body UUID The UUID of the bay.
links body array Links to the resources in question.
stack_id body UUID The reference UUID of orchestration stack from Heat orchestration service.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
api_address body string The endpoint URL of COE API exposed to end-users.
discovery_url body string

The custom discovery url for node discovery. This is used by the COE to discover the servers that have been created to host the containers. The actual discovery mechanism varies with the COE. In some cases, Magnum fills in the server info in the discovery service. In other cases, if the discovery_url is not specified, Magnum will use the public discovery service at:

https://discovery.etcd.io

In this case, Magnum will generate a unique url here for each bay and store the info for the servers.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
master_count body integer The number of servers that will serve as master for the bay/cluster. The default is 1. Set to more than 1 master to enable High Availability. If the option master-lb-enabled is specified in the baymodel/cluster template, the master servers will be placed in a load balancer pool.
coe_version body string Version info of chosen COE in bay/cluster for helping client in picking the right version of client.
baymodel_id body UUID The UUID of the baymodel.
master_addresses body array List of floating IP of all master nodes.
node_count body integer The number of servers that will serve as node in the bay/cluster. The default is 1.
node_addresses body array List of floating IP of all servers that serve as node.
status_reason body string The reason of bay/cluster current status.
bay_create_timeout body integer The timeout for bay creation in minutes. The value expected is a positive integer and the default is 60 minutes. If the timeout is reached during bay creation process, the operation will be aborted and the bay status will be set to CREATE_FAILED.
name body string Name of the resource.

Response Example

{
   "status":"CREATE_COMPLETE",
   "uuid":"746e779a-751a-456b-a3e9-c883d734946f",
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/bays/746e779a-751a-456b-a3e9-c883d734946f",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/bays/746e779a-751a-456b-a3e9-c883d734946f",
         "rel":"bookmark"
      }
   ],
   "stack_id":"9c6f1169-7300-4d08-a444-d2be38758719",
   "created_at":"2016-08-29T06:51:31+00:00",
   "api_address":"https://172.24.4.6:6443",
   "discovery_url":"https://discovery.etcd.io/cbeb580da58915809d59ee69348a84f3",
   "updated_at":"2016-08-29T06:53:24+00:00",
   "master_count":1,
   "coe_version": "v1.2.0",
   "baymodel_id":"0562d357-8641-4759-8fed-8173f02c9633",
   "master_addresses":[
      "172.24.4.6"
   ],
   "node_count":1,
   "node_addresses":[
      "172.24.4.13"
   ],
   "status_reason":"Stack CREATE completed successfully",
   "bay_create_timeout":60,
   "name":"k8s"
}
DELETE
/v1/bays/{bay_ident}

Delete a bay

Delete a bay.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.

Request

Name In Type Description
bay_ident path string The UUID or name of bays in Magnum.

Response

This request does not return anything in the response body.

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
PATCH
/v1/bays/{bay_ident}

Update information of bay

Update information of one bay attributes using operations including: add, replace or remove. The attributes to add and replace in the form of key=value while remove only needs the keys.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
bay_ident path string The UUID or name of bays in Magnum.
path body string Resource attribute’s name.
value body string Resource attribute’s value.
op body string The operation used to modify resource’s attributes. Supported operations are following: add, replace and remove. In case of remove, users only need to provide path for deleting attribute.

Note

Request for updating bay is asynchronous from Newton. Currently only attribute node_count are supported for operation replace and remove.

Request Example

[
   {
      "path":"/node_count",
      "value":2,
      "op":"replace"
   }
]

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
uuid body UUID The UUID of the bay.

Response Example

{
   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
}

Manage Baymodels

Lists, creates, shows details for, updates, and deletes baymodels.

POST
/v1/baymodels/

Create new baymodel

Create new baymodel.

Response Codes

Success

Code Reason
201 - Created Resource was created and is ready to use.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
name body string Name of the resource.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Request Example

{
   "labels":{

   },
   "fixed_subnet":null,
   "master_flavor_id":null,
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "http_proxy":"http://10.164.177.169:8080",
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "name":"k8s-bm2",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the baymodel.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "insecure_registry":null,
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"bookmark"
      }
   ],
   "http_proxy":"http://10.164.177.169:8080",
   "updated_at":null,
   "floating_ip_enabled":true,
   "fixed_subnet":null,
   "master_flavor_id":null,
   "uuid":"085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "labels":{

   },
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "cluster_distro":"fedora-atomic",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "apiserver_port":null,
   "name":"k8s-bm2",
   "created_at":"2016-08-29T02:08:08+00:00",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}
GET
/v1/baymodels/

List all baymodels

List all available baymodels in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
baymodels body array The list of all baymodels in Magnum.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the baymodel.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "baymodels":[
      {
         "insecure_registry":null,
         "links":[
            {
               "href":"http://10.164.180.104:9511/v1/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
               "rel":"self"
            },
            {
               "href":"http://10.164.180.104:9511/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
               "rel":"bookmark"
            }
         ],
         "http_proxy":"http://10.164.177.169:8080",
         "updated_at":null,
         "floating_ip_enabled":true,
         "fixed_subnet":null,
         "master_flavor_id":null,
         "uuid":"085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
         "https_proxy":"http://10.164.177.169:8080",
         "tls_disabled":false,
         "keypair_id":"kp",
         "public":false,
         "labels":{

         },
         "docker_volume_size":3,
         "server_type":"vm",
         "external_network_id":"public",
         "cluster_distro":"fedora-atomic",
         "image_id":"fedora-atomic-latest",
         "volume_driver":"cinder",
         "registry_enabled":false,
         "docker_storage_driver":"devicemapper",
         "apiserver_port":null,
         "name":"k8s-bm2",
         "created_at":"2016-08-29T02:08:08+00:00",
         "network_driver":"flannel",
         "fixed_network":null,
         "coe":"kubernetes",
         "flavor_id":"m1.small",
         "master_lb_enabled":true,
         "dns_nameserver":"8.8.8.8"
      }
   ]
}
GET
/v1/baymodels/{baymodel_ident}

Show details of a baymodel

Get all information of a baymodel in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
baymodel_ident path string The UUID or name of baymodels in Magnum.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
baymodels body array The list of all baymodels in Magnum.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the baymodel.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "insecure_registry":null,
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"bookmark"
      }
   ],
   "http_proxy":"http://10.164.177.169:8080",
   "updated_at":null,
   "floating_ip_enabled":true,
   "fixed_subnet":null,
   "master_flavor_id":null,
   "uuid":"085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "labels":{

   },
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "cluster_distro":"fedora-atomic",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "apiserver_port":null,
   "name":"k8s-bm2",
   "created_at":"2016-08-29T02:08:08+00:00",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}
DELETE
/v1/baymodels/{baymodel_ident}

Delete a baymodel

Delete a baymodel.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.

Request

Name In Type Description
baymodel_ident path string The UUID or name of baymodels in Magnum.

Response

This request does not return anything in the response body.

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
PATCH
/v1/baymodels/{baymodel_ident}

Update information of baymodel

Update information of one baymodel attributes using operations including: add, replace or remove. The attributes to add and replace in the form of key=value while remove only needs the keys.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
baymodel_ident path string The UUID or name of baymodels in Magnum.
path body string Resource attribute’s name.
value body string Resource attribute’s value.
op body string The operation used to modify resource’s attributes. Supported operations are following: add, replace and remove. In case of remove, users only need to provide path for deleting attribute.

Request Example

[
   {
      "path":"/master_lb_enabled",
      "value":"True",
      "op":"replace"
   },
   {
      "path":"/registry_enabled",
      "value":"True",
      "op":"replace"
   }
]

Response

Return new baymodel with updated attributes.

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
baymodels body array The list of all baymodels in Magnum.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the baymodel.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "insecure_registry":null,
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/baymodels/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"bookmark"
      }
   ],
   "http_proxy":"http://10.164.177.169:8080",
   "updated_at":null,
   "floating_ip_enabled":true,
   "fixed_subnet":null,
   "master_flavor_id":null,
   "uuid":"085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "labels":{

   },
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "cluster_distro":"fedora-atomic",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "apiserver_port":null,
   "name":"k8s-bm2",
   "created_at":"2016-08-29T02:08:08+00:00",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}

Manage Cluster

Lists, creates, shows details for, updates, and deletes Cluster.

POST
/v1/clusters

Create new cluster

Create new cluster based on cluster template.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
name body string Name of the resource.
discovery_url body string

The custom discovery url for node discovery. This is used by the COE to discover the servers that have been created to host the containers. The actual discovery mechanism varies with the COE. In some cases, Magnum fills in the server info in the discovery service. In other cases, if the discovery_url is not specified, Magnum will use the public discovery service at:

https://discovery.etcd.io

In this case, Magnum will generate a unique url here for each bay and store the info for the servers.
master_count body integer The number of servers that will serve as master for the bay/cluster. The default is 1. Set to more than 1 master to enable High Availability. If the option master-lb-enabled is specified in the baymodel/cluster template, the master servers will be placed in a load balancer pool.
cluster_template_id body UUID The UUID of the cluster template.
node_count body integer The number of servers that will serve as node in the bay/cluster. The default is 1.
create_timeout body integer The timeout for cluster creation in minutes. The value expected is a positive integer and the default is 60 minutes. If the timeout is reached during cluster creation process, the operation will be aborted and the cluster status will be set to CREATE_FAILED.
keypair body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.

Note

Request for creating cluster is asynchronous from Newton.

Request Example

{
   "name":"k8s",
   "discovery_url":null,
   "master_count":2,
   "cluster_template_id":"0562d357-8641-4759-8fed-8173f02c9633",
   "node_count":2,
   "create_timeout":60,
   "keypair":"my_keypair"
}

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
uuid body UUID The UUID of the cluster.

Response Example

{
   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
}
GET
/v1/clusters

List all clusters

List all clusters in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
clusters body array The list of all clusters in Magnum.
status body string The current state of the bay/cluster.
uuid body UUID The UUID of the cluster.
links body array Links to the resources in question.
stack_id body UUID The reference UUID of orchestration stack from Heat orchestration service.
keypair body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
master_count body integer The number of servers that will serve as master for the bay/cluster. The default is 1. Set to more than 1 master to enable High Availability. If the option master-lb-enabled is specified in the baymodel/cluster template, the master servers will be placed in a load balancer pool.
cluster_template_id body UUID The UUID of the cluster template.
node_count body integer The number of servers that will serve as node in the bay/cluster. The default is 1.
create_timeout body integer The timeout for cluster creation in minutes. The value expected is a positive integer and the default is 60 minutes. If the timeout is reached during cluster creation process, the operation will be aborted and the cluster status will be set to CREATE_FAILED.
name body string Name of the resource.

Response Example

{
   "clusters":[
      {
         "status":"CREATE_IN_PROGRESS",
         "cluster_template_id":"0562d357-8641-4759-8fed-8173f02c9633",
         "uuid":"731387cf-a92b-4c36-981e-3271d63e5597",
         "links":[
            {
               "href":"http://10.164.180.104:9511/v1/bays/731387cf-a92b-4c36-981e-3271d63e5597",
               "rel":"self"
            },
            {
               "href":"http://10.164.180.104:9511/bays/731387cf-a92b-4c36-981e-3271d63e5597",
               "rel":"bookmark"
            }
         ],
         "stack_id":"31c1ee6c-081e-4f39-9f0f-f1d87a7defa1",
         "keypair":"my_keypair",
         "master_count":1,
         "create_timeout":60,
         "node_count":1,
         "name":"k8s"
      }
   ]
}
GET
/v1/clusters/{cluster_ident}

Show details of a cluster

Get all information of a cluster in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
cluster_ident path string The UUID or name of clusters in Magnum.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
status body string The current state of the bay/cluster.
uuid body UUID The UUID of the cluster.
links body array Links to the resources in question.
stack_id body UUID The reference UUID of orchestration stack from Heat orchestration service.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
api_address body string The endpoint URL of COE API exposed to end-users.
discovery_url body string

The custom discovery url for node discovery. This is used by the COE to discover the servers that have been created to host the containers. The actual discovery mechanism varies with the COE. In some cases, Magnum fills in the server info in the discovery service. In other cases, if the discovery_url is not specified, Magnum will use the public discovery service at:

https://discovery.etcd.io

In this case, Magnum will generate a unique url here for each bay and store the info for the servers.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
master_count body integer The number of servers that will serve as master for the bay/cluster. The default is 1. Set to more than 1 master to enable High Availability. If the option master-lb-enabled is specified in the baymodel/cluster template, the master servers will be placed in a load balancer pool.
coe_version body string Version info of chosen COE in bay/cluster for helping client in picking the right version of client.
keypair body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
cluster_template_id body UUID The UUID of the cluster template.
master_addresses body array List of floating IP of all master nodes.
node_count body integer The number of servers that will serve as node in the bay/cluster. The default is 1.
node_addresses body array List of floating IP of all servers that serve as node.
status_reason body string The reason of bay/cluster current status.
create_timeout body integer The timeout for cluster creation in minutes. The value expected is a positive integer and the default is 60 minutes. If the timeout is reached during cluster creation process, the operation will be aborted and the cluster status will be set to CREATE_FAILED.
name body string Name of the resource.

Response Example

{
   "status":"CREATE_COMPLETE",
   "uuid":"746e779a-751a-456b-a3e9-c883d734946f",
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/clusters/746e779a-751a-456b-a3e9-c883d734946f",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/clusters/746e779a-751a-456b-a3e9-c883d734946f",
         "rel":"bookmark"
      }
   ],
   "stack_id":"9c6f1169-7300-4d08-a444-d2be38758719",
   "created_at":"2016-08-29T06:51:31+00:00",
   "api_address":"https://172.24.4.6:6443",
   "discovery_url":"https://discovery.etcd.io/cbeb580da58915809d59ee69348a84f3",
   "updated_at":"2016-08-29T06:53:24+00:00",
   "master_count":1,
   "coe_version": "v1.2.0",
   "keypair":"my_keypair"
   "cluster_template_id":"0562d357-8641-4759-8fed-8173f02c9633",
   "master_addresses":[
      "172.24.4.6"
   ],
   "node_count":1,
   "node_addresses":[
      "172.24.4.13"
   ],
   "status_reason":"Stack CREATE completed successfully",
   "create_timeout":60,
   "name":"k8s"
}
DELETE
/v1/clusters/{cluster_ident}

Delete a cluster

Delete a cluster.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.

Request

Name In Type Description
cluster_ident path string The UUID or name of clusters in Magnum.

Response

This request does not return anything in the response body.

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
PATCH
/v1/clusters/{cluster_ident}

Update information of cluster

Update information of one cluster attributes using operations including: add, replace or remove. The attributes to add and replace in the form of key=value while remove only needs the keys.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
cluster_ident path string The UUID or name of clusters in Magnum.
path body string Resource attribute’s name.
value body string Resource attribute’s value.
op body string The operation used to modify resource’s attributes. Supported operations are following: add, replace and remove. In case of remove, users only need to provide path for deleting attribute.

Note

Request for updating cluster is asynchronous from Newton. Currently only attribute node_count are supported for operation replace and remove.

Request Example

[
   {
      "path":"/node_count",
      "value":2,
      "op":"replace"
   }
]

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
uuid body UUID The UUID of the cluster.

Response Example

{
   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
}

Manage Cluster Templates

Lists, creates, shows details for, updates, and deletes Cluster Templates.

POST
/v1/clustertemplates

Create new cluster template

Create new cluster template.

Response Codes

Success

Code Reason
201 - Created Resource was created and is ready to use.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
name body string Name of the resource.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Request Example

{
   "labels":{

   },
   "fixed_subnet":null,
   "master_flavor_id":null,
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "http_proxy":"http://10.164.177.169:8080",
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "name":"k8s-bm2",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the cluster template.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "insecure_registry":null,
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/clustertemplates/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/clustertemplates/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"bookmark"
      }
   ],
   "http_proxy":"http://10.164.177.169:8080",
   "updated_at":null,
   "floating_ip_enabled":true,
   "fixed_subnet":null,
   "master_flavor_id":null,
   "uuid":"085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "labels":{

   },
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "cluster_distro":"fedora-atomic",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "apiserver_port":null,
   "name":"k8s-bm2",
   "created_at":"2016-08-29T02:08:08+00:00",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}
GET
/v1/clustertemplates

List all cluster templates

List all available cluster templates in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
clustertemplates body array The list of all cluster templates in Magnum.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the cluster template.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "clustertemplates":[
      {
         "insecure_registry":null,
         "links":[
            {
               "href":"http://10.164.180.104:9511/v1/clustertemplates/0562d357-8641-4759-8fed-8173f02c9633",
               "rel":"self"
            },
            {
               "href":"http://10.164.180.104:9511/clustertemplates/0562d357-8641-4759-8fed-8173f02c9633",
               "rel":"bookmark"
            }
         ],
         "http_proxy":"http://10.164.177.169:8080",
         "updated_at":null,
         "floating_ip_enabled":true,
         "fixed_subnet":null,
         "master_flavor_id":null,
         "uuid":"0562d357-8641-4759-8fed-8173f02c9633",
         "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
         "https_proxy":"http://10.164.177.169:8080",
         "tls_disabled":false,
         "keypair_id":"kp",
         "public":false,
         "labels":{

         },
         "docker_volume_size":3,
         "server_type":"vm",
         "external_network_id":"public",
         "cluster_distro":"fedora-atomic",
         "image_id":"fedora-atomic-latest",
         "volume_driver":"cinder",
         "registry_enabled":false,
         "docker_storage_driver":"devicemapper",
         "apiserver_port":null,
         "name":"k8s-bm",
         "created_at":"2016-08-26T09:34:41+00:00",
         "network_driver":"flannel",
         "fixed_network":null,
         "coe":"kubernetes",
         "flavor_id":"m1.small",
         "master_lb_enabled":false,
         "dns_nameserver":"8.8.8.8"
      }
   ]
}
GET
/v1/clustertemplates/{clustertemplate_ident}

Show details of a cluster template

Get all information of a cluster template in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
clustertemplate_ident path string The UUID or name of cluster templates in Magnum.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
clustertemplates body array The list of all cluster templates in Magnum.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the cluster template.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "insecure_registry":null,
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/clustertemplates/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/clustertemplates/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"bookmark"
      }
   ],
   "http_proxy":"http://10.164.177.169:8080",
   "updated_at":null,
   "floating_ip_enabled":true,
   "fixed_subnet":null,
   "master_flavor_id":null,
   "uuid":"085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "labels":{

   },
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "cluster_distro":"fedora-atomic",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "apiserver_port":null,
   "name":"k8s-bm2",
   "created_at":"2016-08-29T02:08:08+00:00",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}
DELETE
/v1/clustertemplates/{clustertemplate_ident}

Delete a cluster template

Delete a cluster template.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.

Request

Name In Type Description
clustertemplate_ident path string The UUID or name of cluster templates in Magnum.

Response

This request does not return anything in the response body.

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
PATCH
/v1/clustertemplates/{clustertemplate_ident}

Update information of cluster template

Update information of one cluster template attributes using operations including: add, replace or remove. The attributes to add and replace in the form of key=value while remove only needs the keys.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request

Name In Type Description
clustertemplate_ident path string The UUID or name of cluster templates in Magnum.
path body string Resource attribute’s name.
value body string Resource attribute’s value.
op body string The operation used to modify resource’s attributes. Supported operations are following: add, replace and remove. In case of remove, users only need to provide path for deleting attribute.

Request Example

[
   {
      "path":"/master_lb_enabled",
      "value":"True",
      "op":"replace"
   },
   {
      "path":"/registry_enabled",
      "value":"True",
      "op":"replace"
   }
]

Response

Return new cluster templates with updated attributes.

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
clustertemplates body array The list of all cluster templates in Magnum.
insecure_registry body string The URL pointing to users’s own private insecure docker registry to deploy and run docker containers.
links body array Links to the resources in question.
http_proxy (Optional) body string The IP address for a proxy to use when direct http access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
floating_ip_enabled body boolean Whether enable or not using the floating IP of cloud provider. Some cloud providers used floating IP, some used public IP, thus Magnum provide this option for specifying the choice of using floating IP.
fixed_subnet (Optional) body string Fixed subnet that are using to allocate network address for nodes in bay/cluster.
master_flavor_id (Optional) body string The flavor of the master node for this baymodel/cluster template.
uuid body UUID The UUID of the cluster template.
no_proxy (Optional) body string When a proxy server is used, some sites should not go through the proxy and should be accessed normally. In this case, users can specify these sites as a comma separated list of IPs. The default is None.
https_proxy (Optional) body string The IP address for a proxy to use when direct https access from the servers to sites on the external internet is blocked. This may happen in certain countries or enterprises, and the proxy allows the servers and containers to access these sites. The format is a URL including a port number. The default is None.
tls_disabled body boolean Transport Layer Security (TLS) is normally enabled to secure the bay/cluster. In some cases, users may want to disable TLS in the bay/cluster, for instance during development or to troubleshoot certain problems. Specifying this parameter will disable TLS so that users can access the COE endpoints without a certificate. The default is TLS enabled.
keypair_id body string The name of the SSH keypair to configure in the bay/cluster servers for ssh access. Users will need the key to be able to ssh to the servers in the bay/cluster. The login name is specific to the bay/cluster driver, for example with fedora-atomic image, default login name is fedora.
public body boolean Access to a baymodel/cluster template is normally limited to the admin, owner or users within the same tenant as the owners. Setting this flag makes the baymodel/cluster template public and accessible by other users. The default is not public.
labels (Optional) body array Arbitrary labels in the form of key=value pairs. The accepted keys and valid values are defined in the bay/cluster drivers. They are used as a way to pass additional parameters that are specific to a bay/cluster driver.
docker_volume_size body integer The size in GB for the local storage on each server for the Docker daemon to cache the images and host the containers. Cinder volumes provide the storage. The default is 25 GB. For the devicemapper storage driver, the minimum value is 3GB. For the overlay storage driver, the minimum value is 1GB.
server_type body string The servers in the bay/cluster can be vm or baremetal. This parameter selects the type of server to create for the bay/cluster. The default is vm.
external_network_id body string The name or network ID of a Neutron network to provide connectivity to the external internet for the bay/cluster. This network must be an external network, i.e. its attribute router:external must be True. The servers in the bay/cluster will be connected to a private network and Magnum will create a router between this private network and the external network. This will allow the servers to download images, access discovery service, etc, and the containers to install packages, etc. In the opposite direction, floating IPs will be allocated from the external network to provide access from the external internet to servers and the container services hosted in the bay/cluster.
cluster_distro body string Display the attribute os-distro defined as appropriate metadata in image for the bay/cluster driver.
image_id body string The name or UUID of the base image in Glance to boot the servers for the bay/cluster. The image must have the attribute os-distro defined as appropriate for the bay/cluster driver.
volume_driver body string The name of a volume driver for managing the persistent storage for the containers. The functionality supported are specific to the driver.
registry_enabled (Optional) body boolean Docker images by default are pulled from the public Docker registry, but in some cases, users may want to use a private registry. This option provides an alternative registry based on the Registry V2: Magnum will create a local registry in the bay/cluster backed by swift to host the images. The default is to use the public registry.
docker_storage_driver body string The name of a driver to manage the storage for the images and the container’s writable layer. The supported drivers are devicemapper and overlay. The default is devicemapper.
apiserver_port body integer The exposed port of COE API server.
name body string Name of the resource.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
network_driver body string The name of a network driver for providing the networks for the containers. Note that this is different and separate from the Neutron network for the bay/cluster. The operation and networking model are specific to the particular driver.
fixed_network (Optional) body string The name or network ID of a Neutron network to provide connectivity to the internal network for the bay/cluster.
coe body string Specify the Container Orchestration Engine to use. Supported COEs include kubernetes, swarm, mesos. If your environment has additional bay/cluster drivers installed, refer to the bay/cluster driver documentation for the new COE names.
flavor_id body string The nova flavor ID or name for booting the node servers. The default is m1.small.
master_lb_enabled body boolean Since multiple masters may exist in a bay/cluster, a Neutron load balancer is created to provide the API endpoint for the bay/cluster and to direct requests to the masters. In some cases, such as when the LBaaS service is not available, this option can be set to false to create a bay/cluster without the load balancer. In this case, one of the masters will serve as the API endpoint. The default is true, i.e. to create the load balancer for the bay.
dns_nameserver body string The DNS nameserver for the servers and containers in the bay/cluster to use. This is configured in the private Neutron network for the bay/cluster. The default is 8.8.8.8.

Response Example

{
   "insecure_registry":null,
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/clustertemplates/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/clustertemplates/085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
         "rel":"bookmark"
      }
   ],
   "http_proxy":"http://10.164.177.169:8080",
   "updated_at":null,
   "floating_ip_enabled":true,
   "fixed_subnet":null,
   "master_flavor_id":null,
   "uuid":"085e1c4d-4f68-4bfd-8462-74b9e14e4f39",
   "no_proxy":"10.0.0.0/8,172.0.0.0/8,192.0.0.0/8,localhost",
   "https_proxy":"http://10.164.177.169:8080",
   "tls_disabled":false,
   "keypair_id":"kp",
   "public":false,
   "labels":{

   },
   "docker_volume_size":3,
   "server_type":"vm",
   "external_network_id":"public",
   "cluster_distro":"fedora-atomic",
   "image_id":"fedora-atomic-latest",
   "volume_driver":"cinder",
   "registry_enabled":false,
   "docker_storage_driver":"devicemapper",
   "apiserver_port":null,
   "name":"k8s-bm2",
   "created_at":"2016-08-29T02:08:08+00:00",
   "network_driver":"flannel",
   "fixed_network":null,
   "coe":"kubernetes",
   "flavor_id":"m1.small",
   "master_lb_enabled":true,
   "dns_nameserver":"8.8.8.8"
}

Manage certificates for bay/cluster

Generates and show CA certificates for bay/cluster.

GET
/v1/certificates/{bay_uuid/cluster_uuid}

Show details about the CA certificate for a bay/cluster

Show CA certificate details that are associated with the created bay/cluster.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Request

Name In Type Description
bay_uuid body UUID The UUID of the bay.

Note

After Newton, all terms related bay/baymodel will be renamed to cluster and cluster template.

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
cluster_uuid body UUID The UUID of the cluster.
pem body string CA certificate for the bay/cluster.
bay_uuid body UUID The UUID of the bay.
links body array Links to the resources in question.

Note

After Newton, all terms related bay/baymodel will be renamed to cluster and cluster template.

Response Example

{
   "cluster_uuid":"0b4b766f-1500-44b3-9804-5a6e12fe6df4"
   "pem":"-----BEGIN CERTIFICATE-----\nMIICzDCCAbSgAwIBAgIQOOkVcEN7TNa9E80GoUs4xDANBgkqhkiG9w0BAQsFADAO\n-----END CERTIFICATE-----\n",
   "bay_uuid":"0b4b766f-1500-44b3-9804-5a6e12fe6df4",
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
         "rel":"bookmark"
      }
   ]
}
POST
/v1/certificates/

Generate the CA certificate for a bay/cluster

Sign client key and generate the CA certificate for a bay/cluster

Response Codes

Success

Code Reason
201 - Created Resource was created and is ready to use.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Request

Name In Type Description
bay_uuid body UUID The UUID of the bay.
csr body string

Certificate Signing Request (CSR) for authenticating client key.

The CSR will be used by Magnum to generate a signed certificate that client will use to communicate with the Bay/Cluster.

Note

After Newton, all terms related bay/baymodel will be renamed to cluster and cluster template.

Request Example

{
   "bay_uuid":"0b4b766f-1500-44b3-9804-5a6e12fe6df4",
   "csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIIEfzCCAmcCAQAwFDESMBAGA1UEAxMJWW91ciBOYW1lMIICIjANBgkqhkiG9w0B\n-----END CERTIFICATE REQUEST-----\n"
}

Response

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
pem body string CA certificate for the bay/cluster.
bay_uuid body UUID The UUID of the bay.
links body array Links to the resources in question.
csr body string

Certificate Signing Request (CSR) for authenticating client key.

The CSR will be used by Magnum to generate a signed certificate that client will use to communicate with the Bay/Cluster.

Note

After Newton, all terms related bay/baymodel will be renamed to cluster and cluster template.

Response Example

{
   "pem":"-----BEGIN CERTIFICATE-----\nMIIDxDCCAqygAwIBAgIRALgUbIjdKUy8lqErJmCxVfkwDQYJKoZIhvcNAQELBQAw\n-----END CERTIFICATE-----\n",
   "bay_uuid":"0b4b766f-1500-44b3-9804-5a6e12fe6df4",
   "links":[
      {
         "href":"http://10.164.180.104:9511/v1/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
         "rel":"self"
      },
      {
         "href":"http://10.164.180.104:9511/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
         "rel":"bookmark"
      }
   ],
   "csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIIEfzCCAmcCAQAwFDESMBAGA1UEAxMJWW91ciBOYW1lMIICIjANBgkqhkiG9w0B\n-----END CERTIFICATE REQUEST-----\n"
}
PATCH
/v1/certificates/{bay_uuid/cluster_uuid}

Rotate the CA certificate for a bay/cluster

Rotate the CA certificate for a bay/cluster and invalidate all user certificates.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.

Request

Name In Type Description
cluster body UUID The UUID of the cluster.

Manage Magnum service

GET
/v1/mservices

List container infrastructure management services

Enables administrative users to list all Magnum services.

Container infrastructure service information include service id, binary, host, report count, creation time, last updated time, health status, and the reason for disabling service.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header UUID A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
mservices body array A list of Magnum services.
binary body string The name of the binary form of the Magnum service.
created_at body string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.
state body string The current state of Magnum services.
report_count body integer The total number of report.
updated_at body string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.
host body string The host for the service.
disabled_reason body string The disable reason of the service, null if the service is enabled or disabled without reason provided.
id body string The ID of the Magnum service.

Response Example

{
   "mservices":[
      {
         "binary":"magnum-conductor",
         "created_at":"2016-08-23T10:52:13+00:00",
         "state":"up",
         "report_count":2179,
         "updated_at":"2016-08-25T01:13:16+00:00",
         "host":"magnum-manager",
         "disabled_reason":null,
         "id":1
      }
   ]
}

Magnum Stats API

An admin user can get stats for the given tenant and also overall system stats. A non-admin user can get self stats.

GET
/v1/stats?project_id=

Show stats for a tenant

Get stats based on project id.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Request

Name In Type Description
project_id path string Project ID.

Response

Name In Type Description
clusters body integer The number of clusters.
nodes body integer The total number of nodes including master nodes.

Response Example

{
   "clusters": 1,
   "nodes": 2
}
GET
/v1/stats

Show overall stats

Show overall Magnum system stats. If the requester is non-admin user show self stats.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Response

Name In Type Description
clusters body integer The number of clusters.
nodes body integer The total number of nodes including master nodes.

Response Example

{
   "clusters": 1,
   "nodes": 2
}

Magnum Quota API

Lists, creates, shows details, and updates Quotas.

POST
/v1/quotas

Set new quota

Create new quota for a project.

Response Codes

Success

Code Reason
201 - Created Resource was created and is ready to use.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request Example

{
   "project_id": "aa5436ab58144c768ca4e9d2e9f5c3b2",
   "resource": "Cluster",
   "hard_limit": 10
}

Response Example

{
   "resource": "Cluster",
   "created_at": "2017-01-17T17:35:48+00:00",
   "updated_at": null,
   "hard_limit": 1,
   "project_id": "aa5436ab58144c768ca4e9d2e9f5c3b2",
   "id": 26
}
GET
/v1/quotas

List all quotas

List all quotas in Magnum.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

Response Example

{
   "quotas": [
      {
         "resource": "Cluster",
         "created_at": "2017-01-17T17:35:49+00:00",
         "updated_at": "2017-01-17T17:38:21+00:00",
         "hard_limit": 10,
         "project_id": "aa5436ab58144c768ca4e9d2e9f5c3b2",
         "id": 26
      }
   ]
}
GET
/v1/quotas/{project_id}/{resource}

Show details of a quota

Get quota information for the given project_id and resource.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Response Example

{
   "resource": "Cluster",
   "created_at": "2017-01-17T17:35:49+00:00",
   "updated_at": "2017-01-17T17:38:20+00:00",
   "hard_limit": 10,
   "project_id": "aa5436ab58144c768ca4e9d2e9f5c3b2",
   "id": 26
}
PATCH
/v1/quotas/{project_id}/{resource}

Update a resource quota

Update resource quota for the given project id.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request Example

{
   "project_id": "aa5436ab58144c768ca4e9d2e9f5c3b2",
   "resource": "Cluster",
   "hard_limit": 10
}

Response Example

{
   "resource": "Cluster",
   "created_at": "2017-01-17T17:35:49+00:00",
   "updated_at": "2017-01-17T17:38:20+00:00",
   "hard_limit": 10,
   "project_id": "aa5436ab58144c768ca4e9d2e9f5c3b2",
   "id": 26
}
DELETE
/v1/quotas/{project_id}/{resource}

Delete a resource quota

Delete a resource quota for the given project id.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.

Request Example

{
   "project_id": "aa5436ab58144c768ca4e9d2e9f5c3b2",
   "resource": "Cluster"
}
updated: 'Fri Jun 16 16:14:28 2017, commit 907415c'
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug questions?