openstack
/
magnum
Code Issues Proposed changes

Merge "Create bay/cluster api reference"

This commit is contained in:
Jenkins 2016-09-10 00:41:39 +00:00 committed by Gerrit Code Review
parent 8ec631d556 2c1f9bde2b
commit 318db1326c
16 changed files with 822 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

259
api-ref/source/bays.inc Normal file
View File

@ -0,0 +1,259 @@
.. -*- rst -*-
============
Manage Bay
============
Lists, creates, shows details for, updates, and deletes Bay.
Create new bay
==============
.. rest_method:: POST /v1/bays
Create new bay based on bay model.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- discovery_url: discovery_url
- master_count: master_count
- baymodel_id: baymodel_id
- node_count: node_count
- bay_create_timeout: bay_create_timeout
.. note::
Request for creating bay is asynchronous from Newton.
Request Example
----------------
.. literalinclude:: samples/bay-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- uuid: bay_id
Response Example
----------------
.. literalinclude:: samples/bay-create-resp.json
:language: javascript
List all bay
====================
.. rest_method:: GET /v1/bays/
List all bays in Magnum.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- bays: bay_list
- status: status
- uuid: bay_id
- links: links
- stack_id: stack_id
- master_count: master_count
- baymodel_id: baymodel_id
- node_count: node_count
- bay_create_timeout: bay_create_timeout
- name: name
Response Example
----------------
.. literalinclude:: samples/bay-get-all-resp.json
:language: javascript
Show details of a bay
=============================
.. rest_method:: GET /v1/bays/{bay_ident}
Get all information of a bay in Magnum.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- bay_ident: bay_ident
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- status: status
- uuid: bay_id
- links: links
- stack_id: stack_id
- created_at: created_at
- api_address: api_address
- discovery_url: discovery_url
- updated_at: updated_at
- master_count: master_count
- coe_version: coe_version
- baymodel_id: baymodel_id
- master_addresses: master_addresses
- node_count: node_count
- node_addresses: node_addresses
- status_reason: status_reason
- bay_create_timeout: bay_create_timeout
- name: name
Response Example
----------------
.. literalinclude:: samples/bay-get-one-resp.json
:language: javascript
Delete a bay
====================
.. rest_method:: DELETE /v1/bays/{bay_ident}
Delete a bay.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- bay_ident: bay_ident
Response
--------
This request does not return anything in the response body.
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
Update information of bay
=================================
.. rest_method:: PATCH /v1/bays/{bay_ident}
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
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- bay_ident: bay_ident
- path: path
- value: value
- op: op
.. note::
Request for updating bay is asynchronous from Newton.
Currently only attribute ``node_count`` are supported for operation
``replace`` and ``remove``.
Request Example
----------------
.. literalinclude:: samples/bay-update-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- uuid: bay_id
Response Example
----------------
.. literalinclude:: samples/bay-create-resp.json
:language: javascript

0
api-ref/source/bays_clusters.inc
View File

28
api-ref/source/certificates.inc
View File

@ -30,7 +30,12 @@ Request
.. rest_parameters:: parameters.yaml
- bay_uuid: bay_cluster_id
- bay_uuid: bay_id
.. note::
After Newton, all terms related bay/baymodel will be renamed to cluster
and cluster template.
Response
--------
@ -39,9 +44,14 @@ Response
- X-Openstack-Request-Id: request_id
- pem: pem
- bay_uuid: bay_cluster_id
- bay_uuid: bay_id
- links: links
.. note::
After Newton, all terms related bay/baymodel will be renamed to cluster
and cluster template.
Response Example
----------------
@ -73,9 +83,14 @@ Request
.. rest_parameters:: parameters.yaml
- bay_uuid: bay_cluster_id
- bay_uuid: bay_id
- csr: csr
.. note::
After Newton, all terms related bay/baymodel will be renamed to cluster
and cluster template.
Request Example
----------------
@ -89,10 +104,15 @@ Response
- X-Openstack-Request-Id: request_id
- pem: pem
- bay_uuid: bay_cluster_id
- bay_uuid: bay_id
- links: links
- csr: csr
.. note::
After Newton, all terms related bay/baymodel will be renamed to cluster
and cluster template.
Response Example
----------------

