From 22f1952bfe7706b1c28057cbe835d479adb4ade8 Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Fri, 31 Oct 2014 11:59:59 +0100 Subject: [PATCH] Include the HOT guide in the user-guide The XML is generated from the hot-guide RST source and imported manually (see doc/user-guide/hot/README.rst to know how). Fix a broken link in the HOT guide to pass the checklinks gate. Change-Id: I839dd7219189c94930f7166ef921bceba0b9b27b --- doc/hot-guide/source/environment.rst | 2 +- doc/user-guide/bk-user-guide.xml | 1 + doc/user-guide/hot/README.rst | 8 + doc/user-guide/hot/index.xml | 17 + .../hot/section_advanced_topics.xml | 33 + .../hot/section_basic_resources.xml | 401 +++++++++ doc/user-guide/hot/section_composition.xml | 108 +++ doc/user-guide/hot/section_environment.xml | 108 +++ doc/user-guide/hot/section_functions.xml | 77 ++ doc/user-guide/hot/section_hello_world.xml | 185 +++++ doc/user-guide/hot/section_hot_spec.xml | 784 ++++++++++++++++++ .../hot/section_software_deployment.xml | 399 +++++++++ 12 files changed, 2122 insertions(+), 1 deletion(-) create mode 100644 doc/user-guide/hot/README.rst create mode 100644 doc/user-guide/hot/index.xml create mode 100644 doc/user-guide/hot/section_advanced_topics.xml create mode 100644 doc/user-guide/hot/section_basic_resources.xml create mode 100644 doc/user-guide/hot/section_composition.xml create mode 100644 doc/user-guide/hot/section_environment.xml create mode 100644 doc/user-guide/hot/section_functions.xml create mode 100644 doc/user-guide/hot/section_hello_world.xml create mode 100644 doc/user-guide/hot/section_hot_spec.xml create mode 100644 doc/user-guide/hot/section_software_deployment.xml diff --git a/doc/hot-guide/source/environment.rst b/doc/hot-guide/source/environment.rst index 16e76e499d..1c99a4335e 100644 --- a/doc/hot-guide/source/environment.rst +++ b/doc/hot-guide/source/environment.rst @@ -85,7 +85,7 @@ environment file. The resource you provide in this manner must have an identifier, and references either other resources IDs or the URL of an existing template file. -The following example maps the new :hotref:`OS::Networking::FloatingIP` +The following example maps the new ``OS::Networking::FloatingIP`` resource to the existing :hotref:`OS::Nova::FloatingIP` resource: .. code-block:: yaml diff --git a/doc/user-guide/bk-user-guide.xml b/doc/user-guide/bk-user-guide.xml index feeccc0ad5..2962e52e08 100644 --- a/doc/user-guide/bk-user-guide.xml +++ b/doc/user-guide/bk-user-guide.xml @@ -145,5 +145,6 @@ + diff --git a/doc/user-guide/hot/README.rst b/doc/user-guide/hot/README.rst new file mode 100644 index 0000000000..8b70bb2b07 --- /dev/null +++ b/doc/user-guide/hot/README.rst @@ -0,0 +1,8 @@ +**The contents of this directory are autogenerated - do NOT modify these files, +your changes will be lost on the next update.** + +To generate the files:: + + cd doc/hot-guide + make xml + openstack-dn2osdbk --toplevel chapter build/xml ../user-guide/hot diff --git a/doc/user-guide/hot/index.xml b/doc/user-guide/hot/index.xml new file mode 100644 index 0000000000..db560d1401 --- /dev/null +++ b/doc/user-guide/hot/index.xml @@ -0,0 +1,17 @@ + + + + + + HOT guide + + + + + + + diff --git a/doc/user-guide/hot/section_advanced_topics.xml b/doc/user-guide/hot/section_advanced_topics.xml new file mode 100644 index 0000000000..ff0d7c9b89 --- /dev/null +++ b/doc/user-guide/hot/section_advanced_topics.xml @@ -0,0 +1,33 @@ + +
+ + Advanced topics +
+ + Networking +
+ Load balancer + TODO +
+
+ Firewall + TODO +
+
+ VPN + TODO +
+
+
+ + Auto scaling +
+ Alarming + TODO +
+
+ Up scaling and down scaling + TODO +
+
+
diff --git a/doc/user-guide/hot/section_basic_resources.xml b/doc/user-guide/hot/section_basic_resources.xml new file mode 100644 index 0000000000..28b20d6c59 --- /dev/null +++ b/doc/user-guide/hot/section_basic_resources.xml @@ -0,0 +1,401 @@ + +
+ + Instances + +
+ + Manage instances +
+ Create an instance + Use the 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. + You also need to define the networks property to indicate to which networks +your instance must connect if multiple networks are available in your tenant. + The following example creates a simple instance, booted from an image, and +connecting to the private network: + resources: + instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + networks: + - network: private +
+
+ Connect an instance to a network + Use the networks property of an 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 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 +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. + + + + The following example demonstrates the use of the port and network +properties: + resources: + instance_port: + type: OS::Neutron::Port + properties: + network: private + fixed_ips: + - subnet_id: "private-subnet" + + instance1: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + networks: + - port: { get_resource: instance_port } + + instance2: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + networks: + - network: private +
+
+ Create and associate security groups to an instance + Use the OS::Neutron::SecurityGroup resource to create security +groups. + Define the security_groups property of the OS::Neutron::Port +resource to associate security groups to a port, then associate the port to an +instance. + The following example creates a security group allowing inbound connections on +ports 80 and 443 (web server) and associates this security group to an instance +port: + resources: + web_secgroup: + type: OS::Neutron::SecurityGroup + properties: + rules: + - protocol: tcp + remote_ip_prefix: 0.0.0.0/0 + port_range_min: 80 + port_range_max: 80 + - protocol: tcp + remote_ip_prefix: 0.0.0.0/0 + port_range_min: 443 + port_range_max: 443 + + instance_port: + type: OS::Neutron::Port + properties: + network: private + security_groups: + - default + - { get_resource: web_secgroup } + fixed_ips: + - subnet_id: private-subnet + + instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + networks: + - port: { get_resource: instance_port } +
+
+ Create and associate a floating IP to an instance + You can use two sets of resources to create and associate floating IPs to +instances. +
+ OS::Nova resources + Use the OS::Nova::FloatingIP resource to create a floating IP, and +the 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 +floating IP to the instance: + resources: + floating_ip: + type: OS::Nova::FloatingIP + properties: + pool: public + + inst1: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + networks: + - network: private + + association: + type: OS::Nova::FloatingIPAssociation + properties: + - floating_ip: { get_resource: floating_ip } + - server_id: { get_resource: instance } +
+
+ OS::Neutron resources + + The Networking service (neutron) must be enabled on your OpenStack +deployment to use these resources. + + Use the OS::Neutron::FloatingIP resource to create a floating IP, and +the OS::Neutron::FloatingIPAssociation resource to associate the +floating IP to a port: + resources: + instance_port: + type: OS::Neutron::Port + properties: + network: private + fixed_ips: + - subnet_id: "private-subnet" + + floating_ip: + type: OS::Neutron::FloatingIP + properties: + floating_network: public + port_id: { get_resource: instance_port } + + association: + type: OS::Neutron::FloatingIPAssociation + properties: + floatingip_id: { get_resource: floating_ip } + port_id: { get_resource: instance_port } +
+
+
+ Enable remote access to an instance + The key_name attribute of the OS::Nova::Server resource defines +the key pair to use to enable SSH remote access: + resources: + my_instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + key_name: my_key + + For more information about key pairs, see the Configure access and +security for instances section of the OpenStack user guide. + +
+
+ Create a key pair + You can create new key pairs with the 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 +creates a new key pair. If the save_private_key property is set to +true, the private_key attribute of the resource holds the private key. + The following example creates a new key pair and uses it as authentication key +for an instance: + resources: + my_key: + type: OS::Nova::KeyPair + properties: + save_private_key: true + + my_instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + key_name: { get_resource: my_key } + +outputs: + private_key: + description: Private key + value: { get_attr: [ my_key, private_key ] } +
+
+
+ + Manage networks +
+ Create a network and a subnet + + The Networking service (neutron) must be enabled on your OpenStack +deployment to create and manage networks and subnets. Networks and subnets +cannot be created if your deployment uses legacy networking (nova-network). + + Use the OS::Neutron::Net resource to create a network, and the +OS::Neutron::Subnet resource to provide a subnet for this network: + resources: + new_net: + type: OS::Neutron::Net + + new_subnet: + type: OS::Neutron::Subnet + properties: + network_id: { get_resource: new_net } + cidr: "10.8.1.0/24" + dns_nameservers: [ "8.8.8.8", "8.8.4.4" ] + ip_version: 4 +
+
+ Create and manage a router + Use the OS::Neutron::Router resource to create a router. You can +define its gateway with the external_gateway_info property: + resources: + router1: + type: OS::Neutron::Router + properties: + external_gateway_info: { network: public } + You can connect subnets to routers with the +OS::Neutron::RouterInterface resource: + resources: + subnet1_interface: + type: OS::Neutron::RouterInterface + properties: + router_id: { get_resource: router1 } + subnet: private-subnet +
+
+ Complete network example + The following example creates a network stack: + + + A network and an associated subnet. + + + A router with an external gateway. + + + An interface to the new subnet for the new router. + + + In this example, the public network is an existing shared network: + resources: + internal_net: + type: OS::Neutron::Net + + internal_subnet: + type: OS::Neutron::Subnet + properties: + network_id: { get_resource: internal_net } + cidr: "10.8.1.0/24" + dns_nameservers: [ "8.8.8.8", "8.8.4.4" ] + ip_version: 4 + + internal_router: + type: OS::Neutron::Router + properties: + external_gateway_info: { network: public } + + internal_interface: + type: OS::Neutron::RouterInterface + properties: + router_id: { get_resource: internal_router } + subnet: { get_resource: internal_subnet } +
+
+
+ + Manage volumes +
+ Create a volume + Use the OS::Cinder::Volume resource to create a new Block Storage +volume. + For example: + resources: + my_new_volume: + type: OS::Cinder::Volume + properties: + size: 10 + The volumes that you create are empty by default. Use the image property to +create a bootable volume from an existing image: + resources: + my_new_bootable_volume: + type: OS::Cinder::Volume + properties: + size: 10 + image: ubuntu-trusty-x86_64 + You can also create new volumes from another volume, a volume snapshot, or a +volume backup. Use the source_volid, snapshot_id or backup_id +properties to create a new volume from an existing source. + For example, to create a new volume from a backup: + resources: + another_volume: + type: OS::Cinder::Volume + properties: + backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868 + In this example the size property is not defined because the Block Storage +service uses the size of the backup to define the size of the new volume. +
+
+ Attach a volume to an instance + Use the OS::Cinder::VolumeAttachment resource to attach a volume to +an instance. + The following example creates a volume and an instance, and attaches the volume +to the instance: + resources: + new_volume: + type: OS::Cinder::Volume + properties: + size: 1 + + new_instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + + volume_attachment: + type: OS::Cinder::VolumeAttachment + properties: + volume_id: { get_resource: new_volume } + instance_uuid: { get_resource: new_instance } +
+
+ Boot an instance from a volume + Use the block_device_mapping property of the 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. + The following example creates a bootable volume from an image, and uses it to +boot an instance: + resources: + bootable_volume: + type: OS::Cinder::Volume + properties: + size: 10 + image: ubuntu-trusty-x86_64 + + instance: + type: OS::Nova::Server + properties: + flavor: m1.small + networks: + - network: private + block_device_mapping: + - device_name: vda + volume_id: { get_resource: bootable_volume } + delete_on_termination: false + +
+
+
diff --git a/doc/user-guide/hot/section_composition.xml b/doc/user-guide/hot/section_composition.xml new file mode 100644 index 0000000000..0c275bdda2 --- /dev/null +++ b/doc/user-guide/hot/section_composition.xml @@ -0,0 +1,108 @@ + +
+ + Template composition + When writing complex templates you are encouraged to break up your +template into separate smaller templates. These can then be brought +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 +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. + + + To achieve this: + + + The Orchestration client gets the associated template files and passes them +along in the files section of the POST stacks/ API request. + + + The environment in the Orchestration engine manages the mapping of resource +type to template creation. + + + The Orchestration engine translates template parameters into resource +properties. + + + The following examples illustrate how you can use a custom template to define +new types of resources. These examples use a custom template stored in a +my_nova.yml file: + heat_template_version: 2013-05-23 + +parameters: + key_name: + type: string + description: Name of a KeyPair + +resources: + server: + type: OS::Nova::Server + properties: + key_name: {get_param: key_name} + flavor: m1.small + image: ubuntu-trusty-x86_64 +
+ + Use the template filename as type + The following template defines the my_nova.yaml file as value for the +type property of a resource: + heat_template_version: 2013-05-23 +resources: + my_server: + type: my_nova.yaml + properties: + key_name: my_key + The key_name argument of the my_nova.yaml template gets its value from +the key_name property of the new template. + + The above reference to my_nova.yaml assumes it is in the same directory. +You can use any of the following forms: + + + Relative path (my_nova.yaml) + + + Absolute path (file:///home/user/templates/my_nova.yaml) + + + Http URL (http://example.com/templates/my_nova.yaml) + + + Https URL (https://example.com/templates/my_nova.yaml) + + + + To create the stack run: + $ heat stack-create -f main.yaml stack1 +
+
+ + Define a new resource type + You can associate a name to the my_noya.yaml template in an environment +file. If the name is already known by the Orchestration module then your new +resource will override the default one. + In the following example a new OS::Nova::Server resource overrides the +default resource of the same name. + An env.yaml environment file holds the definition of the new resource: + resource_registry: + "OS::Nova::Server": my_nova.yaml + + See for more detail about environment files. + + You can now use the new OS::Nova::Server in your new template: + resources: + my_server: + type: OS::Nova::Server + properties: + key_name: my_key + To create the stack run: + $ heat stack-create -f main.yaml -e env.yaml example-two +
+
diff --git a/doc/user-guide/hot/section_environment.xml b/doc/user-guide/hot/section_environment.xml new file mode 100644 index 0000000000..f1cf4e2d5a --- /dev/null +++ b/doc/user-guide/hot/section_environment.xml @@ -0,0 +1,108 @@ + +
+ + Environments + The environment affects the runtime behaviour of a template. It provides a way +to override the resource implementations and a mechanism to place parameters +that the service needs. + To fully understand the runtime behavior you have to consider what plug-ins are +installed on the cloud you're using. +
+ + Environment file format + The environment is a yaml text file that contains two main sections: + + + + parameters + + + A map of key/pair values. + + + + + resource_registry + + + Definition of custom resources. + + + + Use the -e option of the heat stack-create command to +create a stack using with the environment defined in such a file. + You can also provide environment parameters as a list of key/value pairs using +the -P option of the heat stack-create command. + In the following example the environment is read from the my_env.yaml +file and an extra parameter is provided using the -P option: + $ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml +
+
+ + Global and effective environments + The environment used for a stack is the combination of the environment you +use with the template for the stack, and a global environment that is +determined by your cloud operator. An entry in the user environment takes +precedence over the global environment. OpenStack includes a default global +environment, but you cloud operator can add additional environment entries. + +
+
+ + Define values for a template arguments + You can define values for the template arguments in the parameters section +of an environment file: + parameters: + KeyName: my_keypair + InstanceType: m1.tiny + ImageId: F18-x86_64-cfntools +
+
+ + Create and override resources + You can create or override resources in the resource_registry section of an +environment file. The resource you provide in this manner must have an +identifier, and references either other resources IDs or the URL of an existing +template file. + The following example maps the new OS::Networking::FloatingIP +resource to the existing OS::Nova::FloatingIP resource: + resource_registry: + "OS::Networking::FloatingIP": "OS::Nova::FloatingIP" + You can use wilcards to map multiple resources: + resource_registry: + "OS::Network*": "OS::Neutron*" + To create or override a resource with a custom resource, create a template file +to define this resource, and provide the URL to the template file in the +environment file: + resource_registry: + "AWS::EC2::Instance": file:///path/to/my_instance.yaml + The supported URL scheme are file, http and https. + + The template file extension must be .yaml or .template, or it will +not be treated as a custom template resource. + + You can limit the usage of a custom resource to a specific resource of the +template: + resource_registry: + resources: + my_db_server: + "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml +
+
diff --git a/doc/user-guide/hot/section_functions.xml b/doc/user-guide/hot/section_functions.xml new file mode 100644 index 0000000000..2f6154c6c3 --- /dev/null +++ b/doc/user-guide/hot/section_functions.xml @@ -0,0 +1,77 @@ + +
+ + HOT functions +
+ + Link between resources + + + get_param + + + get_resource + + + Ref + + + Fn::GetAtt / get_attr + + +
+
+ + String manipulations + + + get_file + + + list_join + + + str_replace + + + Fn::Base64 + + + Fn::Join + + + Fn::Split + + + Fn::Replace + + +
+
+ + Lookup structured data + + + Fn::FindInMap + + + Fn::MemberListToMap + + + Fn::Select + + +
+
+ + Misc + + + Fn::ResourceFacade / resource_facade + + + Fn::GetAZs + + +
+
diff --git a/doc/user-guide/hot/section_hello_world.xml b/doc/user-guide/hot/section_hello_world.xml new file mode 100644 index 0000000000..6ebcfc722f --- /dev/null +++ b/doc/user-guide/hot/section_hello_world.xml @@ -0,0 +1,185 @@ + + +
+ + Writing a hello world HOT template + HOT is a new template format meant to replace the CloudFormation-compatible +format (CFN) as the native format supported by the Orchestration module over +time. +This guide is targeted towards template authors and explains how to write +HOT templates based on examples. A detailed specification of HOT can be found +at . + This section gives an introduction on how to write HOT templates, starting from +very basic steps and then going into more and more detail by means of examples. +
+ + A most basic template + The most basic template you can think of contains only a single resource +definition using only predefined properties. For example, the template below +could be used to deploy a single compute instance: + heat_template_version: 2013-05-23 + +description: Simple template to deploy a single compute instance + +resources: + my_instance: + type: OS::Nova::Server + properties: + key_name: my_key + image: ubuntu-trusty-x86_64 + flavor: m1.small + Each HOT template has to include the heat_template_version key with value +2013-05-23, the current HOT version. While the description key is +optional, it is good practice to include some useful text that describes what +users can do with the template. In case you want to provide a longer +description that does not fit on a single line, you can provide multi-line text +in YAML, for example: + description: > + This is how you can provide a longer description + of your template that goes over several lines. + The resources section is required and must contain at least one resource +definition. In the above example, a compute instance is defined with fixed +values for the key_name, image and flavor properties. + + All the defined elements (key pair, image, flavor) have to exist in the +OpenStack environment where the template is used. + +
+
+ + Input parameters + Input parameters defined in the parameters section of a template +allow users to customize a template during deployment. For example, this allows +for providing custom key pair names or image IDs to be used for a deployment. +From a template author's perspective, this helps to make a template more easily +reusable by avoiding hardcoded assumptions. + The following example extends the previous template to provide parameters for +the key pair, image and flavor properties of the resource: + heat_template_version: 2013-05-23 + +description: Simple template to deploy a single compute instance + +parameters: + key_name: + type: string + label: Key Name + description: Name of key-pair to be used for compute instance + image_id: + type: string + label: Image ID + description: Image to be used for compute instance + flavor: + type: string + label: Instance Type + description: Type of instance (flavor) to be used + +resources: + my_instance: + type: OS::Nova::Server + properties: + key_name: { get_param: key_name } + image: { get_param: image_id } + flavor: { get_param: flavor } + Values for the three parameters must be defined by the template user during the +deployment of a stack. The get_param intrinsic function retrieves a +user-specified value for a given parameter and uses this value for the +associated resource property. + For more information about intrinsic functions, see +. +
+ Providing default values + You can provide default values for parameters. If a user doesn't define a value +for a parameter, the default value is used during the stack deployment. The +following example defines a default value m1.small for the +flavor property: + parameters: + flavor: + type: string + label: Instance Type + description: Flavor to be used + default: m1.small + + If a template doesn't define a default value for a parameter, then the user +must define the value, otherwise the stack creation will fail. + +
+
+ Hidding parameters values + The values that a user provides when deploying a stack are available in the +stack details and can be accessed by any user in the same tenant. To hide the +value of a parameter, use the hidden boolean attribute of the parameter: + parameters: + database_password: + type: string + label: Database Password + description: Password to be used for database + hidden: true +
+
+ Restricting user input + You can restrict the values of an input parameter to make sure that the user +defines valid data for this parameter. The constraints property of an input +parameter defines a list of constraints to apply for the parameter. +The following example restricts the flavor parameter to a list of three +possible values: + parameters: + flavor: + type: string + label: Instance Type + description: Type of instance (flavor) to be used + constraints: + - allowed_values: [ m1.medium, m1.large, m1.xlarge ] + description: Value must be one of m1.medium, m1.large or m1.xlarge. + The following example defines multiple contraints for a password definition: + parameters: + database_password: + type: string + label: Database Password + description: Password to be used for database + hidden: true + constraints: + - length: { min: 6, max: 8 } + description: Password length must be between 6 and 8 characters. + - allowed_pattern: "[a-zA-Z0-9]+" + description: Password must consist of characters and numbers only. + - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*" + description: Password must start with an uppercase character. + The list of supported constraints is available in the + section. + + You can define multiple constraints of the same type. Especially in the +case of allowed patterns this not only allows for keeping regular +expressions simple and maintainable, but also for keeping error messages to +be presented to users precise. + +
+
+
+ + Template outputs + In addition to template customization through input parameters, you can +provide information about the resources created during the stack deployment to +the users in the outputs section of a template. In the following example +the output section provides the IP address of the my_instance resource: + outputs: + instance_ip: + description: The IP address of the deployed instance + value: { get_attr: [my_instance, first_address] } + + Output values are typically resolved using intrinsic function such as +the get_attr. See for more information +about intrinsic functions.. + + See for more information about the outputs section. +
+
diff --git a/doc/user-guide/hot/section_hot_spec.xml b/doc/user-guide/hot/section_hot_spec.xml new file mode 100644 index 0000000000..fee6b5630a --- /dev/null +++ b/doc/user-guide/hot/section_hot_spec.xml @@ -0,0 +1,784 @@ + + +
+ + Heat Orchestration Template (HOT) specification +
+ + Template structure + HOT templates are defined in YAML and use the following structure: + heat_template_version: 2013-05-23 + +description: + # description of the template + +parameter_groups: + # declaration of input parameter groups and order + +parameters: + # declaration of input parameters + +resources: + # declaration of template resources + +outputs: + # declaration of output parameters + + + heat_template_version + + This key with value 2013-05-23 (or a later date) indicates that the +YAML document is a HOT template of the specified version. + + + + description + + This optional key gives a description of the template, or +the workload that can be deployed using the template. + + + + parameter_groups + + This section specifies how the input parameters should be +grouped and the order to provide the parameters in. + This section is optional. + + + + parameters + + This section specifies input parameters that have to +be provided when instantiating the template. + This section is optional. + + + + resources + + This section contains the declaration of the resources of the template. +This section with at least one resource must be defined in any HOT +template, or the template would not really do anything when being +instantiated. + + + + outputs + + This section specifies output parameters available to users once the +template has been instantiated. + This section is optional. + + + +
+
+ + Parameter groups section + The parameter_groups section specifies how the input parameters should be +grouped and the order to provide the parameters in. These groups are typically +used to describe expected behavior for downstream user interfaces. + These groups are specified in a list with each group containing a list of +associated parameters. The lists are used to denote the expected order of the +parameters. A parameter can only be included in one group. Use the name of the +parameter to add it to a group. The parameters details are defined in +the parameters section. + parameter_groups: +- label: <human-readable label of parameter group> + description: <description of the parameter group> + parameters: + - <param name> + - <param name> + + + label + + A human-readable label that defines the associated group of parameters. + + + + description + + A human-readable description of the parameter group. + + + + parameters + + A list of parameters that belong with this parameter group. + + + + param name + + The name of a parameter defined in the parameters section. + + + +
+
+ + Parameters section + The parameters section defines input parameters that have to be +provided when instantiating the template. Such parameters are typically used to +customize each deployment, or for binding to environment specifics like certain +images. + Each parameter is specified in a separated nested block with the name of the +parameter defined in the first line and additional attributes such as a type or +a default value defined as nested elements: + parameters: + <param name>: + type: <string | number | json | comma_delimited_list | boolean> + label: <human-readable name of the parameter> + description: <description of the parameter> + default: <default value for parameter> + hidden: <true | false> + constraints: + <parameter constraints> + + + param name + + The name of the parameter. + + + + type + + The type of the parameter. Supported types +are string, number, comma_delimited_list, json and +boolean. + This attribute is required. + + + + label + + A human readable name for the parameter. + This attribute is optional. + + + + description + + A human readable description for the parameter. + This attribute is optional. + + + + default + + A default value for the parameter. This value is used if the user doesn't +specify his own value during deployment. + This attribute is optional. + + + + hidden + + Defines whether the parameters should be hidden when a user requests +information about a stack created from the template. This attribute can be +used to hide passwords specified as parameters. + This attribute is optional and defaults to false. + + + + constraints + + A list of constraints to apply. The constraints are validated by the +Orchestration engine when a user deploys a stack. The stack creation fails +if the parameter value doesn't comply to the constraints. + This attribute is optional. + + + + The following example shows a minimalistic definition of two parameters: + parameters: + user_name: + type: string + label: User Name + description: User name to be configured for the application + port_number: + type: number + label: Port Number + description: Port number to be configured for the web server + + The description and the label are optional, but defining these attributes +is good practice to provide useful information about the role of the +parameter to the user. + +
+ Parameter constraints + The constraints block of a parameter definition defines +additional validation constraints that apply to the value of the +parameter. The parameter values provided by a user are validated against the +contrainsts at instantiation time. The contrainsts are defined as a list with +the following syntax: + constraints: + - <constraint type>: <constraint definition> + description: <constraint description> + + + constraint type + + Type of constraint to apply. The set of currently supported constraints is +given below. + + + + constraint definition + + The actual constraint, depending on the constraint type. The +concrete syntax for each constraint type is given below. + + + + description + + A description of the constraint. The text +is presented to the user when the value he defines violates the constraint. +If ommitted, a default validation message is presented to the user. + This attribute is optional. + + + + The following example shows the definition of a string parameter with two +constraints. Note that while the descriptions for each constraint are optional, +it is good practice to provide concrete descriptions to present useful messages +to the user at deployment time. + parameters: + user_name: + type: string + label: User Name + description: User name to be configured for the application + constraints: + - length: { min: 6, max: 8 } + description: User name must be between 6 and 8 characters + - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*" + description: User name must start with an uppercase character + + While the descriptions for each constraint are optional, it is good practice +to provide concrete descriptions so useful messages can be presented to the +user at deployment time. + + The following sections list the supported types of parameter constraints, along +with the syntax for each type. +
+ length + The length constraint applies to parameters of type string. It defines +a lower and upper limit for the length of the string value. + The syntax of the length constraint is: + length: { min: <lower limit>, max: <upper limit> } + It is possible to define a length constraint with only a lower limit or an +upper limit. However, at least one of min or max must be specified. +
+
+ range + The range constraint applies to parameters of type number. It defines a +lower and upper limit for the numeric value of the parameter. + The syntax of the range constraint is: + range: { min: <lower limit>, max: <upper limit> } + It is possible to define a range constraint with only a lower limit or an +upper limit. However, at least one of min or max must be specified. + The minimum and maximum boundaries are included in the range. For example, the +following range constraint would allow for all numeric values between 0 and 10: + range: { min: 0, max: 10 } +
+
+ allowed_values + The allowed_values constraint applies to parameters of type string or +number. It specifies a set of possible values for a parameter. At +deployment time, the user-provided value for the respective parameter must +match one of the elements of the list. + The syntax of the allowed_values constraint is: + allowed_values: [ <value>, <value>, ... ] + Alternatively, the following YAML list notation can be used: + allowed_values: + - <value> + - <value> + - ... + For example: + parameters: + instance_type: + type: string + label: Instance Type + description: Instance type for compute instances + constraints: + - allowed_values: + - m1.small + - m1.medium + - m1.large +
+
+ allowed_pattern + The allowed_pattern constraint applies to parameters of type string. +It specifies a regular expression against which a user-provided parameter value +must evaluate at deployment. + The syntax of the allowed_pattern constraint is: + allowed_pattern: <regular expression> + For example: + parameters: + user_name: + type: string + label: User Name + description: User name to be configured for the application + constraints: + - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*" + description: User name must start with an uppercase character +
+
+ custom_constraint + The custom_constraint constraint adds an extra step of validation, +generally to check that the specified resource exists in the backend. Custom +constraints get implemented by plug-ins and can provide any kind of advanced +constraint validation logic. + The syntax of the custom_constraint constraint is: + custom_constraint: <name> + The name attribute specifies the concrete type of custom constraint. It +corresponds to the name under which the respective validation plugin has been +registered in the Orchestration engine. + For example: + parameters: + key_name + type: string + description: SSH key pair + constraints: + - custom_constraint: nova.keypair +
+
+
+ Pseudo Parameters + In addition to parameters defined by a template author, the Orchestration +module also creates two parameters for every stack that allow referential +access to the stack's name and identifier. These parameters are named +OS::stack_name for the stack name and OS::stack_id for the stack +identifier. These values are accessible via the get_param intrinsic +function, just like user-defined parameters. +
+
+
+ + Resources section + The resources section defines actual resources that make up a stack +deployed from the HOT template (for instance compute instances, networks, +storage volumes). + Each resource is defined as a separate block in the resources section with +the following syntax: + resources: + <resource ID>: + type: <resource type> + properties: + <property name>: <property value> + metadata: + <resource specific metadata> + depends_on: <resource ID or list of ID> + update_policy: <update policy> + deletion_policy: <deletion policy> + + + resource ID + + A resource ID which must be unique within the resources section of the +template. + + + + type + + The resource type, such as OS::Nova::Server or OS::Neutron::Port. + This attribute is required. + + + + properties + + A list of resource-specific properties. The property value can be provided +in place, or via a function (see Intrinsic functions). + This section is optional. + + + + metadata + + Resource-specific metadata. + This section is optional. + + + + depends_on + + Dependencies of the resource on one or more resources of the template. + See Resource dependencies for details. + This attribute is optional. + + + + update_policy + + Update policy for the resource, in the form of a nested dictionary. Whether +update policies are supported and what the exact semantics are depends on +the type of the current resource. + This attribute is optional. + + + + deletion_policy + + Deletion policy for the resource. Which type of deletion policy is +supported depends on the type of the current resource. + This attribute is optional. + + + + Depending on the type of resource, the resource block might include more +resource specific data. + All resource types that can be used in CFN templates can also be used in HOT +templates, adapted to the YAML structure as outlined above. + The following example demonstrates the definition of a simple compute resource +with some fixed property values: + resources: + my_instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: F18-x86_64-cfntools +
+ Resource dependencies + The depends_on attribute of a resource defines a dependency between this +resource and one or more other resources. + If a resource depends on just one other resource, the ID of the other resource +is specified as string of the depends_on attribute, as shown in the +following example: + resources: + server1: + type: OS::Nova::Server + depends_on: server2 + + server2: + type: OS::Nova::Server + If a resource depends on more than one other resources, the value of the +depends_on attribute is specified as a list of resource IDs, as shown in +the following example: + resources: + server1: + type: OS::Nova::Server + depends_on: [ server2, server3 ] + + server2: + type: OS::Nova::Server + + server3: + type: OS::Nova::Server +
+
+
+ + Outputs section + The outputs section defines output parameters that should be available to +the user once a stack has been created. This would be, for example, parameters +such as IP addresses of deployed instances, or URLs of web applications +deployed as part of a stack. + Each output parameter is defined as a separate block within the outputs section +according to the following syntax: + outputs: + <parameter name>: + description: <description> + value: <parameter value> + + + parameter name + + The output parameter name, which must be unique within the outputs +section of a template. + + + + description + + A short description of the output parameter. + This attribute is optional. + + + + parameter value + + The value of the output parameter. This value is usually resolved by means +of a function. See Intrinsic functions for details about +the functions. + This attribute is required. + + + + The example below shows how the IP address of a compute resource can +be defined as an output parameter: + outputs: + instance_ip: + description: IP address of the deployed compute instance + value: { get_attr: [my_instance, first_address] } +
+
+ + Intrinsic functions + HOT provides a set of intrinsic functions that can be used inside templates +to perform specific tasks, such as getting the value of a resource attribute at +runtime. The following section describes the role and syntax of the intrinsic +functions. +
+ get_attr + The get_attr function references an attribute of a +resource. The attribute value is resolved at runtime using the resource +instance created from the respective resource definition. + The syntax of the get_attr function is: + get_attr: + - <resource ID> + - <attribute name> + - <key/index 1> (optional) + - <key/index 2> (optional) + - ... + + + resource ID + + The resource ID for which the attribute needs to be resolved. + The resource ID must exist in the resources section of the template. + + + + attribute name + + The attribute name to be resolved. If the attribute returns a complex data +structure such as a list or a map, then subsequent keys or indexes can be +specified. These additional parameters are used to navigate the data +structure to return the desired value. + + + + The following example demonstrates how to use the get_param function: + resources: + my_instance: + type: OS::Nova::Server + # ... + +outputs: + instance_ip: + description: IP address of the deployed compute instance + value: { get_attr: [my_instance, first_address] } + instance_private_ip: + description: Private IP address of the deployed compute instance + value: { get_attr: [my_instance, networks, private, 0] } + In this example, if the networks attribute contained the following data: + {"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"], + "private": ["10.0.0.1"]} + then the value of the get_attr function would resolve to 10.0.0.1 +(first item of the private entry in the networks map). +
+
+ get_file + The get_file function returns the content of a file into the template. +It is generally used as a file inclusion mechanism for files +containing scripts or configuration files. + The syntax of the get_file function is: + get_file: <content key> + The content key is used to look up the files dictionary that is +provided in the REST API call. The Orchestration client command +(heat) is get_file aware and will populate the files +dictionnary with the actual content of fetched paths and URLs. The +Orchestration client command supports relative paths and will transform these +to the absolute URLs required by the Orcestration API. + + The get_file argument must be a static path or URL and not rely on +intrinsic functions like get_param. the Orchestration client does not +process intrinsic functions (they are only processed by the Orchestration +engine). + + The example below demonstrates the get_file function usage with both +relative and absolute URLs: + resources: + my_instance: + type: OS::Nova::Server + properties: + # general properties ... + user_data: + get_file: my_instance_user_data.sh + + my_other_instance: + type: OS::Nova::Server + properties: + # general properties ... + user_data: + get_file: http://example.com/my_other_instance_user_data.sh + The files dictionary generated by the Orchestration client during +instantiation of the stack would contain the following keys: +* file:///path/to/my_instance_user_data.sh +* http://example.com/my_other_instance_user_data.sh* +
+
+ get_param + The get_param function references an input parameter of a template. It +resolves to the value provided for this input parameter at runtime. + The syntax of the get_param function is: + get_param: + - <parameter name> + - <key/index 1> (optional) + - <key/index 2> (optional) + - ... + + + parameter name + + The parameter name to be resolved. If the parameters returns a complex data +structure such as a list or a map, then subsequent keys or indexes can be +specified. These additional parameters are used to navigate the data +structure to return the desired value. + + + + The following example demonstrates the use of the get_param function: + parameters: + instance_type: + type: string + label: Instance Type + description: Instance type to be used. + server_data: + type: json + +resources: + my_instance: + type: OS::Nova::Server + properties: + flavor: { get_param: instance_type} + metadata: { get_param: [ server_data, metadata ] } + key_name: { get_param: [ server_data, keys, 0 ] } + In this example, if the instance_type and server_data parameters +contained the following data: + {"instance_type": "m1.tiny", +{"server_data": {"metadata": {"foo": "bar"}, + "keys": ["a_key","other_key"]}}} + then the value of the property flavor would resolve to m1.tiny, +metadata would resolve to {"foo": "bar"} and key_name would resolve +to a_key. +
+
+ get_resource + The get_resource function references another resource within the +same template. At runtime, it is resolved to reference the ID of the referenced +resource, which is resource type specific. For example, a reference to a +floating IP resource returns the respective IP address at runtime. The syntax +of the get_resource function is: + get_resource: <resource ID> + The resource ID of the referenced resource is given as single parameter to the +get_resource function. + For exemple: + resources: + instance_port: + type: OS::Neutron::Port + properties: ... + + instance: + type: OS::Nova::Server + properties: + ... + networks: + port: { get_resource: instance_port } +
+
+ list_join + The list_join function joins a list of strings with the given delimiter. + The syntax of the list_join function is: + list_join: +- <delimiter> +- <list to join> + For example: + list_join: [', ', ['one', 'two', 'and three']] + This resolve to the string one, two, and three. +
+
+ resource_facade + The resource_facade function retrieves data in a parent provider template. + A provider template provdes a custom definition of a resource, called its +facade. For more information about custom templates, see . +The syntax of the resource_facade function is: + resource_facade: <data type> + data type can be one of metadata, deletion_policy or +update_policy. +
+
+ str_replace + The str_replace function dynamically constructs strings by +providing a template string with placeholders and a list of mappings to assign +values to those placeholders at runtime. The placeholders are replaced with +mapping values wherever a mapping key exactly matches a placeholder. + The syntax of the str_replace function is: + str_replace: + template: <template string> + params: <parameter mappings> + + + template + + Defines the template string that contains placeholders which will be +substituted at runtime. + + + + params + + Provides parameter mappings in the form of dictionary. Each key refers to a +placeholder used in the template attribute. + + + + The following example shows a simple use of the str_replace function in the +outputs section of a template to build a URL for logging into a deployed +application: + resources: + my_instance: + type: OS::Nova::Server + # general metadata and properties ... + +outputs: + Login_URL: + description: The URL to log into the deployed application + value: + str_replace: + template: http://host/MyApplication + params: + host: { get_attr: [ my_instance, first_address ] } + The following examples show the use of the str_replace function to build an +instance initialization script: + parameters: + DBRootPassword: + type: string + label: Database Password + description: Root password for MySQL + hidden: true + +resources: + my_instance: + type: OS::Nova::Server + properties: + # general properties ... + user_data: + str_replace: + template: | + #!/bin/bash + echo "Hello world" + echo "Setting MySQL root password" + mysqladmin -u root password $db_rootpassword + # do more things ... + params: + $db_rootpassword: { get_param: DBRootPassword } +
+
+
diff --git a/doc/user-guide/hot/section_software_deployment.xml b/doc/user-guide/hot/section_software_deployment.xml new file mode 100644 index 0000000000..ea32842bd9 --- /dev/null +++ b/doc/user-guide/hot/section_software_deployment.xml @@ -0,0 +1,399 @@ + +
+ + Software configuration + There are a variety of options to configure the software which runs on the +servers in your stack. These can be broadly divided into the following: + + + Custom image building + + + User-data boot scripts and cloud-init + + + Software deployment resources + + + This section will describe each of these options and provide examples for +using them together in your stacks. +
+ + Image building + The first opportunity to influence what software is configured on your servers +is by booting them with a custom-built image. There are a number of reasons +you might want to do this, including: + + + - since the required software is already on the image there +is no need to download and install anything at boot time. + + + - software downloads can fail for a number of reasons +including transient network failures and inconsistent software repositories. + + + - custom built images can be verified in test +environments before being promoted to production. + + + - post-boot configuration may depend on +agents already being installed and enabled + + + A number of tools are available for building custom images, including: + + + 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. +
+
+ + 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. + 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. + Whether the image is using Cloud-init or not, it should be possible to +specify a shell script in the user_data property and have it be executed by +the server during boot: + resources: + + the_server: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data: | + #!/bin/bash + echo "Running boot script" + # ... + +
+ : debugging these scripts it is often useful to view the boot +log using nova console-log <server-id> to view the progress of boot +script execution. +
+ Often there is a need to set variable values based on parameters or resources +in the stack. This can be done with the str_replace intrinsic function: + parameters: + foo: + default: bar + +resources: + + the_server: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data: + str_replace: + template: | + #!/bin/bash + echo "Running boot script with $FOO" + # ... + params: + $FOO: {get_param: foo} + +
+ : If a stack-update is performed and there are any changes +at all to the content of user_data then the server will be replaced +(deleted and recreated) so that the modified boot configuration can be +run on a new server. +
+ When these scripts grow it can become difficult to maintain them inside the +template, so the get_file intrinsic function can be used to maintain the +script in a separate file: + parameters: + foo: + default: bar + +resources: + + the_server: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data: + str_replace: + template: {get_file: the_server_boot.sh} + params: + $FOO: {get_param: foo} + +
+ : str_replace can replace any strings, not just strings +starting with $. However doing this for the above example is useful +because the script file can be executed for testing by passing in +environment variables. +
+
+ Choosing the user_data_format + The 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 +for user_data_format, it is considered legacy and RAW or +SOFTWARE_CONFIG will generally be more appropriate. + For RAW the user_data is passed to Nova unmodified. For a Cloud-init +enabled image, the following are both valid RAW user-data: + resources: + + server_with_boot_script: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data_format: RAW + user_data: | + #!/bin/bash + echo "Running boot script" + # ... + + server_with_cloud_config: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data_format: RAW + user_data: | + #cloud-config + final_message: "The system is finally up, after $UPTIME seconds" + For SOFTWARE_CONFIG user_data is bundled as part of the software config +data, and metadata is derived from any associated software deployment +resources. +
+
+ Signals and wait conditions + 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 +OS::Heat::WaitCondition and OS::Heat::SwiftSignal both perform +this function using different techniques and tradeoffs. + 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 +to a project which belongs to the stack, in an identity domain which is +dedicated to the orchestration service. + Sending the signal is a simple HTTP request, as with this example using curl: + curl -i -X POST -H 'X-Auth-Token: <token>' \ + -H 'Content-Type: application/json' -H 'Accept: application/json' \ + '<wait condition URL>' --data-binary '<json containing signal data>' + The JSON containing the signal data is expected to be of the following format: + { + "status": "SUCCESS", + "reason": "The reason which will appear in the 'heat event-list' output", + "data": "Data to be used elsewhere in the template via get_attr", + "id": "Optional unique ID of signal" +} + All of these values are optional, and if not specified will be set to the +following defaults: + { + "status": "SUCCESS", + "reason": "Signal <id> received", + "data": null, + "id": "<sequential number starting from 1 for each signal received>" +} + If status is set to FAILURE then the resource (and the stack) will go +into a FAILED state using the reason as failure reason. + The following template example uses the convenience attribute curl_cli +which builds a curl command with a valid token: + resources: + wait_condition: + type: OS::Heat::WaitCondition + properties: + handle: {get_resource: wait_handle} + # Note, count of 5 vs 6 is due to duplicate signal ID 5 sent below + count: 5 + timeout: 300 + + wait_handle: + type: OS::Heat::WaitConditionHandle + + the_server: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data_format: RAW + user_data: + str_replace: + template: | + #!/bin/sh + # Below are some examples of the various ways signals + # can be sent to the Handle resource + + # Simple success signal + wc_notify --data-binary '{"status": "SUCCESS"}' + + # Or you optionally can specify any of the additional fields + wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal2"}' + wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal3", "data": "data3"}' + wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal4", "data": "data4"}' + + # If you require control of the ID, you can pass it. + # The ID should be unique, unless you intend for duplicate + # signals to overrite each other. The following two calls + # do the exact same thing, and will be treated as one signal + # (You can prove this by changing count above to 7) + wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}' + wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}' + + # Example of sending a failure signal, optionally + # reason, id, and data can be specified as above + # wc_notify --data-binary '{"status": "FAILURE"}' + params: + wc_notify: { get_attr: [wait_handle, curl_cli] } + +outputs: + wc_data: + value: { get_attr: [wait_condition, data] } + # this would return the following json + # {"1": null, "2": null, "3": "data3", "4": "data4", "5": null} + + wc_data_4: + value: { get_attr: [wait_condition, data, '4'] } + # this would return "data4" + + 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. + Sending the signal is a simple HTTP request, as with this example using curl: + curl -i -X PUT '<object URL>' --data-binary '<json containing signal data>' + The above template example only needs to have the type changed to the +swift signal resources: + resources: + signal: + type: OS::Heat::SwiftSignal + properties: + handle: {get_resource: wait_handle} + timeout: 300 + + signal_handle: + type: OS::Heat::SwiftSignalHandle + # ... + The decision to use OS::Heat::WaitCondition or +OS::Heat::SwiftSignal will depend on a few factors: + + + OS::Heat::SwiftSignal depends on the availability of an Object +Storage API + + + 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). + + + The preference to protect signal URLs with token authentication or a +secret webhook URL. + + +
+
+ Software config resources + Boot configuration scripts can also be managed as their own resources. This +allows configuration to be defined once and run on multiple server resources. +These software-config resources are stored and retrieved via dedicated calls +to the Orchestration API. It is not possible to modify the contents of an +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 OS::Heat::SoftwareConfig is used for storing configs +represented by text scripts, for example: + resources: + boot_script: + type: OS::Heat::SoftwareConfig + properties: + group: ungrouped + config: | + #!/bin/bash + echo "Running boot script" + # ... + + server_with_boot_script: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data_format: RAW + user_data: {get_resource: boot_script} + The resource 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 +valid cloud-config are done. + parameters: + file_content: + type: string + description: The contents of the file /tmp/file + +resources: + boot_config: + type: OS::Heat::CloudConfig + properties: + cloud_config: + write_files: + - path: /tmp/file + content: {get_param: file_content} + + server_with_cloud_config: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data_format: RAW + user_data: {get_resource: boot_config} + + The resource OS::Heat::MultipartMime allows multiple +OS::Heat::SoftwareConfig and OS::Heat::CloudConfig +resources to be combined into a single Cloud-init multi-part message: + parameters: + file_content: + type: string + description: The contents of the file /tmp/file + + other_config: + type: string + description: The ID of a software-config resource created elsewhere + +resources: + boot_config: + type: OS::Heat::CloudConfig + properties: + cloud_config: + write_files: + - path: /tmp/file + content: {get_param: file_content} + + boot_script: + type: OS::Heat::SoftwareConfig + properties: + group: ungrouped + config: | + #!/bin/bash + echo "Running boot script" + # ... + + server_init: + type: OS::Heat::MultipartMime + properties: + parts: + - config: {get_resource: boot_config} + - config: {get_resource: boot_script} + - config: {get_resource: other_config} + + server: + type: OS::Nova::Server + properties: + # flavor, image etc + user_data_format: RAW + user_data: {get_resource: server_init} + +
+
+