openstack/heat
Code Issues Proposed changes

Docs: use extrefs to link to other projects' docs

Browse Source 
This feature of openstackdocstheme means that we'll always link to the
corresponding branch of another project (i.e. latest links to latest,
but train links to train, &c.)

https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper

Change-Id: If94115f87af3689413405f3283be7fb197fab058
This commit is contained in:
Zane Bitter 2020-01-22 10:32:43 -05:00
parent a7b554cd80
commit dd70d9244d
12 changed files with 74 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/source/admin/auth-model.rst
View File

@ -77,7 +77,8 @@ which is consumed by *only* the trustee to obtain a
such that the trustee has limited access to those such that the trustee has limited access to those
roles delegated. In addition, the trustee has effective impersonation roles delegated. In addition, the trustee has effective impersonation
of the trustor user if it was selected when creating the trust. of the trustor user if it was selected when creating the trust.
For more information, see `Identity Management trusts`_. For more information, see :keystone-doc:`Identity management trusts
<admin/identity-use-trusts.html>`.
Trusts authorization involves the following steps: Trusts authorization involves the following steps:
@ -146,5 +147,3 @@ defined, then all the trustor roles are delegated to trustee.
The trustor delegated roles must be pre-configured in the The trustor delegated roles must be pre-configured in the
OpenStack Identity service before using them in the Orchestration service. OpenStack Identity service before using them in the Orchestration service.
.. _Identity management trusts: https://docs.openstack.org/keystone/latest/admin/identity-use-trusts.html

4
doc/source/admin/introduction.rst
View File

@ -28,5 +28,5 @@ integrated with the OpenStack dashboard to perform stack functions through
a web interface. a web interface.
For more information about using the Orchestration service through the For more information about using the Orchestration service through the
command line, see the `Heat Command-Line Interface reference command line, see the :python-heatclient-doc:`Heat Command-Line Interface
<https://docs.openstack.org/python-heatclient/latest/#openstackclient-command-line>`_. reference <#openstackclient-command-line>`.

5
doc/source/admin/stack-domain-users.rst
View File

@ -125,7 +125,8 @@ The following steps are run during stack creation:
in the stack domain are still assigned the ``heat_stack_user`` role, so in the stack domain are still assigned the ``heat_stack_user`` role, so
the API surface they can access is limited through the API surface they can access is limited through
the :file:`policy.json` file. the :file:`policy.json` file.
For more information, see `OpenStack Identity documentation`_. For more information, see :keystone-doc:`OpenStack Identity documentation
<>`.
#. When API requests are processed, the Orchestration service performs #. When API requests are processed, the Orchestration service performs
an internal lookup, and allows stack details for a given stack to be an internal lookup, and allows stack details for a given stack to be
@ -149,5 +150,3 @@ or::
The stack owner uses the former (via ``openstack stack resource metadata The stack owner uses the former (via ``openstack stack resource metadata
STACK RESOURCE``), and any agents in the instance STACK RESOURCE``), and any agents in the instance
use the latter. use the latter.
.. _OpenStack Identity documentation: https://docs.openstack.org/keystone/latest/

13
doc/source/conf.py
View File

@ -100,6 +100,19 @@ bug_tag = 'docs'
todo_include_todos = True todo_include_todos = True
# openstackdocstheme external link helper projects
openstack_projects = [
'devstack',
'diskimage-builder',
'keystone',
'keystoneauth',
'nova',
'oslo.reports',
'python-barbicanclient',
'python-heatclient',
'python-openstackclient',
]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = [] templates_path = []

2
doc/source/developing_guides/gmr.rst
View File

@ -90,4 +90,4 @@ Extending the GMR
As mentioned above, additional sections can be added to the GMR for a As mentioned above, additional sections can be added to the GMR for a
particular executable. For more information, see the documentation about particular executable. For more information, see the documentation about
`oslo.reports <https://docs.openstack.org/oslo.reports/>`_ :oslo.reports-doc:`oslo.reports <>`.

9
doc/source/getting_started/create_a_stack.rst
View File

