openstack
/
heat
Code Issues Proposed changes

Docs: use extrefs to link to other projects' docs 

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
(cherry picked from commit dd70d9244d)
This commit is contained in:
Zane Bitter 2020-01-22 10:32:43 -05:00
parent a62584005d
commit cf00a64dfc
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
roles delegated. In addition, the trustee has effective impersonation
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:
@ -146,5 +147,3 @@ defined, then all the trustor roles are delegated to trustee.
The trustor delegated roles must be pre-configured in the
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.
For more information about using the Orchestration service through the
command line, see the `Heat Command-Line Interface reference
<https://docs.openstack.org/python-heatclient/latest/#openstackclient-command-line>`_.
command line, see the :python-heatclient-doc:`Heat Command-Line Interface
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
the API surface they can access is limited through
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
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
STACK RESOURCE``), and any agents in the instance
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
# 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.
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
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 list
You can explore other heat commands by referring to the `Heat command reference
<https://docs.openstack.org/python-heatclient/latest/cli/>`_ for the
`OpenStack Command-Line Interface
<https://docs.openstack.org/python-openstackclient/>`_; then read the
:ref:`template-guide` and start authoring your own templates.
You can explore other heat commands by referring to the
:python-heatclient-doc:`Heat command reference <cli/>` for the
:python-openstackclient-doc:`OpenStack Command-Line Interface <>`; then read
the :ref:`template-guide` and start authoring your own templates.

12
doc/source/glossary.rst
View File

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

3
doc/source/index.rst
View File

@ -80,10 +80,9 @@ Using the Heat Service
----------------------
- `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/
.. _`Python and CLI client`: https://docs.openstack.org/python-heatclient/latest
Developing Heat
===============

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

@ -74,14 +74,13 @@ requires additional information in the Identity service.
.. note::
If installing OpenStack manually following the `Keystone install
guide`_, the name of the services project is ``service`` as given
above. However, traditional methods of installing RDO (such as
PackStack and TripleO) use ``services`` as the name of the service
project. If you installed RDO 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
If installing OpenStack manually following the :keystone-doc:`Keystone
install guide <install/keystone-users-rdo.html>`, the name of the
services project is ``service`` as given above. However, traditional
methods of installing RDO (such as PackStack and TripleO) use
``services`` as the name of the service project. If you installed RDO
using a Puppet-based method, substitute ``services`` as the project
name.
.. 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:
1. You have configured devstack from `Single Machine Installation Guide
<https://docs.openstack.org/devstack/latest/guides/single-machine.html>`_;
2. You have set up heat on devstack, as defined at :doc:`heat and DevStack
<../getting_started/on_devstack>`;
3. You have installed HAProxy_ on the devstack
server.
1. You have configured devstack from :devstack-doc:`Single Machine
Installation Guide <guides/single-machine.html>`;
2. You have set up heat on devstack, as defined at :doc:`heat and DevStack
<../getting_started/on_devstack>`;
3. You have installed HAProxy_ on the devstack
server.
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,
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
your multi-region environment, you can jump to `Use CA
cert(Optional)`_ .
cert (Optional)`_ .
Requirements
~~~~~~~~~~~~
@ -58,17 +58,23 @@ Gathering credential information
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
``auth``. ``auth_type``, and ``auth`` following auth plugin loader rules from
Keystone. You can find `plugin options`_ and `authentication plugins`_ in
keystoneauth documents.
Keystone. You can find :keystoneauth-doc:`plugin options
<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
`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
perform authentication. You can find all valid parameter references from
`available plugins`_ or get to all class path from `plugin names`_ for more
detail allowed value or trace plugin class from there.
:keystoneauth-doc:`available plugins
<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
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
you can. You can either directly test them `via config`_, `via CLI`_, or
`via keystoneauth sessions`_.
you can. You can either directly test them :keystoneauth-doc:`via config
<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
-----------------------
Once you're sure it's valid, we can start building the secret out.
To build a secret you just have to follow standard Barbican CLI_ or API to
store your secret.
Once you're sure it's valid, we can start building the secret out. To build a
secret you just have to follow the standard
: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.
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
input for template.
To create a remote stack, you can simply use `OS::Heat::Stack`_ resource, as
child stack in your template (we also referring this structure as
`nested stack`).
To create a remote stack, you can simply use an :ref:`OS::Heat::Stack` resource
in your template.
In resource properties, provide `credential_secret_id` (Barbican secret ID
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.
Use CA cert(Optional)
---------------------
Use CA cert (Optional)
----------------------
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
@ -174,13 +182,3 @@ Here is an example for you:
template: { get_file: "remote-app.yaml" }
.. 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:
* 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
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
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
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
.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/
.. _imagefactory: https://imgfac.org/
.. _`Metadata service`: https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service
.. _cloud-init: https://cloudinit.readthedocs.io/
.. _curl: https://curl.haxx.se/
.. _`Orchestration API`: https://docs.openstack.org/api-ref/orchestration/v1/