259
api-ref/source/clusters.inc Normal file
View File

@ -0,0 +1,259 @@
.. -*- rst -*-
================
Manage Cluster
================
Lists, creates, shows details for, updates, and deletes Cluster.
Create new cluster
==================
.. rest_method:: POST /v1/clusters
Create new cluster based on cluster template.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- discovery_url: discovery_url
- master_count: master_count
- cluster_template_id: clustertemplate_id
- node_count: node_count
- create_timeout: create_timeout
.. note::
Request for creating cluster is asynchronous from Newton.
Request Example
----------------
.. literalinclude:: samples/cluster-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- uuid: cluster_id
Response Example
----------------
.. literalinclude:: samples/cluster-create-resp.json
:language: javascript
List all cluster
================
.. rest_method:: GET /v1/clusters
List all clusters in Magnum.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- clusters: cluster_list
- status: status
- uuid: cluster_id
- links: links
- stack_id: stack_id
- master_count: master_count
- cluster_template_id: clustertemplate_id
- node_count: node_count
- create_timeout: create_timeout
- name: name
Response Example
----------------
.. literalinclude:: samples/cluster-get-all-resp.json
:language: javascript
Show details of a cluster
=========================
.. rest_method:: GET /v1/clusters/{cluster_ident}
Get all information of a cluster in Magnum.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- cluster_ident: cluster_ident
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- status: status
- uuid: cluster_id
- links: links
- stack_id: stack_id
- created_at: created_at
- api_address: api_address
- discovery_url: discovery_url
- updated_at: updated_at
- master_count: master_count
- coe_version: coe_version
- cluster_template_id: clustertemplate_id
- master_addresses: master_addresses
- node_count: node_count
- node_addresses: node_addresses
- status_reason: status_reason
- create_timeout: create_timeout
- name: name
Response Example
----------------
.. literalinclude:: samples/cluster-get-one-resp.json
:language: javascript
Delete a cluster
====================
.. rest_method:: DELETE /v1/clusters/{cluster_ident}
Delete a cluster.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- cluster_ident: cluster_ident
Response
--------
This request does not return anything in the response body.
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
Update information of cluster
=============================
.. rest_method:: PATCH /v1/clusters/{cluster_ident}
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
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- cluster_ident: cluster_ident
- path: path
- value: value
- op: op
.. note::
Request for updating cluster is asynchronous from Newton.
Currently only attribute ``node_count`` are supported for operation
``replace`` and ``remove``.
Request Example
----------------
.. literalinclude:: samples/cluster-update-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- uuid: cluster_id
Response Example
----------------
.. literalinclude:: samples/cluster-create-resp.json
:language: javascript

3
api-ref/source/index.rst
View File

@ -8,8 +8,9 @@
.. include:: versions.inc
.. include:: urls.inc
.. include:: bays_clusters.inc
.. include:: bays.inc
.. include:: baymodels.inc
.. include:: clusters.inc
.. include:: clustertemplates.inc
.. include:: certificates.inc
.. include:: mservices.inc

132
api-ref/source/parameters.yaml
View File