@ -118,8 +118,7 @@ Note: The list operation will show no running stack.::
$ openstack stack delete teststack $ openstack stack delete teststack
$ openstack stack list $ openstack stack list
You can explore other heat commands by referring to the `Heat command reference You can explore other heat commands by referring to the
<https://docs.openstack.org/python-heatclient/latest/cli/>`_ for the :python-heatclient-doc:`Heat command reference <cli/>` for the
`OpenStack Command-Line Interface :python-openstackclient-doc:`OpenStack Command-Line Interface <>`; then read
<https://docs.openstack.org/python-openstackclient/>`_; then read the the :ref:`template-guide` and start authoring your own templates.
:ref:`template-guide` and start authoring your own templates.

12
doc/source/glossary.rst
View File

@ -57,10 +57,9 @@
Metadata service Metadata service
A Compute service that enables virtual machine instances to A Compute service that enables virtual machine instances to
retrieve instance-specific data. See `Metadata retrieve instance-specific data. See :nova-doc:`Metadata
service (OpenStack Administrator Guide)`_. service (OpenStack Administrator Guide)
<admin/networking-nova.html#metadata-service>`.
.. _Metadata service (OpenStack Administrator Guide): https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service
Multi-region Multi-region
A feature of Heat that supports deployment to multiple regions. A feature of Heat that supports deployment to multiple regions.
@ -162,10 +161,9 @@
User data User data
A :term:`resource property` that contains a user-provided data A :term:`resource property` that contains a user-provided data
blob. User data gets passed to `cloud-init`_ to automatically blob. User data gets passed to `cloud-init`_ to automatically
configure instances at boot time. See also `User data (OpenStack configure instances at boot time. See also :nova-doc:`User data
End User Guide)`_. (OpenStack End User Guide) <user/user-data.html>`.
.. _User data (OpenStack End User Guide): https://docs.openstack.org/nova/latest/user/user-data.html
.. _cloud-init: https://cloudinit.readthedocs.io/ .. _cloud-init: https://cloudinit.readthedocs.io/
Wait condition Wait condition

3
doc/source/index.rst
View File

@ -80,10 +80,9 @@ Using the Heat Service
---------------------- ----------------------
- `OpenStack Orchestration API v1 Reference`_ - `OpenStack Orchestration API v1 Reference`_
- `Python and CLI client`_ - :python-heatclient-doc:`Python and CLI client <>`
.. _`OpenStack Orchestration API v1 Reference`: https://docs.openstack.org/api-ref/orchestration/v1/ .. _`OpenStack Orchestration API v1 Reference`: https://docs.openstack.org/api-ref/orchestration/v1/
.. _`Python and CLI client`: https://docs.openstack.org/python-heatclient/latest
Developing Heat Developing Heat
=============== ===============

15
doc/source/install/install-rdo.rst
View File

@ -74,14 +74,13 @@ requires additional information in the Identity service.
.. note:: .. note::
If installing OpenStack manually following the `Keystone install If installing OpenStack manually following the :keystone-doc:`Keystone
guide`_, the name of the services project is ``service`` as given install guide <install/keystone-users-rdo.html>`, the name of the
above. However, traditional methods of installing RDO (such as services project is ``service`` as given above. However, traditional
PackStack and TripleO) use ``services`` as the name of the service methods of installing RDO (such as PackStack and TripleO) use
project. If you installed RDO using a Puppet-based method, substitute ``services`` as the name of the service project. If you installed RDO
``services`` as the project name. using a Puppet-based method, substitute ``services`` as the project
name.
.. _`Keystone install guide`: https://docs.openstack.org/keystone/latest/install/keystone-users-rdo.html
.. note:: .. note::

12
doc/source/operating_guides/scale_deployment.rst
View File

@ -31,12 +31,12 @@ Assumptions
This guide, using a devstack installation of OpenStack, assumes that: This guide, using a devstack installation of OpenStack, assumes that:
1. You have configured devstack from `Single Machine Installation Guide 1. You have configured devstack from :devstack-doc:`Single Machine
<https://docs.openstack.org/devstack/latest/guides/single-machine.html>`_; Installation Guide <guides/single-machine.html>`;
2. You have set up heat on devstack, as defined at :doc:`heat and DevStack 2. You have set up heat on devstack, as defined at :doc:`heat and DevStack
<../getting_started/on_devstack>`; <../getting_started/on_devstack>`;
3. You have installed HAProxy_ on the devstack 3. You have installed HAProxy_ on the devstack
server. server.
Architecture Architecture
============ ============

