From f3ec1b5dacd8167d23e3c6a8b79c608aa840ee34 Mon Sep 17 00:00:00 2001 From: Sergey Kraynev Date: Mon, 26 Dec 2016 15:22:21 +0400 Subject: [PATCH] Replace all remained tables on list_tables Previously graphic representation was used, but we also can use list-tables as mentioned in documentation: http://docs.openstack.org/contributor-guide/rst-conv/tables.html This change it and introduce same format for tables on the page. Change-Id: Icc55f135b7eed6cd3988ac8a938e1eaf7bbdf6bd --- doc/source/bootstrapping.rst | 131 +++++++------ doc/source/config/types.rst | 207 ++++++++++++-------- doc/source/dsl.rst | 359 +++++++++++++++++++++++------------ 3 files changed, 441 insertions(+), 256 deletions(-) diff --git a/doc/source/bootstrapping.rst b/doc/source/bootstrapping.rst index 53ce7bc1..cf52061a 100755 --- a/doc/source/bootstrapping.rst +++ b/doc/source/bootstrapping.rst @@ -46,56 +46,69 @@ Snippet below demonstrates all available options: First part configures internal network. All options have default values: -+-------------+-----------------------------------------------+---------------+ -| Name | Description | Default | -+=============+===============================================+===============+ -| enable | boolean flag, which turns on/off bootstrap. | true | -+-------------+-----------------------------------------------+---------------+ -| net_name | Name of the internal network, which will be | int-net | -| | created in neutron. | | -+-------------+-----------------------------------------------+---------------+ -| subnet_name | Name of the subnet in internal network, which | int-subnet | -| | will be created in neutron. | | -+-------------+-----------------------------------------------+---------------+ -| network | CIDR of the internal network for allocating | 10.0.1.0/24 | -| | internal IP addresses. | | -+-------------+-----------------------------------------------+---------------+ -| gateway | Gateway for subnet in the internal network. | 10.0.1.1 | -+-------------+-----------------------------------------------+---------------+ +.. list-table:: **Internal network configuration options** + :widths: 10 25 10 + :header-rows: 1 + + * - Name + - Description + - Default + * - enable + - boolean flag, which turns on/off bootstrap. + - true + * - net_name + - Name of the internal network, which will be created in neutron. + - int-net + * - subnet_name + - Name of the subnet in internal network, which will be created in + neutron. + - int-subnet + * - network + - CIDR of the internal network for allocating internal IP addresses. + - 10.0.1.0/24 + * - gateway + - Gateway for subnet in the internal network. + - 10.0.1.1 Second part describes external network configuration. Bootstrapping for external network is disabled by default and user should specify all options after turning it on, because most of them don't have default values. -+-------------+-----------------------------------------------+---------------+ -| Name | Description | Default | -+=============+===============================================+===============+ -| enable | boolean flag, which turns on/off bootstrap. | false | -+-------------+-----------------------------------------------+---------------+ -| net_name | Name of the external network, which will be | ext-net | -| | created in neutron. Default value can be used.| | -+-------------+-----------------------------------------------+---------------+ -| subnet_name | Name of the subnet in external network, which | ext-subnet | -| | will be created in neutron. Default value can | | -| | be used. | | -+-------------+-----------------------------------------------+---------------+ -| physnet | Name of the physnet, which was defined in | | -| | **physnets** section. | | -+-------------+-----------------------------------------------+---------------+ -| network | CIDR of the external network for allocating | | -| | external IP addresses. | | -+-------------+-----------------------------------------------+---------------+ -| gateway | Gateway for subnet in the external network. | | -+-------------+-----------------------------------------------+---------------+ -| nameserver | DNS server for subnet in external network. | | -+-------------+-----------------------------------------------+---------------+ -| pool | Pool of the addresses from external network, | | -| | which can be used for association with | | -| | Openstack VMs. | | -| | Should be specified by using nested keys: | | -| | **start** and **end**, which requires | | -| | corresponding IP addresses. | | -+-------------+-----------------------------------------------+---------------+ +.. list-table:: **External network configuration options** + :widths: 10 25 10 + :header-rows: 1 + + * - Name + - Description + - Default + * - enable + - boolean flag, which turns on/off bootstrap. + - false + * - net_name + - Name of the external network, which will be created in neutron. Default + value can be used. + - ext-net + * - subnet_name + - Name of the subnet in external network, which will be created in + neutron. Default value can be used. + - ext-subnet + * - physnet + - Name of the physnet, which was defined in **physnets** section. + - -- + * - network + - CIDR of the external network for allocating external IP addresses. + - -- + * - gateway + - Gateway for subnet in the external network. + - -- + * - nameserver + - DNS server for subnet in external network. + - -- + * - pool + - Pool of the addresses from external network, which can be used for + association with Openstack VMs. Should be specified by using nested + keys: **start** and **end**, which requires corresponding IP addresses. + - -- The last section is a router configuration. It allows to specify name of the router, which will be created in neutron. Both networks will be connected with @@ -174,17 +187,23 @@ The last part of the snippet describes image specific options. All options should be specified, othrwise it will cause an error during job execution: -+-------------+-----------------------------------------------+---------------------------------------------------------------------+ -| Name | Description | Default | -+=============+===============================================+=====================================================================+ -| url | url, which will be used for downloading image.| http://download.cirros-cloud.net/0.3.4/cirros-0.3.4-x86_64-disk.img | -+-------------+-----------------------------------------------+---------------------------------------------------------------------+ -| disk_format | format of the image which will be used during | qcow2 | -| | image creation in the glance. | | -+-------------+-----------------------------------------------+---------------------------------------------------------------------+ -| name | name of the image, which will be created | cirros | -| | in the glance. | | -+-------------+-----------------------------------------------+---------------------------------------------------------------------+ +.. list-table:: **Glance image bootstrapping default configuration options** + :widths: 10 25 10 + :header-rows: 1 + + * - Name + - Description + - Default + * - url + - url, which will be used for downloading image. + - http://download.cirros-cloud.net/0.3.4/cirros-0.3.4-x86_64-disk.img + * - disk_format + - format of the image which will be used during image creation in the + glance. + - qcow2 + * - name + - name of the image, which will be created in the glance. + - cirros Creation of the image is handled by glance post deployment job **glance-cirros-image-upload**, which uses Bash script from fuel-ccp-glance diff --git a/doc/source/config/types.rst b/doc/source/config/types.rst index d100efe5..862aa358 100644 --- a/doc/source/config/types.rst +++ b/doc/source/config/types.rst @@ -149,23 +149,35 @@ Allowed content: - This key has the following list of sub-keys: -+--------------------------------+----------------------------------+----------+------------+ -| Name | Description | Schema | Default | -+================================+==================================+==========+============+ -| workers | Number of the workers, which | integer | number of | -| | will be used during building | | CPU in the | -| | component images. | | system | -+--------------------------------+----------------------------------+----------+------------+ -| keep_image_tree_consistency | Rebuld dependent images, if base | boolean | True | -| | image was rebuilt. | | | -+--------------------------------+----------------------------------+----------+------------+ -| build_base_images_if_not_exist | Forces base image building. | boolean | True | -+--------------------------------+----------------------------------+----------+------------+ -| push | Push images to docker registry. | boolean | False | -+--------------------------------+----------------------------------+----------+------------+ -| no_cache | Do not use docker caching during | | | -| | building images. | boolean | False | -+--------------------------------+----------------------------------+----------+------------+ +.. list-table:: + :widths: 10 25 10 10 + :header-rows: 1 + + * - Name + - Description + - Schema + - Default + * - workers + - Number of the workers, which will be used during building component + images. + - integer + - number of CPU in the system + * - keep_image_tree_consistency + - Rebuld dependent images, if base image was rebuilt. + - boolean + - True + * - build_base_images_if_not_exist + - Forces base image building. + - boolean + - True + * - push + - Push images to docker registry. + - boolean + - False + * - no_cache + - Do not use docker caching during building images. + - boolean + - False .. _versions: @@ -289,27 +301,42 @@ Allowed content: - This key has the following list of sub-keys: -+--------------+----------------------------------+----------+----------------------------------------------------+ -| Name | Description | Schema | Default | -+==============+==================================+==========+====================================================+ -| namespace | Namespace which should be used | string | ccp | -| | for **ccp** related images. | | | -+--------------+----------------------------------+----------+----------------------------------------------------+ -| tag | Tag for **ccp** related images. | string | latest | -+--------------+----------------------------------+----------+----------------------------------------------------+ -| base_distro | Base image for building **ccp** | string | debian | -| | images. | | | -+--------------+----------------------------------+----------+----------------------------------------------------+ -| base_tag | Tag of the base image for bulding| string | jessie | -| | **ccp** images. | | | -+--------------+----------------------------------+----------+----------------------------------------------------+ -| base_images | Names of base images. | array of | ['base'] | -| | | strings | | -+--------------+----------------------------------+----------+----------------------------------------------------+ -| maintainer | Maintainer of **ccp** images. | string | MOS Microservices | -+--------------+----------------------------------+----------+----------------------------------------------------+ -| image_specs | Extra keys for building images. | json | | -+--------------+----------------------------------+----------+----------------------------------------------------+ +.. list-table:: + :widths: 10 25 10 10 + :header-rows: 1 + + * - Name + - Description + - Schema + - Default + * - namespace + - Namespace which should be used for **ccp** related images. + - string + - ccp + * - tag + - Tag for **ccp** related images. + - string + - latest + * - base_distro + - Base image for building **ccp** images. + - string + - debian + * - base_tag + - Tag of the base image for bulding **ccp** images. + - string + - jessie + * - base_images + - Names of base images. + - array of strings + - ['base'] + * - maintainer + - Maintainer of **ccp** images. + - string + - MOS Microservices + * - image_specs + - Extra keys for building images. + - json + - -- .. _configs: @@ -376,32 +403,43 @@ Allowed content: - This key has the following list of sub-keys: -+----------------+----------------------------------+----------+-----------------------+ -| Name | Description | Schema | Default | -+================+==================================+==========+=======================+ -| server | URL for accessing of Kubernetes | string | http://localhost:8080 | -| | API. | | | -+----------------+----------------------------------+----------+-----------------------+ -| namespace | Namespace which will be created | string | ccp | -| | and used for deploying Openstack.| | | -+----------------+----------------------------------+----------+-----------------------+ -| ca_cert | Path of CA TLS certificate(s) | string | | -| | used to verify the Kubernetes | | | -| | server's certificate. | | | -+----------------+----------------------------------+----------+-----------------------+ -| key_file | Path of client key to use in SSL | string | | -| | connection. | | | -+----------------+----------------------------------+----------+-----------------------+ -| cert_file | Path of certificate file to use | string | | -| | in SSL connection. | | | -+----------------+----------------------------------+----------+-----------------------+ -| insecure | Explicitly allow **ccp** | boolean | False | -| | to perform "insecure SSL" | | | -| | (https) requests. | | | -+----------------+----------------------------------+----------+-----------------------+ -| cluster_domain | Name of the cluster domain. | string | cluster.local | -+----------------+----------------------------------+----------+-----------------------+ +.. list-table:: + :widths: 10 25 10 10 + :header-rows: 1 + * - Name + - Description + - Schema + - Default + * - server + - URL for accessing of Kubernetes API. + - string + - http://localhost:8080 + * - namespace + - Namespace which will be created and used for deploying Openstack. + - string + - ccp + * - ca_cert + - Path of CA TLS certificate(s) used to verify the Kubernetes server's + certificate. + - string + - -- + * - key_file + - Path of client key to use in SSL connection. + - string + - -- + * - cert_file + - Path of certificate file to use in SSL connection. + - string + - -- + * - insecure + - Explicitly allow **ccp** to perform "insecure SSL" (https) requests. + - boolean + - False + * - cluster_domain + - Name of the cluster domain. + - string + - cluster.local .. _replicas: @@ -458,21 +496,34 @@ Allowed content: - This key has the following list of sub-keys: -+-----------+------------------------------------+----------+-----------+ -| Name | Description | Schema | Default | -+===========+====================================+==========+===========+ -| address | Address of registry service. | string | | -+-----------+------------------------------------+----------+-----------+ -| insecure | Use insecure connection or not. | boolean | False | -+-----------+------------------------------------+----------+-----------+ -| username | Username to access docker registry.| string | | -+-----------+------------------------------------+----------+-----------+ -| password | Password to access docker registry.| string | | -+-----------+------------------------------------+----------+-----------+ -| timeout | Value, which specifies how long | integer | 300 | -| | the CCP waits response from | | | -| | registry. | | | -+-----------+------------------------------------+----------+-----------+ +.. list-table:: + :widths: 10 25 10 10 + :header-rows: 1 + + * - Name + - Description + - Schema + - Default + * - address + - Address of registry service. + - string + - -- + * - insecure + - Use insecure connection or not. + - boolean + - False + * - username + - Username to access docker registry. + - string + - -- + * - password + - Password to access docker registry. + - string + - -- + * - timeout + - Value, which specifies how long the CCP waits response from registry. + - integer + - 300 This is used to pass information for accessing docker registry. Example can be found in :doc:`quickstart`. diff --git a/doc/source/dsl.rst b/doc/source/dsl.rst index eb1dad47..b98c368d 100644 --- a/doc/source/dsl.rst +++ b/doc/source/dsl.rst @@ -84,72 +84,125 @@ Parameters description service ------- -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| Name | Description | Required | Schema | Default | -+===============+===============================================+==========+==================+===============+ -| name | Name of the service. | true | string | | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| kind | Kind of k8s object to use for containers | false | one of: | Deployment | -| | deployment | | ["Deployment", | | -| | | | "DaemonSet"] | | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| containers | List of containers under multi-container pod | true | container_ array | | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| ports | k8s Service will be created if specified | false | internal-port: | | -| | (with NodePort type for now) | | external-port | | -| | Only internal or both internal:external ports | | array | | -| | can be specified | | | | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| hostNetwork | Use the host’s network namespace | false | boolean | false | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| hostPID | Use the host’s pid namespace | false | boolean | false | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| strategy | The strategy that should be used to replace | false | one of: | RollingUpdate | -| | old Pods by new ones | | ["RollingUpdate",| | -| | | | "Recreate"] | | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| antiAffinity | Restrict scheduling of pods on the same host: | false | one of: | null | -| | local - within namespace | | [null, "global", | | -| | global - within k8s cluster | | "local"] | | -+---------------+-----------------------------------------------+----------+------------------+---------------+ -| annotations | pod - annotations for pods | false | string dict | null | -| | service - annotations for service | | | | -+---------------+-----------------------------------------------+----------+------------------+---------------+ +.. list-table:: + :widths: 10 35 7 15 7 + :header-rows: 1 + + * - Name + - Description + - Required + - Schema + - Default + * - name + - Name of the service. + - true + - string + - -- + * - kind + - Kind of k8s object to use for containers deployment. + - false + - one of: ["Deployment", "DaemonSet"] + - Deployment + * - containers + - List of containers under multi-container pod. + - true + - container_ array + - -- + * - ports + - k8s Service will be created if specified (with NodePort type for now). + Only internal or both internal:external ports can be specified. + - false + - internal-port: external-port array + - -- + * - hostNetwork + - Use the host’s network namespace. + - false + - boolean + - false + * - hostPID + - Use the host’s pid namespace. + - false + - boolean + - false + * - strategy + - The strategy that should be used to replace old Pods by new ones. + - false + - one of: ["RollingUpdate", "Recreate"] + - RollingUpdate + * - antiAffinity + - Restrict scheduling of pods on the same host: + local - within namespace, global - within k8s cluster + - false + - one of: [null, "global", "local"] + - null + * - annotations + - pod - annotations for pods, service - annotations for service. + - false + - string dict + - null .. _container: container --------- -+---------+--------------------------------------------+----------+------------------+---------+ -| Name | Description | Required | Schema | Default | -+=========+============================================+==========+==================+=========+ -| name | Name of the container. It will be used to | true | string | | -| | track status in etcd | | | | -+---------+--------------------------------------------+----------+------------------+---------+ -| image | Name of the image. registry, namespace, | true | string | | -| | tag will be added by framework | | | | -+---------+--------------------------------------------+----------+------------------+---------+ -| probes | Readiness, liveness or both checks can be | false | dict with | | -| | defined. Exec action will be used for both | | two keys: | | -| | checks | | liveness: cmd | | -| | | | readiness: cmd | | -+---------+--------------------------------------------+----------+------------------+---------+ -| volumes | | false | volume_ array | | -+---------+--------------------------------------------+----------+------------------+---------+ -| pre | List of commands that need to be executed | false | command_ array | | -| | before daemon process start | | | | -+---------+--------------------------------------------+----------+------------------+---------+ -| daemon | | true | command_ | | -+---------+--------------------------------------------+----------+------------------+---------+ -| post | The same as for “pre” except that post | false | command_ array | | -| | commands will be executed after daemon | | | | -| | process has been started | | | | -+---------+--------------------------------------------+----------+------------------+---------+ -| env | An array of environment variables defined | false | env_ array | | -| | in kubernetes way. | | | | -| | | | | | -+---------+--------------------------------------------+----------+------------------+---------+ +.. list-table:: + :widths: 10 35 7 15 7 + :header-rows: 1 + + * - Name + - Description + - Required + - Schema + - Default + * - name + - Name of the container. It will be used to track status in etcd. + - true + - string + - -- + * - image + - Name of the image. registry, namespace, tag will be added by framework. + - true + - string + - -- + * - probes + - Readiness, liveness or both checks can be defined. Exec action will be + used for both checks. + - false + - dict with two keys: + + liveness: + cmd + + readiness: + cmd + - -- + * - volumes + - -- + - false + - volume_ array + - -- + * - pre + - List of commands that need to be executed before daemon process start. + - false + - command_ array + - -- + * - daemon + - -- + - true + - command_ + - -- + * - post + - The same as for “pre” except that post commands will be executed after + daemon process has been started. + - false + - command_ array + - -- + * - env + - An array of environment variables defined in kubernetes way. + - false + - env_ array + - -- .. _env: http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_envvar @@ -158,87 +211,149 @@ container volume ------ -+------------+-------------------------------------------+----------+-----------------------+---------+ -| Name | Description | Required | Schema | Default | -+============+===========================================+==========+=======================+=========+ -| name | Name of the volume | true | string | | -+------------+-------------------------------------------+----------+-----------------------+---------+ -| type | host and empty-dir type supported for now | true | one of: | | -| | | | ["host", "empty-dir"] | | -+------------+-------------------------------------------+----------+-----------------------+---------+ -| path | Host path that should be mounted | false | string | | -| | (only if type = "host") | | | | -+------------+-------------------------------------------+----------+-----------------------+---------+ -| mount-path | Mount path in container | false | string | path | -+------------+-------------------------------------------+----------+-----------------------+---------+ -| readOnly | Mount mode of the volume | false | bool | False | -+------------+-------------------------------------------+----------+-----------------------+---------+ +.. list-table:: + :widths: 10 35 7 15 7 + :header-rows: 1 + + * - Name + - Description + - Required + - Schema + - Default + * - name + - Name of the volume. + - true + - string + - -- + * - type + - host and empty-dir type supported for now. + - true + - one of: ["host", "empty-dir"] + - -- + * - path + - Host path that should be mounted (only if type = "host"). + - false + - string + - -- + * - mount-path + - Mount path in container. + - false + - string + - path + * - readOnly + - Mount mode of the volume. + - false + - bool + - False .. _command: command ------- -+--------------+--------------------------------------------+----------+----------------------+---------+ -| Name | Description | Required | Schema | Default | -+==============+============================================+==========+======================+=========+ -| name | Name of the command. Required only for | -- | string | | -| | `pre` and `post` with type `single` | | | | -+--------------+--------------------------------------------+----------+----------------------+---------+ -| command | | true | string | | -+--------------+--------------------------------------------+----------+----------------------+---------+ -| dependencies | These keys will be polled from etcd | false | string array | | -| | before commands execution | | | | -+--------------+--------------------------------------------+----------+----------------------+---------+ -| type | type: single means that this command | false | one of: | local | -| | should be executed once per openstack | | ["single", "local"] | | -| | deployment. For commands with | | | | -| | type: single Job object will be created | | | | -| | | | | | -| | type: local (or if type is not specified) | | | | -| | means that command will be executed | | | | -| | inside the same container as a | | | | -| | daemon process. | | | | -+--------------+--------------------------------------------+----------+----------------------+---------+ -| files | List of the files that maps to the keys | false | file_ keys array | | -| | of files dict. It defines which files will | | | | -| | be rendered inside a container | | | | -+--------------+--------------------------------------------+----------+----------------------+---------+ -| user | | false | string | | -+--------------+--------------------------------------------+----------+----------------------+---------+ +.. list-table:: + :widths: 10 35 7 15 7 + :header-rows: 1 + + * - Name + - Description + - Required + - Schema + - Default + * - name + - Name of the command. Required only for `pre` and `post` with type + `single`. + - -- + - string + - -- + * - command + - -- + - true + - string + - -- + * - dependencies + - These keys will be polled from etcd before commands execution. + - false + - string array + - -- + * - type + - type: single means that this command should be executed once per + openstack deployment. For commands with type: single Job object will be + created. + + type: local (or if type is not specified) means that command will be + executed inside the same container as a daemon process. + - false + - one of: ["single", "local"] + - local + * - files + - List of the files that maps to the keys of files dict. It defines which + files will be rendered inside a container. + - false + - file_ keys array + - -- + * - user + - -- + - false + - string + - -- .. _files: files ----- -+------------------------------+-------------+----------+-------------+---------+ -| Name | Description | Required | Schema | Default | -+==============================+=============+==========+=============+=========+ -| Name of the file to refer in | | false | file_ array | | -| files list of commands | | | | | -+------------------------------+-------------+----------+-------------+---------+ +.. list-table:: + :widths: 35 10 7 15 7 + :header-rows: 1 + + * - Name + - Description + - Required + - Schema + - Default + * - Name of the file to refer in files list of commands + - -- + - false + - file_ array + - -- .. _file: file ---- -+---------+------------------------------------------------+----------+--------+---------+ -| Name | Description | Required | Schema | Default | -+=========+================================================+==========+========+=========+ -| path | Destination path inside a container | true | string | | -+---------+------------------------------------------------+----------+--------+---------+ -| content | Name of the file under | true | string | | -| | {{ service_repo }}/service/files directory. | | | | -| | This file will be rendered inside a container | | | | -| | and moved to the destination defined with path | | | | -+---------+------------------------------------------------+----------+--------+---------+ -| perm | | false | string | | -+---------+------------------------------------------------+----------+--------+---------+ -| user | | false | string | | -+---------+------------------------------------------------+----------+--------+---------+ +.. list-table:: + :widths: 10 35 7 15 7 + :header-rows: 1 + * - Name + - Description + - Required + - Schema + - Default + * - path + - Destination path inside a container. + - true + - string + - -- + * - content + - Name of the file under {{ service_repo }}/service/files directory. This + file will be rendered inside a container and moved to the destination + defined with path. + - true + - string + - -- + * - perm + - -- + - false + - string + - -- + * - user + - -- + - false + - string + - -- DSL versioning ~~~~~~~~~~~~~~