Browse Source

Merge "Remove hotref links in the documentation"

changes/55/197655/3
Jenkins 7 years ago committed by Gerrit Code Review
parent
commit
cf8f36c44b
  1. 20
      doc/source/ext/resources.py
  2. 41
      doc/source/template_guide/basic_resources.rst
  3. 2
      doc/source/template_guide/composition.rst
  4. 42
      doc/source/template_guide/software_deployment.rst

20
doc/source/ext/resources.py

@ -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)

41
doc/source/template_guide/basic_resources.rst

@ -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.

2
doc/source/template_guide/composition.rst

@ -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.

42
doc/source/template_guide/software_deployment.rst

@ -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…
Cancel
Save