52
doc/source/template_guide/multi-clouds.rst
View File

@ -13,10 +13,10 @@ multi-clouds features, and what's the environment requirement.
.. note:: If you like to create a stack in multi-region environment, .. note:: If you like to create a stack in multi-region environment,
you don't need this feature at all. all you need to do is provide you don't need this feature at all. all you need to do is provide
`region_name` under `context` property for `OS::Heat::Stack`_. `region_name` under `context` property for :ref:`OS::Heat::Stack`.
If you like to see information on how to provide SSL support for If you like to see information on how to provide SSL support for
your multi-region environment, you can jump to `Use CA your multi-region environment, you can jump to `Use CA
cert(Optional)`_ . cert (Optional)`_ .
Requirements Requirements
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -58,17 +58,23 @@ Gathering credential information
Before we start generating secret, let's talk about what credential format we Before we start generating secret, let's talk about what credential format we
need. credential is a JSON format string contains two keys ``auth_type``, and need. credential is a JSON format string contains two keys ``auth_type``, and
``auth``. ``auth_type``, and ``auth`` following auth plugin loader rules from ``auth``. ``auth_type``, and ``auth`` following auth plugin loader rules from
Keystone. You can find `plugin options`_ and `authentication plugins`_ in Keystone. You can find :keystoneauth-doc:`plugin options
keystoneauth documents. <plugin-options.html>` and :keystoneauth-doc:`authentication plugins
<authentication-plugins.html#loading-plugins-by-name>` in keystoneauth
documents.
* **auth_type** - ``auth_type`` is a string for plugin name. Allows value like * **auth_type** - ``auth_type`` is a string for plugin name. Allows value like
`v3applicationcredential`, `password`, `v3oidcclientcredentials`, etc. You `v3applicationcredential`, `password`, `v3oidcclientcredentials`, etc. You
need to provide `available plugins`_. need to provide `available plugins
<plugin-options.html#available-plugins>`.
* **auth** - auth is a dictionary contains all parameters for plugins to * **auth** - auth is a dictionary contains all parameters for plugins to
perform authentication. You can find all valid parameter references from perform authentication. You can find all valid parameter references from
`available plugins`_ or get to all class path from `plugin names`_ for more :keystoneauth-doc:`available plugins
detail allowed value or trace plugin class from there. <plugin-options.html#available-plugins>` or get to all class path from
:keystoneauth-doc:`plugin names
<authentication-plugins.html#loading-plugins-by-name>` for more detail
allowed value or trace plugin class from there.
As you can tell, all allowed authentication plugins for credentials follows As you can tell, all allowed authentication plugins for credentials follows
plugins keystoneauth rules. So once new change in keystoneauth, it will also plugins keystoneauth rules. So once new change in keystoneauth, it will also
@ -81,15 +87,18 @@ Validate your credential
------------------------ ------------------------
Now you have all your credential information ready, try to validate first if Now you have all your credential information ready, try to validate first if
you can. You can either directly test them `via config`_, `via CLI`_, or you can. You can either directly test them :keystoneauth-doc:`via config
`via keystoneauth sessions`_. <plugin-options.html#using-plugins-via-config-file>`,
:keystoneauth-doc:`via CLI <plugin-options.html#using-plugins-via-cli>`,
or :keystoneauth-doc:`via keystoneauth sessions <using-sessions.html>`.
build credential secret build credential secret
----------------------- -----------------------
Once you're sure it's valid, we can start building the secret out. Once you're sure it's valid, we can start building the secret out. To build a
To build a secret you just have to follow standard Barbican CLI_ or API to secret you just have to follow the standard
store your secret. :python-barbicanclient-doc:`Barbican CLI <cli/cli_usage.html#secret-create>` or
API to store your secret.
The local site will read this secret to perform stack actions in remote site. The local site will read this secret to perform stack actions in remote site.
Let's give a quick example here: Let's give a quick example here:
@ -111,9 +120,8 @@ Create remote stacks
Now, you have a secret id generated for your Barbican secret. Use that id as Now, you have a secret id generated for your Barbican secret. Use that id as
input for template. input for template.
To create a remote stack, you can simply use `OS::Heat::Stack`_ resource, as To create a remote stack, you can simply use an :ref:`OS::Heat::Stack` resource
child stack in your template (we also referring this structure as in your template.
`nested stack`).
In resource properties, provide `credential_secret_id` (Barbican secret ID In resource properties, provide `credential_secret_id` (Barbican secret ID
from the secret we just builded for credential) under `context` property. from the secret we just builded for credential) under `context` property.
@ -146,8 +154,8 @@ won't affect resources/stacks in remote site. So do such actions with super
care. care.
Use CA cert(Optional) Use CA cert (Optional)
--------------------- ----------------------
For production clouds, it's very important to have SSL support. Here we For production clouds, it's very important to have SSL support. Here we
provide CA cert method for your SSL access. If you wish to use that, use provide CA cert method for your SSL access. If you wish to use that, use
@ -174,13 +182,3 @@ Here is an example for you:
template: { get_file: "remote-app.yaml" } template: { get_file: "remote-app.yaml" }
.. note:: If insecure flag is on, ca_cert will be ignored. .. note:: If insecure flag is on, ca_cert will be ignored.
.. _`plugin options`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html
.. _`authentication plugins`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name
.. _`plugin names`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name
.. _`available plugins`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#available-plugins
.. _`via keystoneauth sessions`: https://docs.openstack.org/keystoneauth/latest/using-sessions.html
.. _`via config`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-config-file
.. _`via CLI`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-cli
.. _CLI: https://docs.openstack.org/python-barbicanclient/latest/cli/cli_usage.html#secret-create
.. _`OS::Heat::Stack`: https://docs.openstack.org/heat/rocky/template_guide/openstack.html#OS::Heat::Stack

