diff --git a/doc/admin-guide-cloud/roadmap.rst b/doc/admin-guide-cloud/roadmap.rst index 85ea73ce38..23594088ea 100644 --- a/doc/admin-guide-cloud/roadmap.rst +++ b/doc/admin-guide-cloud/roadmap.rst @@ -8,18 +8,21 @@ review up on review.openstack.org. May 20, 2014 To do tasks: - Add a chapter describing monitoring; deeper dive into Telemetry (ceilomter) -- Update networking information with the goal of starting a new Network Admin Guide* +- Update networking information with the goal of starting a new + Network Admin Guide* - Add more networking diagrams - Add audience information; who is this book intended for Ongoing tasks: - Ensure it meets conventions and standards -- Continually update with latest OpenStack dashboard (horizon) information -including great descriptions of fields and why you set a setting +- Continually update with latest OpenStack dashboard (horizon) + information including great descriptions of fields and why you set a + setting - Continually add Python examples to SDK chapter Wishlist tasks: -- Replace all individual client commands (like keystone, nova) with openstack client -commands +- Replace all individual client commands (like keystone, nova) with + openstack client commands -* At Pycon Australia in August, a one-day "swarm" will focus on the Network Admin Guide +* At Pycon Australia in August, a one-day "swarm" will focus on the + Network Admin Guide diff --git a/doc/cli-reference/generated/README.rst b/doc/cli-reference/generated/README.rst index 6a64b80574..94f5b018f4 100644 --- a/doc/cli-reference/generated/README.rst +++ b/doc/cli-reference/generated/README.rst @@ -7,4 +7,3 @@ tool from the openstack-doc-tools package. Do not change these files - change openstack-auto-commands and the python commands itself. - diff --git a/doc/cli-reference/roadmap.rst b/doc/cli-reference/roadmap.rst index 898a7cc8b2..625792af86 100644 --- a/doc/cli-reference/roadmap.rst +++ b/doc/cli-reference/roadmap.rst @@ -12,7 +12,9 @@ To do tasks: Ongoing tasks: - Ensure it meets conventions and standards -- Continually add CLI commands for integrated projects; but only when the release occurs +- Continually add CLI commands for integrated projects; but only when + the release occurs Wishlist tasks: -- Add troubleshooting for clients - installation, environment variables. Can be common. +- Add troubleshooting for clients - installation, environment + variables. Can be common. diff --git a/doc/config-reference/roadmap.rst b/doc/config-reference/roadmap.rst index c4a1919b12..9cbdae7b3c 100644 --- a/doc/config-reference/roadmap.rst +++ b/doc/config-reference/roadmap.rst @@ -7,15 +7,17 @@ review up on review.openstack.org. May 20, 2014 To do tasks: -- Add a chapter showing differences from release-to-release of renamed and removed options +- Add a chapter showing differences from release-to-release of renamed + and removed options - Add descriptions that describe why you would set a setting - Add information about additional options affected (in groups of settings) - Add audience information; who is this book intended for Ongoing tasks: - Ensure it meets conventions and standards -- Continually update with latest reference information including great descriptions -of options and why you set a setting or groups of settings +- Continually update with latest reference information including great + descriptions of options and why you set a setting or groups of + settings Wishlist tasks: - Can distros like Ubuntu produce documented config files? diff --git a/doc/hot-guide/source/hot_guide.rst b/doc/hot-guide/source/hot_guide.rst index 2c2816223b..87bf8aba22 100644 --- a/doc/hot-guide/source/hot_guide.rst +++ b/doc/hot-guide/source/hot_guide.rst @@ -17,8 +17,9 @@ Heat Orchestration Template (HOT) Guide ======================================= -HOT is a new template format meant to replace the Heat CloudFormation-compatible -format (CFN) as the native format supported by the Heat over time. +HOT is a new template format meant to replace the Heat +CloudFormation-compatible format (CFN) as the native format supported +by the Heat over time. This guide is targeted towards template authors and explains how to write HOT templates based on examples. A detailed specification of HOT can be found at :ref:`hot_spec`. @@ -27,10 +28,10 @@ at :ref:`hot_spec`. Status ------ -HOT support is still under development and needs more work to provide access to -all functionality currently available via the CFN compatible template interface. -This guide will be updated periodically whenever new features get implemented -for HOT. +HOT support is still under development and needs more work to provide +access to all functionality currently available via the CFN compatible +template interface. This guide will be updated periodically whenever +new features get implemented for HOT. ---------------------------------- Writing a hello world HOT template @@ -60,11 +61,12 @@ deploy a single compute instance. image: F18-x86_64-cfntools flavor: m1.small -Each HOT template has to include the *heat_template_version* key with value -'2013-05-23' (the current version of HOT). While the *description* is optional, -it is good practice to include some useful text that describes what users can do -with the template. In case you want to provide a longer description that does -not fit on a single line, you can provide multi-line text in YAML, for example: +Each HOT template has to include the *heat_template_version* key with +value '2013-05-23' (the current version of HOT). While the +*description* is optional, it is good practice to include some useful +text that describes what users can do with the template. In case you +want to provide a longer description that does not fit on a single +line, you can provide multi-line text in YAML, for example: :: @@ -76,20 +78,21 @@ The *resources* section is required and must contain at least one resource definition. In the example above, a compute instance is defined with fixed values for the 'key_name', 'image' and 'flavor' parameters. -Note that all those elements, i.e. a key-pair with the given name, the image and -the flavor have to exist in the OpenStack environment where the template is -used. Typically a template is made more easily reusable, though, by defining a -set of *input parameters* instead of hard-coding such values. +Note that all those elements, i.e. a key-pair with the given name, the +image and the flavor have to exist in the OpenStack environment where +the template is used. Typically a template is made more easily +reusable, though, by defining a set of *input parameters* instead of +hard-coding such values. Template input parameters ------------------------- -Input parameters defined in the *parameters* section of a HOT template (see also -:ref:`hot_spec_parameters`) allow users to customize a template during -deployment. For example, this allows for providing custom key-pair names or -image IDs to be used for a deployment. -From a template author's perspective, this helps to make a template more easily -reusable by avoiding hardcoded assumptions. +Input parameters defined in the *parameters* section of a HOT template +(see also :ref:`hot_spec_parameters`) allow users to customize a +template during deployment. For example, this allows for providing +custom key-pair names or image IDs to be used for a deployment. +From a template author's perspective, this helps to make a template +more easily reusable by avoiding hardcoded assumptions. Sticking to the example used above, it makes sense to allow users to provide their custom key-pairs, provide their own image, and to select a flavor for the @@ -130,10 +133,11 @@ resource properties have been replaced by references to the corresponding input parameters by means of the *get_param* function (see also :ref:`hot_spec_intrinsic_functions`). -You can also define default values for input parameters which will be used in -case the user does not provide the respective parameter during deployment. For -example, the following definition for the *instance_type* parameter would select -the 'm1.small' flavor unless specified otherwise by the user. +You can also define default values for input parameters which will be +used in case the user does not provide the respective parameter during +deployment. For example, the following definition for the +*instance_type* parameter would select the 'm1.small' flavor unless +specified otherwise by the user. :: @@ -161,14 +165,15 @@ passwords as user input: Restricting user input ~~~~~~~~~~~~~~~~~~~~~~ -In some cases you might want to restrict the values of input parameters that -users can supply. For example, you might know that the software running in a -compute instance needs a certain amount of resources so you might want to -restrict the *instance_type* parameter introduced above. Parameters in HOT -templates can be restricted by adding a *constraints* section (see also +In some cases you might want to restrict the values of input +parameters that users can supply. For example, you might know that the +software running in a compute instance needs a certain amount of +resources so you might want to restrict the *instance_type* parameter +introduced above. Parameters in HOT templates can be restricted by +adding a *constraints* section (see also :ref:`hot_spec_parameters_constraints`). -For example, the following would allow only three values to be provided as input -for the *instance_type* parameter: +For example, the following would allow only three values to be +provided as input for the *instance_type* parameter: :: diff --git a/doc/hot-guide/source/hot_spec.rst b/doc/hot-guide/source/hot_spec.rst index a5ce5acbc6..74e1b68827 100644 --- a/doc/hot-guide/source/hot_spec.rst +++ b/doc/hot-guide/source/hot_spec.rst @@ -17,22 +17,23 @@ Heat Orchestration Template (HOT) Specification =============================================== -HOT is a new template format meant to replace the Heat CloudFormation-compatible -format (CFN) as the native format supported by the Heat over time. -This specification explains in detail all elements of the HOT template format. -An example driven guide to writing HOT templates can be found -at :ref:`hot_guide`. +HOT is a new template format meant to replace the Heat +CloudFormation-compatible format (CFN) as the native format supported +by the Heat over time. This specification explains in detail all +elements of the HOT template format. An example driven guide to +writing HOT templates can be found at :ref:`hot_guide`. ------ Status ------ HOT is considered reliable, supported, and standardized as of our -Icehouse (April 2014) release. The Heat core team may make improvements -to the standard, which very likely would be backward compatible. The template -format is also versioned. In our Juno release, Heat will support multiple -different versions of the HOT specification if there is a need driven by the -introduction of new features. +Icehouse (April 2014) release. The Heat core team may make +improvements to the standard, which very likely would be backward +compatible. The template format is also versioned. In our Juno +release, Heat will support multiple different versions of the HOT +specification if there is a need driven by the introduction of new +features. ------------------ @@ -74,9 +75,9 @@ parameter_groups *optional* and can be omitted when necessary. parameters - This section allows for specifying input parameters that have to be provided - when instantiating the template. The section is *optional* and can be - omitted when no input is required. + This section allows for specifying input parameters that have to + be provided when instantiating the template. The section is + *optional* and can be omitted when no input is required. resources This section contains the declaration of the single resources of the @@ -85,9 +86,9 @@ resources instantiated. outputs - This section allows for specifying output parameters available to users once - the template has been instantiated. This section is *optional* and can be - omitted when no output values are required. + This section allows for specifying output parameters available to + users once the template has been instantiated. This section is + *optional* and can be omitted when no output values are required. .. _hot_spec_parameter_groups: @@ -165,12 +166,12 @@ type are *string*, *number*, *comma_delimited_list*, *json*, or *boolean*. label - This *optional* attribute allows for giving a human readable name of the - parameter. + This *optional* attribute allows for giving a human readable name + of the parameter. description - This *optional* attribute allows for giving a human readable description of - the parameter. + This *optional* attribute allows for giving a human readable + description of the parameter. default This *optional* attribute allows for defining a default value for the @@ -209,13 +210,13 @@ provide a useful description and label for each parameter. Parameter Constraints --------------------- -The *constraints* block of a parameter definition allows for defining additional -validation constraints that apply to the value of the parameter. At -instantiation time of the template, user provided parameter values are validated -against those constraints to make sure the provided values match expectations of -the template author. -Constraints are defined in the form of a bulleted list according to the -following syntax: +The *constraints* block of a parameter definition allows for defining +additional validation constraints that apply to the value of the +parameter. At instantiation time of the template, user provided +parameter values are validated against those constraints to make sure +the provided values match expectations of the template author. +Constraints are defined in the form of a bulleted list according to +the following syntax: :: @@ -331,9 +332,9 @@ For example: allowed_pattern ~~~~~~~~~~~~~~~ -The *allowed_pattern* constraint applies to parameters of type string and allows -for specifying a regular expression against which a user provided parameter -value must evaluate at deployment. +The *allowed_pattern* constraint applies to parameters of type string +and allows for specifying a regular expression against which a user +provided parameter value must evaluate at deployment. The syntax of the allowed_pattern constraint is: :: @@ -399,11 +400,11 @@ via the `get_param`_ intrinsic function just like user-defined parameters. Resources Section ----------------- -In the *resources* section, the templates for actual resources that will make up -a stack deployed from the HOT template (e.g. compute instances, networks, -storage volumes) are defined. -Each resource is defined as a separate block in the resources section according -to the syntax below. +In the *resources* section, the templates for actual resources that +will make up a stack deployed from the HOT template (e.g. compute +instances, networks, storage volumes) are defined. +Each resource is defined as a separate block in the resources section +according to the syntax below. :: @@ -506,10 +507,10 @@ following example: Outputs Section --------------- -In the *outputs* section, any output parameters that should be available to the -user can be defined. Typically, this would be, for example, parameters such as -IP addresses of deployed instances, or URLs of web applications deployed as part -of a stack. +In the *outputs* section, any output parameters that should be +available to the user can be defined. Typically, this would be, for +example, parameters such as IP addresses of deployed instances, or +URLs of web applications deployed as part of a stack. Each output parameter is defined as a separate block within the outputs section according to the following syntax: @@ -522,8 +523,8 @@ according to the following syntax: value: parameter name - An output parameter block is headed by the output parameter name, which must - be unique within the outputs section of a template. + An output parameter block is headed by the output parameter name, + which must be unique within the outputs section of a template. description This element gives a short description of the output parameter. parameter value @@ -532,8 +533,8 @@ parameter value of one of the stack's resources (see also :ref:`hot_spec_intrinsic_functions`). -The example below shows, how the IP address of a compute resource can be defined -as an output parameter. +The example below shows, how the IP address of a compute resource can +be defined as an output parameter. :: @@ -556,9 +557,10 @@ below. get_attr -------- -The *get_attr* function allows referencing an attribute of a resource. At -runtime, it will be resolved to the value of an attribute of a resource instance -created from the respective resource definition of the template. +The *get_attr* function allows referencing an attribute of a +resource. At runtime, it will be resolved to the value of an attribute +of a resource instance created from the respective resource definition +of the template. The syntax of the get_attr function is as follows: :: @@ -657,10 +659,10 @@ a *files* dictionary containing entries with keys get_param --------- -The *get_param* function allows for referencing an input parameter of a template -from anywhere within a template. At runtime, it will be resolved to the value -provided for this input parameter. The syntax of the get_param function is as -follows: +The *get_param* function allows for referencing an input parameter of +a template from anywhere within a template. At runtime, it will be +resolved to the value provided for this input parameter. The syntax of +the get_param function is as follows: :: @@ -722,8 +724,8 @@ The syntax of the get_resource function is as follows: get_resource: -The *resource ID* of the referenced resources as used in the current template is -given as single parameter to the get_resource function. +The *resource ID* of the referenced resources as used in the current +template is given as single parameter to the get_resource function. list_join @@ -748,9 +750,14 @@ This would resolve to "one, two, and three". resource_facade --------------- -The *resource_facade* function allows a provider template to retrieve data -about its resource facade in the parent template. (A provider template is used to provide a custom definition of a resource - the facade - in the form of a Heat template. The resource's properties are passed to the provider template as its parameters, but other resource data can be included using this function.) -The syntax of the *resource_facade* function is as follows:: + +The *resource_facade* function allows a provider template to retrieve +data about its resource facade in the parent template. (A provider +template is used to provide a custom definition of a resource - the +facade - in the form of a Heat template. The resource's properties are +passed to the provider template as its parameters, but other resource +data can be included using this function.) The syntax of the +*resource_facade* function is as follows:: resource_facade: @@ -800,8 +807,9 @@ section of a template to build a URL for logging into a deployed application. params: host: { get_attr: [ my_instance, first_address ] } -The str_replace function can also be used for constructing bigger chunks of text -like scripts for initializing compute instances as shown in the example below: +The str_replace function can also be used for constructing bigger +chunks of text like scripts for initializing compute instances as +shown in the example below: :: diff --git a/doc/image-guide/roadmap.rst b/doc/image-guide/roadmap.rst index 6afdb22112..e387d36176 100644 --- a/doc/image-guide/roadmap.rst +++ b/doc/image-guide/roadmap.rst @@ -7,12 +7,13 @@ review up on review.openstack.org. May 21, 2014 To do tasks: -- Add a chapter describing how to make an image for Database as a Service (trove) +- Add a chapter describing how to make an image for Database as a + Service (trove) - Add audience information; who is this book intended for Ongoing tasks: - Ensure it meets conventions and standards Wishlist tasks: -- Replace all individual client commands (like keystone, glance) with openstack client -commands +- Replace all individual client commands (like keystone, glance) with + openstack client commands diff --git a/doc/install-guide/roadmap.rst b/doc/install-guide/roadmap.rst index a417abbe58..eb5bcf0252 100644 --- a/doc/install-guide/roadmap.rst +++ b/doc/install-guide/roadmap.rst @@ -15,8 +15,8 @@ To do tasks: - Unify chapter and section names (such as Overview) - Add sample output of each command and highlight important parts - Mention project as standard but tenant must be used for CLI params -- Refer to generic SQL database and update for MariaDB (RHEL), MySQL, and -PostgreSQL +- Refer to generic SQL database and update for MariaDB (RHEL), MySQL, + and PostgreSQL - Provide sample configuration files for each node - Compute and network nodes should reference server on controller node - Update password list @@ -27,4 +27,5 @@ Ongoing tasks: - Continually update with latest release information relevant to install Wishlist tasks: -- Replace all individual client commands (like keystone, nova) with openstack client commands +- Replace all individual client commands (like keystone, nova) with + openstack client commands diff --git a/doc/user-guide-admin/roadmap.rst b/doc/user-guide-admin/roadmap.rst index 2c1c4ed1b3..b658ca68e0 100644 --- a/doc/user-guide-admin/roadmap.rst +++ b/doc/user-guide-admin/roadmap.rst @@ -11,12 +11,16 @@ To do tasks: Ongoing tasks: - Ensure it meets conventions and standards -- Continually update with latest OpenStack dashboard (horizon) information -including great descriptions of fields and why you set a setting +- Continually update with latest OpenStack dashboard (horizon) + information including great descriptions of fields and why you set a + setting Wishlist tasks: -- Get examples of common tasks from real admins and add to this guide as how-to: migration of VM from one host to another, quota management, targeting launch on a particular compute node +- Get examples of common tasks from real admins and add to this guide + as how-to: migration of VM from one host to another, quota + management, targeting launch on a particular compute node - Create flavor example - also refer to from Ops Guide (Anne Gentle todo) - Migrations examples (Anne Gentle todo) - Create tenant example with CLI -- Replace all individual client commands (like keystone, nova) with openstack client commands +- Replace all individual client commands (like keystone, nova) with + openstack client commands diff --git a/doc/user-guide/roadmap.rst b/doc/user-guide/roadmap.rst index dcbf398538..166a5f7ad6 100644 --- a/doc/user-guide/roadmap.rst +++ b/doc/user-guide/roadmap.rst @@ -8,16 +8,19 @@ review up on review.openstack.org. May 20, 2014 To do tasks: - Add a chapter describing the HOT templates for Orchestration, how to use them -- Add reference information about HOT templates for Orchestration; attempt to automate +- Add reference information about HOT templates for Orchestration; + attempt to automate Ongoing tasks: - Ensure it meets conventions and standards -- Continually update with latest OpenStack dashboard (horizon) information -including great descriptions of fields and why you set a setting +- Continually update with latest OpenStack dashboard (horizon) + information including great descriptions of fields and why you set a + setting - Continually add Python examples to SDK chapter Wishlist tasks: - Investigate moving to simpler markup and still enabling translation -- Replace all individual client commands (like keystone, nova) with openstack client -commands -- Create a new security group, boot a VM, and then add the newly created security group to the running VM +- Replace all individual client commands (like keystone, nova) with + openstack client commands +- Create a new security group, boot a VM, and then add the newly + created security group to the running VM