openstack/magnum
Code Issues Proposed changes

Fix specs reference rst format

Browse Source 
In our specs we not correctly reference as rst format, which
is not good to display well for readers.

Change-Id: Idca82ae3b2b447a40870b38b820c008db219165b
This commit is contained in:
Kai Qiang Wu(Kennan) 2016-04-15 02:58:17 +00:00
parent 5d5cdf99d8
commit 816caeab63
3 changed files with 54 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
specs/container-networking-model.rst
View File

@ -29,7 +29,7 @@ Problem Description
The container networking ecosystem is undergoing rapid changes. The
networking tools and techniques used in today's container deployments are
different than twelve months ago and will continue to evolve. For example,
Flannel[6], Kubernetes preferred networking implementation, was initially
Flannel [6]_, Kubernetes preferred networking implementation, was initially
released in July of 2014 and was not considered preferred until early 2015.
Furthermore, the various container orchestration engines have not
@ -98,7 +98,7 @@ Pod
managed within Kubernetes.
Additional Magnum definitions can be found in the Magnum Developer
documentation[2].
documentation [2]_.
Use Cases
----------
@ -170,7 +170,7 @@ As a CP:
Proposed Changes
================
1. Currently, Magnum supports Flannel[6] as the only multi-host container
1. Currently, Magnum supports Flannel [6]_ as the only multi-host container
networking implementation. Although Flannel has become widely accepted
for providing networking capabilities to Kubernetes-based container
clusters, other networking tools exist and future tools may develop.
@ -233,7 +233,7 @@ Proposed Changes
support labels as a mechanism for providing custom metadata. The labels
attribute within Magnum should be extended beyond Kubernetes pods, so a
single mechanism can be used to pass arbitrary metadata throughout the
entire system. A blueprint[2] has been registered to expand the scope
entire system. A blueprint [2]_ has been registered to expand the scope
of labels for Magnum. This document intends on adhering to the
expand-labels-scope blueprint.
@ -252,7 +252,7 @@ Proposed Changes
3. Update python-magnumclient to understand the new Container Networking
Model attributes. The client should also be updated to support passing
the --labels flag according to the expand-labels-scope blueprint[2].
the --labels flag according to the expand-labels-scope blueprint [2]_.
4. Update the conductor template definitions to support the new Container
Networking Model attributes.
@ -260,14 +260,14 @@ Proposed Changes
5. Refactor Heat templates to support the Magnum Container Networking Model.
Currently, Heat templates embed Flannel-specific configuration within
top-level templates. For example, the top-level Kubernetes Heat
template[8] contains the flannel_network_subnetlen parameter. Network
template [8]_ contains the flannel_network_subnetlen parameter. Network
driver specific configurations should be removed from all top-level
templates and instead be implemented in one or more template fragments.
As it relates to container networking, top-level templates should only
expose the labels and generalized parameters such as network-driver.
Heat templates, template definitions and definition entry points should
be suited for composition, allowing for a range of supported labels. This
document intends to follow the refactor-heat-templates blueprint[3] to
document intends to follow the refactor-heat-templates blueprint [3]_ to
achieve this goal.
6. Update unit and functional tests to support the new attributes of the
@ -276,10 +276,11 @@ Proposed Changes
7. The spec will not add support for natively managing container networks.
Due to each network driver supporting different API operations, this
document suggests that Magnum not natively manage container networks at
this time and instead leave this job to native tools. References [4-7]
this time and instead leave this job to native tools. References [4]_ [5]_
[6]_ [7]_.
provide additional details to common labels operations.
8. Since implementing the expand-labels-scope blueprint[2] may take a while,
8. Since implementing the expand-labels-scope blueprint [2]_ may take a while,
exposing network functionality through baymodel configuration parameters
should be considered as an interim solution.
@ -299,7 +300,7 @@ Alternatives
abstractions for each supported network driver or creating an
abstraction layer that covers all possible network drivers.
4. Use the Kuryr project[10] to provide networking to Magnum containers.
4. Use the Kuryr project [10]_ to provide networking to Magnum containers.
Kuryr currently contains no documentation or code, so this alternative
is highly unlikely if the Magnum community requires a pluggable
container networking implementation in the near future. However, Kuryr
@ -422,14 +423,11 @@ following blueprints, it's highly recommended that the Magnum Container
Networking Model be developed in concert with the blueprints to maintain
development continuity within the project.
1. Common Plugin Framework Blueprint:
https://blueprints.launchpad.net/magnum/+spec/common-plugin-framework
1. Common Plugin Framework Blueprint [1]_.
2. Expand the Scope of Labels Blueprint:
https://blueprints.launchpad.net/magnum/+spec/expand-labels-scope
2. Expand the Scope of Labels Blueprint [9]_.
3. Refactor Heat Templates, Definitions and Entry Points Blueprint:
https://blueprints.launchpad.net/magnum/+spec/refactor-heat-templates
3. Refactor Heat Templates, Definitions and Entry Points Blueprint [3]_.
Testing
=======
@ -448,13 +446,13 @@ information on how to use these flags will be included.
References
==========
[1] https://blueprints.launchpad.net/magnum/+spec/common-plugin-framework
[2] http://docs.openstack.org/developer/magnum/
[3] https://blueprints.launchpad.net/magnum/+spec/refactor-heat-templates
[4] https://github.com/docker/libnetwork/blob/master/docs/design.md
[5] https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/networking.md
[6] https://github.com/coreos/flannel
[7] https://github.com/coreos/rkt/blob/master/Documentation/networking.md
[8] https://github.com/openstack/magnum/blob/master/magnum/templates/kubernetes/kubecluster.yaml
[9] https://blueprints.launchpad.net/magnum/+spec/expand-labels-scope
[10] https://github.com/openstack/kuryr
.. [1] https://blueprints.launchpad.net/magnum/+spec/common-plugin-framework
.. [2] http://docs.openstack.org/developer/magnum/
.. [3] https://blueprints.launchpad.net/magnum/+spec/refactor-heat-templates
.. [4] https://github.com/docker/libnetwork/blob/master/docs/design.md
.. [5] https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/networking.md
.. [6] https://github.com/coreos/flannel
.. [7] https://github.com/coreos/rkt/blob/master/Documentation/networking.md
.. [8] https://github.com/openstack/magnum/blob/master/magnum/templates/kubernetes/kubecluster.yaml
.. [9] https://blueprints.launchpad.net/magnum/+spec/expand-labels-scope
.. [10] https://github.com/openstack/kuryr