12
doc/source/template_guide/software_deployment.rst
View File

@ -39,18 +39,21 @@ you might want to do this, including:
A number of tools are available for building custom images, including: A number of tools are available for building custom images, including:
* diskimage-builder_ image building tools for OpenStack * :diskimage-builder-doc:`diskimage-builder <>` image building tools for OpenStack
* imagefactory_ builds images for a variety of operating system/cloud * imagefactory_ builds images for a variety of operating system/cloud
combinations combinations
Examples in this guide which require custom images will use diskimage-builder_. Examples in this guide that require custom images will use
:diskimage-builder-doc:`diskimage-builder <>`.
User-data boot scripts and cloud-init User-data boot scripts and cloud-init
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When booting a server it is possible to specify the contents of the user-data When booting a server it is possible to specify the contents of the user-data
to be passed to that server. This user-data is made available either from to be passed to that server. This user-data is made available either from
configured config-drive or from the `Metadata service`_. configured config-drive or from the :nova-doc:`Metadata service
<admin/networking-nova.html#metadata-service>`
How this user-data is consumed depends on the image being booted, but the most How this user-data is consumed depends on the image being booted, but the most
commonly used tool for default cloud images is cloud-init_. commonly used tool for default cloud images is cloud-init_.
@ -779,11 +782,8 @@ contents of the file ``example-puppet-manifest.pp``, containing:
} }
.. _`AWS::CloudFormation::Init`: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html .. _`AWS::CloudFormation::Init`: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html
.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/
.. _imagefactory: https://imgfac.org/ .. _imagefactory: https://imgfac.org/
.. _`Metadata service`: https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service
.. _cloud-init: https://cloudinit.readthedocs.io/ .. _cloud-init: https://cloudinit.readthedocs.io/
.. _curl: https://curl.haxx.se/ .. _curl: https://curl.haxx.se/
.. _`Orchestration API`: https://docs.openstack.org/api-ref/orchestration/v1/ .. _`Orchestration API`: https://docs.openstack.org/api-ref/orchestration/v1/