Remove hotref links in the documentation
Now that we moved the template_guide in-tree, the hotref sphinx directive doesn't work anymore and isn't needed. This replaces it with ref directives and a missing-reference handler managing resources. Change-Id: I5cba4b96894878a57d577c74dd6ade7fd252b164changes/85/198685/2
Thomas Herve
parent
7dcb065b55
commit
5d2e6ea3f1
|
|
@ -361,6 +361,24 @@ def _load_all_resources():
|
|||
all_resources[name] = [cls]
|
||||
|
||||
|
||||
def link_resource(app, env, node, contnode):
|
||||
reftarget = node.attributes['reftarget']
|
||||
for resource_name in all_resources:
|
||||
if resource_name.lower() == reftarget.lower():
|
||||
resource = all_resources[resource_name]
|
||||
refnode = nodes.reference('', '', internal=True)
|
||||
refnode['reftitle'] = resource_name
|
||||
if resource_name.startswith('AWS'):
|
||||
source = 'template_guide/cfn'
|
||||
else:
|
||||
source = 'template_guide/openstack'
|
||||
uri = app.builder.get_relative_uri(
|
||||
node.attributes['refdoc'], source)
|
||||
refnode['refuri'] = '%s#%s' % (uri, resource_name)
|
||||
refnode.append(contnode)
|
||||
return refnode
|
||||
|
||||
|
||||
def setup(app):
|
||||
_load_all_resources()
|
||||
app.add_node(integratedrespages)
|
||||
|
|
@ -374,3 +392,5 @@ def setup(app):
|
|||
app.add_node(contribresourcepages)
|
||||
|
||||
app.add_directive('contribrespages', ContribResourcePages)
|
||||
|
||||
app.connect('missing-reference', link_resource)
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ Manage instances
|
|||
|
||||
Create an instance
|
||||
------------------
|
||||
Use the :hotref:`OS::Nova::Server` resource to create a Compute instance. The
|
||||
Use the :ref:`OS::Nova::Server` resource to create a Compute instance. The
|
||||
``flavor`` property is the only mandatory one, but you need to define a boot
|
||||
source using one of the ``image`` or ``block_device_mapping`` properties.
|
||||
|
||||
|
|
@ -42,19 +42,19 @@ connecting to the ``private`` network:
|
|||
|
||||
Connect an instance to a network
|
||||
--------------------------------
|
||||
Use the ``networks`` property of an :hotref:`OS::Nova::Server` resource to
|
||||
Use the ``networks`` property of an :ref:`OS::Nova::Server` resource to
|
||||
define which networks an instance should connect to. Define each network as a
|
||||
YAML map, containing one of the following keys:
|
||||
|
||||
``port``
|
||||
The ID of an existing Networking port. You usually create this port in the
|
||||
same template using an :hotref:`OS::Neutron::Port` resource. You will be
|
||||
same template using an :ref:`OS::Neutron::Port` resource. You will be
|
||||
able to associate a floating IP to this port, and the port to your Compute
|
||||
instance.
|
||||
|
||||
``network``
|
||||
The name or ID of an existing network. You don't need to create an
|
||||
:hotref:`OS::Neutron::Port` resource if you use this property, but you will
|
||||
:ref:`OS::Neutron::Port` resource if you use this property, but you will
|
||||
not be able to associate a floating IP with the instance interface in the
|
||||
template.
|
||||
|
||||
|
|
@ -91,10 +91,10 @@ properties:
|
|||
|
||||
Create and associate security groups to an instance
|
||||
---------------------------------------------------
|
||||
Use the :hotref:`OS::Neutron::SecurityGroup` resource to create security
|
||||
Use the :ref:`OS::Neutron::SecurityGroup` resource to create security
|
||||
groups.
|
||||
|
||||
Define the ``security_groups`` property of the :hotref:`OS::Neutron::Port`
|
||||
Define the ``security_groups`` property of the :ref:`OS::Neutron::Port`
|
||||
resource to associate security groups to a port, then associate the port to an
|
||||
instance.
|
||||
|
||||
|
|
@ -145,8 +145,8 @@ instances.
|
|||
|
||||
OS::Nova resources
|
||||
++++++++++++++++++
|
||||
Use the :hotref:`OS::Nova::FloatingIP` resource to create a floating IP, and
|
||||
the :hotref:`OS::Nova::FloatingIPAssociation` resource to associate the
|
||||
Use the :ref:`OS::Nova::FloatingIP` resource to create a floating IP, and
|
||||
the :ref:`OS::Nova::FloatingIPAssociation` resource to associate the
|
||||
floating IP to an instance.
|
||||
|
||||
The following example creates an instance and a floating IP, and associate the
|
||||
|
|
@ -181,8 +181,8 @@ OS::Neutron resources
|
|||
The Networking service (neutron) must be enabled on your OpenStack
|
||||
deployment to use these resources.
|
||||
|
||||
Use the :hotref:`OS::Neutron::FloatingIP` resource to create a floating IP, and
|
||||
the :hotref:`OS::Neutron::FloatingIPAssociation` resource to associate the
|
||||
Use the :ref:`OS::Neutron::FloatingIP` resource to create a floating IP, and
|
||||
the :ref:`OS::Neutron::FloatingIPAssociation` resource to associate the
|
||||
floating IP to a port:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -242,7 +242,7 @@ with stack updates.
|
|||
|
||||
Enable remote access to an instance
|
||||
-----------------------------------
|
||||
The ``key_name`` attribute of the :hotref:`OS::Nova::Server` resource defines
|
||||
The ``key_name`` attribute of the :ref:`OS::Nova::Server` resource defines
|
||||
the key pair to use to enable SSH remote access:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -257,11 +257,12 @@ the key pair to use to enable SSH remote access:
|
|||
key_name: my_key
|
||||
|
||||
.. note::
|
||||
For more information about key pairs, see the :doc:`../cli_nova_configure_access_security_for_instances`.
|
||||
For more information about key pairs, see
|
||||
`Configure access and security for instances <http://docs.openstack.org/user-guide/configure_access_and_security_for_instances.html>`_.
|
||||
|
||||
Create a key pair
|
||||
-----------------
|
||||
You can create new key pairs with the :hotref:`OS::Nova::KeyPair` resource. Key
|
||||
You can create new key pairs with the :ref:`OS::Nova::KeyPair` resource. Key
|
||||
pairs can be imported or created during the stack creation.
|
||||
|
||||
If the ``public_key`` property is not specified, the Orchestration module
|
||||
|
|
@ -301,8 +302,8 @@ Create a network and a subnet
|
|||
deployment to create and manage networks and subnets. Networks and subnets
|
||||
cannot be created if your deployment uses legacy networking (nova-network).
|
||||
|
||||
Use the :hotref:`OS::Neutron::Net` resource to create a network, and the
|
||||
:hotref:`OS::Neutron::Subnet` resource to provide a subnet for this network:
|
||||
Use the :ref:`OS::Neutron::Net` resource to create a network, and the
|
||||
:ref:`OS::Neutron::Subnet` resource to provide a subnet for this network:
|
||||
|
||||
.. code-block:: yaml
|
||||
:linenos:
|
||||
|
|
@ -322,7 +323,7 @@ Use the :hotref:`OS::Neutron::Net` resource to create a network, and the
|
|||
|
||||
Create and manage a router
|
||||
--------------------------
|
||||
Use the :hotref:`OS::Neutron::Router` resource to create a router. You can
|
||||
Use the :ref:`OS::Neutron::Router` resource to create a router. You can
|
||||
define its gateway with the ``external_gateway_info`` property:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -335,7 +336,7 @@ define its gateway with the ``external_gateway_info`` property:
|
|||
external_gateway_info: { network: public }
|
||||
|
||||
You can connect subnets to routers with the
|
||||
:hotref:`OS::Neutron::RouterInterface` resource:
|
||||
:ref:`OS::Neutron::RouterInterface` resource:
|
||||
|
||||
.. code-block:: yaml
|
||||
:linenos:
|
||||
|
|
@ -389,7 +390,7 @@ Manage volumes
|
|||
~~~~~~~~~~~~~~
|
||||
Create a volume
|
||||
---------------
|
||||
Use the :hotref:`OS::Cinder::Volume` resource to create a new Block Storage
|
||||
Use the :ref:`OS::Cinder::Volume` resource to create a new Block Storage
|
||||
volume.
|
||||
|
||||
For example:
|
||||
|
|
@ -437,7 +438,7 @@ service uses the size of the backup to define the size of the new volume.
|
|||
|
||||
Attach a volume to an instance
|
||||
------------------------------
|
||||
Use the :hotref:`OS::Cinder::VolumeAttachment` resource to attach a volume to
|
||||
Use the :ref:`OS::Cinder::VolumeAttachment` resource to attach a volume to
|
||||
an instance.
|
||||
|
||||
The following example creates a volume and an instance, and attaches the volume
|
||||
|
|
@ -466,7 +467,7 @@ to the instance:
|
|||
|
||||
Boot an instance from a volume
|
||||
------------------------------
|
||||
Use the ``block_device_mapping`` property of the :hotref:`OS::Nova::Server`
|
||||
Use the ``block_device_mapping`` property of the :ref:`OS::Nova::Server`
|
||||
resource to define a volume used to boot the instance. This property is a list
|
||||
of volumes to attach to the instance before its boot.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ together using template resources. This is a mechanism to define a resource
|
|||
using a template, thus composing one logical stack with multiple templates.
|
||||
|
||||
Template resources provide a feature similar to the
|
||||
:hotref:`AWS::CloudFormation::Stack` resource, but also provide a way to:
|
||||
:ref:`AWS::CloudFormation::Stack` resource, but also provide a way to:
|
||||
|
||||
* Define new resource types and build your own resource library.
|
||||
* Override the default behaviour of existing resource types.
|
||||
|
|
|
|||
|
|
@ -137,7 +137,7 @@ script in a separate file:
|
|||
|
||||
Choosing the user_data_format
|
||||
-----------------------------
|
||||
The :hotref:`OS::Nova::Server` ``user_data_format`` property determines how the
|
||||
The :ref:`OS::Nova::Server` ``user_data_format`` property determines how the
|
||||
``user_data`` should be formatted for the server. For the default value
|
||||
``HEAT_CFNTOOLS``, the ``user_data`` is bundled as part of the heat-cfntools
|
||||
cloud-init boot configuration data. While ``HEAT_CFNTOOLS`` is the default
|
||||
|
|
@ -181,10 +181,10 @@ Often it is necessary to pause further creation of stack resources until the
|
|||
boot configuration script has notified that it has reached a certain state.
|
||||
This is usually either to notify that a service is now active, or to pass out
|
||||
some generated data which is needed by another resource. The resources
|
||||
:hotref:`OS::Heat::WaitCondition` and :hotref:`OS::Heat::SwiftSignal` both perform
|
||||
:ref:`OS::Heat::WaitCondition` and :ref:`OS::Heat::SwiftSignal` both perform
|
||||
this function using different techniques and tradeoffs.
|
||||
|
||||
:hotref:`OS::Heat::WaitCondition` is implemented as a call to the
|
||||
:ref:`OS::Heat::WaitCondition` is implemented as a call to the
|
||||
`Orchestration API`_ resource signal. The token is created using credentials
|
||||
for a user account which is scoped only to the wait condition handle
|
||||
resource. This user is created when the handle is created, and is associated
|
||||
|
|
@ -289,7 +289,7 @@ which builds a curl command with a valid token:
|
|||
|
||||
..
|
||||
|
||||
:hotref:`OS::Heat::SwiftSignal` is implemented by creating an Object Storage
|
||||
:ref:`OS::Heat::SwiftSignal` is implemented by creating an Object Storage
|
||||
API temporary URL which is populated with signal data with an HTTP PUT. The
|
||||
orchestration service will poll this object until the signal data is available.
|
||||
Object versioning is used to store multiple signals.
|
||||
|
|
@ -317,13 +317,13 @@ swift signal resources:
|
|||
type: OS::Heat::SwiftSignalHandle
|
||||
# ...
|
||||
|
||||
The decision to use :hotref:`OS::Heat::WaitCondition` or
|
||||
:hotref:`OS::Heat::SwiftSignal` will depend on a few factors:
|
||||
The decision to use :ref:`OS::Heat::WaitCondition` or
|
||||
:ref:`OS::Heat::SwiftSignal` will depend on a few factors:
|
||||
|
||||
* :hotref:`OS::Heat::SwiftSignal` depends on the availability of an Object
|
||||
* :ref:`OS::Heat::SwiftSignal` depends on the availability of an Object
|
||||
Storage API
|
||||
|
||||
* :hotref:`OS::Heat::WaitCondition` depends on whether the orchestration
|
||||
* :ref:`OS::Heat::WaitCondition` depends on whether the orchestration
|
||||
service has been configured with a dedicated stack domain (which may depend
|
||||
on the availability of an Identity V3 API).
|
||||
|
||||
|
|
@ -341,7 +341,7 @@ existing software-config resource, so a stack-update which changes any
|
|||
existing software-config resource will result in API calls to create a new
|
||||
config and delete the old one.
|
||||
|
||||
The resource :hotref:`OS::Heat::SoftwareConfig` is used for storing configs
|
||||
The resource :ref:`OS::Heat::SoftwareConfig` is used for storing configs
|
||||
represented by text scripts, for example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -364,7 +364,7 @@ represented by text scripts, for example:
|
|||
user_data_format: RAW
|
||||
user_data: {get_resource: boot_script}
|
||||
|
||||
The resource :hotref:`OS::Heat::CloudConfig` allows Cloud-init_ cloud-config to
|
||||
The resource :ref:`OS::Heat::CloudConfig` allows Cloud-init_ cloud-config to
|
||||
be represented as template YAML rather than a block string. This allows
|
||||
intrinsic functions to be included when building the cloud-config. This also
|
||||
ensures that the cloud-config is valid YAML, although no further checks for
|
||||
|
|
@ -394,8 +394,8 @@ valid cloud-config are done.
|
|||
user_data_format: RAW
|
||||
user_data: {get_resource: boot_config}
|
||||
|
||||
The resource :hotref:`OS::Heat::MultipartMime` allows multiple
|
||||
:hotref:`OS::Heat::SoftwareConfig` and :hotref:`OS::Heat::CloudConfig`
|
||||
The resource :ref:`OS::Heat::MultipartMime` allows multiple
|
||||
:ref:`OS::Heat::SoftwareConfig` and :ref:`OS::Heat::CloudConfig`
|
||||
resources to be combined into a single Cloud-init_ multi-part message:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -448,18 +448,18 @@ Software deployment resources
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
There are many situations where it is not desirable to replace the server
|
||||
whenever there is a configuration change. The
|
||||
:hotref:`OS::Heat::SoftwareDeployment` resource allows any number of software
|
||||
:ref:`OS::Heat::SoftwareDeployment` resource allows any number of software
|
||||
configurations to be added or removed from a server throughout its life-cycle.
|
||||
|
||||
Building custom image for software deployments
|
||||
----------------------------------------------
|
||||
:hotref:`OS::Heat::SoftwareConfig` resources are used to store software
|
||||
configuration, and a :hotref:`OS::Heat::SoftwareDeployment` resource is used
|
||||
:ref:`OS::Heat::SoftwareConfig` resources are used to store software
|
||||
configuration, and a :ref:`OS::Heat::SoftwareDeployment` resource is used
|
||||
to associate a config resource with one server. The ``group`` attribute on
|
||||
:hotref:`OS::Heat::SoftwareConfig` specifies what tool will consume the
|
||||
:ref:`OS::Heat::SoftwareConfig` specifies what tool will consume the
|
||||
config content.
|
||||
|
||||
:hotref:`OS::Heat::SoftwareConfig` has the ability to define a schema of
|
||||
:ref:`OS::Heat::SoftwareConfig` has the ability to define a schema of
|
||||
``inputs`` and which the configuration script supports. Inputs are mapped to
|
||||
whatever concept the configuration tool has for assigning
|
||||
variables/parameters.
|
||||
|
|
@ -468,7 +468,7 @@ Likewise, ``outputs`` are mapped to the tool's capability to export structured
|
|||
data after configuration execution. For tools which do not support this,
|
||||
outputs can always be written to a known file path for the hook to read.
|
||||
|
||||
The :hotref:`OS::Heat::SoftwareDeployment` resource allows values to be
|
||||
The :ref:`OS::Heat::SoftwareDeployment` resource allows values to be
|
||||
assigned to the config inputs, and the resource remains in an ``IN_PROGRESS``
|
||||
state until the server signals to heat what (if any) output values were
|
||||
generated by the config script.
|
||||
|
|
@ -686,15 +686,15 @@ example:
|
|||
|
||||
There are a number of things to note about this template example:
|
||||
|
||||
* :hotref:`OS::Heat::StructuredConfig` is like
|
||||
:hotref:`OS::Heat::SoftwareConfig` except that the ``config`` property
|
||||
* :ref:`OS::Heat::StructuredConfig` is like
|
||||
:ref:`OS::Heat::SoftwareConfig` except that the ``config`` property
|
||||
contains structured YAML instead of text script. This is useful for a
|
||||
number of other configuration tools including ansible, salt and
|
||||
os-apply-config.
|
||||
|
||||
* ``cfn-init`` has no concept of inputs, so ``{get_input: bar}`` acts as a
|
||||
placeholder which gets replaced with the
|
||||
:hotref:`OS::Heat::StructuredDeployment` ``input_values`` value when the
|
||||
:ref:`OS::Heat::StructuredDeployment` ``input_values`` value when the
|
||||
deployment resource is created.
|
||||
|
||||
* ``cfn-init`` has no concept of outputs, so specifying
|
||||
|
|
|
|||
Loading…
Reference in New Issue