3050f3c5c7
This patch fixes some typos in the current documentation. Change-Id: I35155244d581ddfc316064e35e851f55b6d853f1
267 lines
9.2 KiB
ReStructuredText
267 lines
9.2 KiB
ReStructuredText
Node customization and Third-Party Integration
|
|
==============================================
|
|
|
|
It is possible to enable additional configuration during one of the
|
|
following deployment phases:
|
|
|
|
* firstboot - run once config (performed on each node by cloud-init)
|
|
* per-node - run after the node is initially created but before services are deployed and configured (e.g by puppet)
|
|
* post-deploy - run after the services have been deployed and configured (e.g by puppet)
|
|
|
|
.. note::
|
|
|
|
This documentation assumes some knowledge of heat HOT_ template
|
|
syntax, and makes use of heat environment_ files. See the upstream
|
|
heat documentation_ for further information.
|
|
|
|
.. _HOT: http://docs.openstack.org/developer/heat/template_guide/hot_guide.html
|
|
.. _environment: http://docs.openstack.org/developer/heat/template_guide/environment.html
|
|
.. _documentation: http://docs.openstack.org/developer/heat/template_guide/index.html
|
|
|
|
Firstboot extra configuration
|
|
-----------------------------
|
|
|
|
Firstboot configuration is optional, and is performed on *all* nodes on initial
|
|
deployment.
|
|
|
|
Any configuration possible via cloud-init may be performed at this point,
|
|
either by applying cloud-config yaml or running arbitrary additional
|
|
scripts.
|
|
|
|
The heat templates used for deployment provide the `OS::TripleO::NodeUserData`
|
|
resource as the interface to enable this configuration. A basic example of its
|
|
usage is provided below, followed by some notes related to real world
|
|
usage.
|
|
|
|
The script snippet below shows how to create a simple example containing two
|
|
scripts, combined via the MultipartMime_ resource::
|
|
|
|
mkdir firstboot
|
|
cat > firstboot/one_two.yaml << EOF
|
|
heat_template_version: 2014-10-16
|
|
|
|
resources:
|
|
userdata:
|
|
type: OS::Heat::MultipartMime
|
|
properties:
|
|
parts:
|
|
- config: {get_resource: one_config}
|
|
- config: {get_resource: two_config}
|
|
|
|
one_config:
|
|
type: OS::Heat::SoftwareConfig
|
|
properties:
|
|
config: |
|
|
#!/bin/bash
|
|
echo "one" > /tmp/one
|
|
|
|
two_config:
|
|
type: OS::Heat::SoftwareConfig
|
|
properties:
|
|
config: |
|
|
#!/bin/bash
|
|
echo "two" > /tmp/two
|
|
|
|
outputs:
|
|
OS::stack_id:
|
|
value: {get_resource: userdata}
|
|
EOF
|
|
|
|
.. _MultipartMime: http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Heat::MultipartMime
|
|
|
|
.. note::
|
|
|
|
The stack must expose an `OS::stack_id` output which references an
|
|
OS::Heat::MultipartMime resource.
|
|
|
|
This template is then mapped to the `OS::TripleO::NodeUserData` resource type
|
|
via a heat environment file::
|
|
|
|
cat > userdata_env.yaml << EOF
|
|
resource_registry:
|
|
OS::TripleO::NodeUserData: firstboot/one_two.yaml
|
|
EOF
|
|
|
|
You may then deploy your overcloud referencing the additional environment file::
|
|
|
|
openstack overcloud deploy --templates -e userdata_env.yaml
|
|
|
|
.. note::
|
|
|
|
The userdata is applied to *all* nodes in the deployment. If you need role
|
|
specific logic, the userdata scripts can contain conditionals which use
|
|
e.g the node hostname to determine the role.
|
|
|
|
.. note::
|
|
|
|
OS::TripleO::NodeUserData is only applied on initial node deployment,
|
|
not on any subsequent stack update, because cloud-init only processes the
|
|
nova user-data once, on first boot.
|
|
|
|
For a more complete example, which creates an additional user and configures
|
|
SSH keys by accessing the nova metadata server, see
|
|
`/usr/share/openstack-tripleo-heat-templates/firstboot/userdata_example.yaml`
|
|
on the undercloud node or the tripleo-heat-templates_ repo.
|
|
|
|
.. _tripleo-heat-templates: https://git.openstack.org/openstack/tripleo-heat-templates
|
|
|
|
Per-node extra configuration
|
|
----------------------------
|
|
|
|
This configuration happens after after any "firstboot" configuration is applied,
|
|
but before any Post-Deploy configuration takes place.
|
|
|
|
Typically these interfaces are suitable for preparing each node for service
|
|
deployment, such as registering nodes with a content repository, or creating
|
|
additional data to be consumed by the post-deploy phase. They may also be suitable
|
|
integration points for additional third-party services, drivers or plugins.
|
|
|
|
|
|
.. note::
|
|
If you only need to provide some additional data to the existing service
|
|
configuration, see :ref:`node_config` as this may provide a simpler solution.
|
|
|
|
.. note::
|
|
The per-node interface only enable *individual* nodes to be configured,
|
|
if cluster-wide configuration is required, the Post-Deploy interfaces should be
|
|
used instead.
|
|
|
|
The following interfaces are available:
|
|
|
|
* `OS::TripleO::ControllerExtraConfigPre`: Controller node additional configuration
|
|
* `OS::TripleO::ComputeExtraConfigPre`: Compute node additional configuration
|
|
* `OS::TripleO::CephStorageExtraConfigPre` : CephStorage node additional configuration
|
|
* `OS::TripleO::NodeExtraConfig`: additional configuration applied to all nodes (all roles).
|
|
|
|
Below is an example of a per-node configuration template that shows additional node configuration
|
|
via standard heat SoftwareConfig_ resources::
|
|
|
|
mkdir -p extraconfig/per-node
|
|
cat > extraconfig/per-node/example.yaml << EOF
|
|
|
|
heat_template_version: 2014-10-16
|
|
|
|
parameters:
|
|
server:
|
|
description: ID of the controller node to apply this config to
|
|
type: string
|
|
|
|
resources:
|
|
NodeConfig:
|
|
type: OS::Heat::SoftwareConfig
|
|
properties:
|
|
group: script
|
|
config: |
|
|
#!/bin/sh
|
|
echo "Node configured" > /root/per-node
|
|
|
|
NodeDeployment:
|
|
type: OS::Heat::SoftwareDeployment
|
|
properties:
|
|
config: {get_resource: NodeConfig}
|
|
server: {get_param: server}
|
|
outputs:
|
|
deploy_stdout:
|
|
description: Deployment reference, used to trigger post-deploy on changes
|
|
value: {get_attr: [NodeDeployment, deploy_stdout]}
|
|
|
|
EOF
|
|
|
|
The "server" parameter must be specified in all per-node ExtraConfig templates,
|
|
this is the server to apply the configuration to, and is provided by the parent
|
|
template. Optionally additional implementation specific parameters may also be
|
|
provided by parameter_defaults, see below for more details.
|
|
|
|
Any resources may be defined in the template, but the outputs must define a "deploy_stdout"
|
|
value, which is an identifier used to detect if the configuration applied has changed,
|
|
hence when any post-deploy actions (such as re-applying puppet manifests on update)
|
|
may need to be performed.
|
|
|
|
For a more complete example showing how to apply a personalized map of per-node configuration
|
|
to each node, see `/usr/share/openstack-tripleo-heat-templates/puppet/extraconfig/pre_deploy/per_node.yaml`
|
|
or the tripleo-heat-templates_ repo.
|
|
|
|
.. _SoftwareConfig: http://docs.openstack.org/developer/heat/template_guide/software_deployment.html
|
|
|
|
|
|
Post-Deploy extra configuration
|
|
-------------------------------
|
|
|
|
Post-deploy additional configuration is possible via the
|
|
`OS::TripleO::NodeExtraConfigPost` interface, which is applied after any
|
|
per-node configuration has completed.
|
|
|
|
.. note::
|
|
|
|
The `OS::TripleO::NodeExtraConfigPost` applies configuration to *all* nodes,
|
|
there is currently no per-role NodeExtraConfigPost interface.
|
|
|
|
Below is an example of a post-deployment configuration template::
|
|
|
|
mkdir -p extraconfig/post-deploy/
|
|
cat > extraconfig/post-deploy/example.yaml << EOF
|
|
heat_template_version: 2014-10-16
|
|
|
|
parameters:
|
|
servers:
|
|
type: json
|
|
|
|
# Optional implementation specific parameters
|
|
some_extraparam:
|
|
type: string
|
|
|
|
resources:
|
|
|
|
ExtraConfig:
|
|
type: OS::Heat::SoftwareConfig
|
|
properties:
|
|
group: script
|
|
config:
|
|
str_replace:
|
|
template: |
|
|
#!/bin/sh
|
|
echo "extra _APARAM_" > /root/extra
|
|
parameters:
|
|
_APARAM_: {get_param: some_extraparam}
|
|
|
|
ExtraDeployments:
|
|
type: OS::Heat::SoftwareDeployments
|
|
properties:
|
|
servers: {get_param: servers}
|
|
config: {get_resource: ExtraConfig}
|
|
actions: ['CREATE'] # Only do this on CREATE
|
|
EOF
|
|
|
|
The "servers" parameter must be specified in all NodeExtraConfigPost
|
|
templates, this is the server list to apply the configuration to,
|
|
and is provided by the parent template.
|
|
|
|
Optionally, you may define additional parameters which are consumed by the
|
|
implementation. These may then be provided via parameter_defaults in the
|
|
environment which enables the configuration.
|
|
|
|
.. note::
|
|
|
|
If the parameter_defaults approach is used, care must be used to avoid
|
|
unintended reuse of parameter names between multiple templates, because
|
|
parameter_defaults is applied globally.
|
|
|
|
The "actions" property of the `OS::Heat::SoftwareDeployments` resource may be
|
|
used to specify when the configuration should be applied, e.g only on CREATE,
|
|
only on DELETE etc. If this is omitted, the heat default is to apply the
|
|
config on CREATE and UPDATE, e.g on initial deployment and every subsequent
|
|
update.
|
|
|
|
The extra config may be enabled via an environment file::
|
|
|
|
cat > post_config_env.yaml << EOF
|
|
resource_registry:
|
|
OS::TripleO::NodeExtraConfigPost: extraconfig/post-deploy/example.yaml
|
|
parameter_defaults:
|
|
some_extraparam: avalue123
|
|
EOF
|
|
|
|
You may then deploy your overcloud referencing the additional environment file::
|
|
|
|
openstack overcloud deploy --templates -e post_config_env.yaml
|