diff --git a/doc/source/ext/resources.py b/doc/source/ext/resources.py index f79d0ee27b..607caec7fb 100644 --- a/doc/source/ext/resources.py +++ b/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) diff --git a/doc/source/template_guide/basic_resources.rst b/doc/source/template_guide/basic_resources.rst index 1812241f89..cc1d706cfc 100644 --- a/doc/source/template_guide/basic_resources.rst +++ b/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 `_. 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. diff --git a/doc/source/template_guide/composition.rst b/doc/source/template_guide/composition.rst index 6c79700530..98e9808884 100644 --- a/doc/source/template_guide/composition.rst +++ b/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. diff --git a/doc/source/template_guide/software_deployment.rst b/doc/source/template_guide/software_deployment.rst index a7f430f771..cf0f5b724a 100644 --- a/doc/source/template_guide/software_deployment.rst +++ b/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