@ -8,12 +8,24 @@ request_id:
with the request by default appears in the service logs.
# Path params
bay_ident:
type: string
in: path
required: true
description: |
The UUID or name of bays in Magnum.
baymodel_ident:
description: |
The UUID or name of baymodels in Magnum.
in: path
required: true
type: string
cluster_ident:
type: string
in: path
required: true
description: |
The UUID or name of clusters in Magnum.
clustertemplate_ident:
type: string
in: path
@ -22,18 +34,41 @@ clustertemplate_ident:
The UUID or name of cluster templates in Magnum.
# Body params
api_address:
description: |
The endpoint URL of COE API exposed to end-users.
in: body
format: uri
required: true
type: string
apiserver_port:
type: integer
in: body
required: true
description: |
The exposed port of COE API server.
bay_cluster_id:
bay_create_timeout:
type: integer
in: body
required: true
description: |
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``.
bay_id:
type: UUID
in: body
required: true
description: |
The UUID of the bay/cluster.
The UUID of the bay.
bay_list:
type: array
in: body
required: true
description: |
The list of all bays in Magnum.
The list of all clusters in Magnum.
baymodel_id:
type: UUID
in: body
@ -59,6 +94,18 @@ cluster_distro:
description: |
Display the attribute ``os-distro`` defined as appropriate metadata in
image for the bay/cluster driver.
cluster_id:
type: UUID
in: body
required: true
description: |
The UUID of the cluster.
cluster_list:
type: array
in: body
required: true
description: |
The list of all clusters in Magnum.
clustertemplate_id:
type: UUID
in: body
@ -80,6 +127,22 @@ coe:
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.
coe_version:
type: string
in: body
required: true
description: |
Version info of chosen COE in bay/cluster for helping client in picking
the right version of client.
create_timeout:
type: integer
in: body
required: true
description: |
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``.
created_at:
description: |
The date and time when the resource was created.
@ -120,6 +183,25 @@ disabled_reason:
in: body
required: true
type: string
discovery_url:
description: |
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.
in: body
format: uri
required: true
type: string
dns_nameserver:
description: |
The DNS nameserver for the servers and containers in the bay/cluster to
@ -260,6 +342,21 @@ links:
in: body
required: true
type: array
master_addresses:
description: |
List of floating IP of all master nodes.
in: body
required: true
type: array
master_count:
description: |
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.
in: body
required: true
type: integer
master_flavor_id:
description: |
The flavor of the master node for this baymodel/cluster template.
@ -307,6 +404,19 @@ no_proxy:
in: body
required: false
type: string
node_addresses:
description: |
List of floating IP of all servers that serve as node.
in: body
required: true
type: array
node_count:
description: |
The number of servers that will serve as node in the bay/cluster. The
default is 1.
in: body
required: true
type: integer
op:
description: |
The operation used to modify resource's attributes. Supported operations
@ -360,12 +470,30 @@ server_type:
in: body
required: true
type: string
stack_id:
description: |
The reference UUID of orchestration stack from Heat orchestration service.
in: body
required: true
type: UUID
state:
description: |
The current state of Magnum services.
in: body
required: true
type: string
status:
description: |
The current state of the bay/cluster.
in: body
required: true
type: string
status_reason:
description: |
The reason of bay/cluster current status.
in: body
required: true
type: string
tls_disabled:
description: |
Transport Layer Security (TLS) is normally enabled to secure the

8
api-ref/source/samples/bay-create-req.json Normal file
View File

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

3
api-ref/source/samples/bay-create-resp.json Normal file
View File

@ -0,0 +1,3 @@
{
"uuid":"746e779a-751a-456b-a3e9-c883d734946f"
}

24
api-ref/source/samples/bay-get-all-resp.json Normal file
View File

@ -0,0 +1,24 @@
{
"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"
}
]
}

32
api-ref/source/samples/bay-get-one-resp.json Normal file
View File

@ -0,0 +1,32 @@
{
"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"
}

7
api-ref/source/samples/bay-update-req.json Normal file
View File

@ -0,0 +1,7 @@
[
{
"path":"/node_count",
"value":2,
"op":"replace"
}
]

8
api-ref/source/samples/cluster-create-req.json Normal file
View File

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

3
api-ref/source/samples/cluster-create-resp.json Normal file
View File

@ -0,0 +1,3 @@
{
"uuid":"746e779a-751a-456b-a3e9-c883d734946f"
}

24
api-ref/source/samples/cluster-get-all-resp.json Normal file
View File

@ -0,0 +1,24 @@
{
"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",
"master_count":1,
"create_timeout":60,
"node_count":1,
"name":"k8s"
}
]
}

32
api-ref/source/samples/cluster-get-one-resp.json Normal file
View File

@ -0,0 +1,32 @@
{
"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",
"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"
}

7
api-ref/source/samples/cluster-update-req.json Normal file
View File

@ -0,0 +1,7 @@
[
{
"path":"/node_count",
"value":2,
"op":"replace"
}
]