62
specs/container-volume-integration-model.rst
View File

@ -39,7 +39,7 @@ In this area, the support for container volume is undergoing rapid change
to bring more integration with open source software and third party
storage solutions.
A clear evidence of this growth is the many plugin volume drivers [1][3]
A clear evidence of this growth is the many plugin volume drivers [1]_ [4]_
such as NFS, GlusterFS, EBS, etc. They provide different functionality, use
different storage backend and have different requirements. The COE's are
naturally motivated to be flexible and allow as many choices as possible for
@ -93,7 +93,7 @@ Volume plugin
COE specific code that supports the functionality of a type of volume.
Additional Magnum definitions can be found in the Magnum Developer
documentation[7].
documentation[7]_ .
Use Cases
----------
@ -173,8 +173,8 @@ We propose extending Magnum as follows.
rexray, flocker, nfs, glusterfs, etc..
Here is an example of creating a Docker Swarm baymodel that uses rexray[5][6]
as the volume driver: ::
Here is an example of creating a Docker Swarm baymodel that uses rexray [5]_
[6]_ as the volume driver: ::
magnum baymodel-create --name swarmbaymodel \
@ -193,11 +193,11 @@ We propose extending Magnum as follows.
then the REX-Ray volume plugin will be registered in Docker. When a container
is created with rexray as the volume driver, the container will have full
access to the REX-Ray capabilities such as creating, mounting, deleting
volumes [6]. REX-Ray in turn will interface with Cinder to manage the volumes
in OpenStack.
volumes [6]_. REX-Ray in turn will interface with Cinder to manage the
volumes in OpenStack.
Here is an example of creating a Kubernetes baymodel that uses Cinder [2][3]
as the volume driver: ::
Here is an example of creating a Kubernetes baymodel that uses Cinder [2]_
[3]_ as the volume driver: ::
magnum baymodel-create --name k8sbaymodel \
--image-id fedora-21-atomic-5 \
@ -237,7 +237,7 @@ volume driver: ::
When the mesos bay is created using this bay model, the mesos bay will be
configured so that an existing Cinder volume can be mounted in a container
by configuring the parameters to mount the cinder volume in the json file. ::
by configuring the parameters to mount the cinder volume in the json file. ::
"parameters": [
{ "key": "volume-driver", "value": "rexray" },
@ -378,7 +378,7 @@ performance.
An example of the second case is a docker swarm bay with
"--volume-driver rexray" where the rexray driver's storage provider is
OpenStack cinder. The resulting performance for container may vary depending
on the storage backends. As listed in [8], Cinder supports many storage
on the storage backends. As listed in [8]_ , Cinder supports many storage
drivers. Besides this, different container volume driver can also cause
performance variance.
@ -403,11 +403,11 @@ High-Availablity Impact
Kubernetes does support pod high-availability through the replication
controller, however, this doesn't work when a pod with volume attached
fails. Refer the link [11] for details.
fails. Refer the link [11]_ for details.
Docker swarm doesn't support the containers reschduling when a node fails, so
volume can not be automatically detached by volume driver. Refer the
link [12] for details.
link [12]_ for details.
Mesos supports the application high-availability when a node fails, which
means application would be started on new node, and volumes can be
@ -484,29 +484,17 @@ configuration flags introduced by this document. Additionally, background
information on how to use these flags will be included.
References
==========
[1] http://kubernetes.io/v1.1/docs/user-guide/volumes.html
[2] http://kubernetes.io/v1.1/examples/mysql-cinder-pd/
[3] https://github.com/kubernetes/kubernetes/tree/master/pkg/volume/cinder
[3] http://docs.docker.com/engine/extend/plugins/
[4] https://docs.docker.com/engine/userguide/dockervolumes/
[5] https://github.com/emccode/rexray
[6] http://rexray.readthedocs.org/en/stable/user-guide/storage-providers/openstack
[7] http://docs.openstack.org/developer/magnum/
[8] http://docs.openstack.org/liberty/config-reference/content/section_volume-drivers.html
[9] http://docs.openstack.org/admin-guide-cloud/blockstorage_multi_backend.html#
[10] http://docs.openstack.org/user-guide-admin/dashboard_manage_volumes.html
[11] https://github.com/kubernetes/kubernetes/issues/14642
[12] https://github.com/docker/swarm/issues/1488
.. [1] http://kubernetes.io/v1.1/docs/user-guide/volumes.html
.. [2] http://kubernetes.io/v1.1/examples/mysql-cinder-pd/
.. [3] https://github.com/kubernetes/kubernetes/tree/master/pkg/volume/cinder
.. [4] http://docs.docker.com/engine/extend/plugins/
.. [5] https://github.com/emccode/rexray
.. [6] http://rexray.readthedocs.org/en/stable/user-guide/storage-providers/openstack
.. [7] http://docs.openstack.org/developer/magnum/
.. [8] http://docs.openstack.org/liberty/config-reference/content/section_volume-drivers.html
.. [9] http://docs.openstack.org/admin-guide-cloud/blockstorage_multi_backend.html#
.. [10] http://docs.openstack.org/user-guide-admin/dashboard_manage_volumes.html
.. [11] https://github.com/kubernetes/kubernetes/issues/14642
.. [12] https://github.com/docker/swarm/issues/1488

12
specs/resource-quotas.rst
View File

@ -68,7 +68,7 @@ Mitaka.
When a project is created and if the Magnum service is running, the default
quota for Magnum resources will be set by the values configured in magnum.conf.
Other Openstack projects like Nova [3], Cinder [4] follow a similar pattern
Other Openstack projects like Nova [2]_, Cinder [3]_ follow a similar pattern
and we will also do so and hence won't have a seperate CLI for quota-create.
Later if the user wants to change the Quota of the resource option will be
provided to do so using magnum quota-update. In situation where all of the
@ -114,7 +114,7 @@ At present there is not quota infrastructure in Magnum.
Adding Quota Management layer at the Orchestration layer, Heat, could be an
alternative. Doing so will give a finer view of resource consumption at the
IaaS layer which can be used while provisioning Magnum resources which
depend on the IaaS layer [1].
depend on the IaaS layer [1]_.
Data model impact
-----------------
@ -247,8 +247,6 @@ None
References
==========
[1] http://lists.openstack.org/pipermail/openstack-dev/2015-December/082266.html
[2] https://github.com/openstack/nova/blob/master/nova/quota.py
[3] https://github.com/openstack/nova/blob/master/cinder/quota.py
.. [1] http://lists.openstack.org/pipermail/openstack-dev/2015-December/082266.html
.. [2] https://github.com/openstack/nova/blob/master/nova/quota.py
.. [3] https://github.com/openstack/nova/blob/master/cinder/quota.py