From 08e04e6733e69080743521c1673c53a96ae42907 Mon Sep 17 00:00:00 2001 From: Angus Salkeld Date: Thu, 25 Jul 2013 14:53:51 +1000 Subject: [PATCH] Add some docs for intrinsic functions. And start the template guide. DocImpact Change-Id: I4dc32dfc20b464e09b78f192b6f4931ce812fd4b --- doc/source/index.rst | 1 + doc/source/template_guide/functions.rst | 273 ++++++++++++++++++++++++ doc/source/template_guide/index.rst | 20 ++ 3 files changed, 294 insertions(+) create mode 100644 doc/source/template_guide/functions.rst create mode 100644 doc/source/template_guide/index.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index ed5cd0e3..b3a21027 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -35,6 +35,7 @@ Getting Started getting_started/index troubleshooting/index + template_guide/index glossary Man Pages diff --git a/doc/source/template_guide/functions.rst b/doc/source/template_guide/functions.rst new file mode 100644 index 00000000..209912a4 --- /dev/null +++ b/doc/source/template_guide/functions.rst @@ -0,0 +1,273 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +Built in functions +================== + +There are a number of functions that you can use to help you write templates. + +All of these functions (except *Ref*) start with *Fn::*. + + +Ref +--- +Return the value of the named parameter or Resource. + +Parameters +~~~~~~~~~~ +**Name**: the name of the Resource or Parameter. + +Usage +~~~~~ +:: + + {Ref: my_server} + +Returns +~~~~~~~ +:: + + instance-0003 + +Fn::Base64 +---------- +This returns the Base64 representation of the input string. + +Parameters +~~~~~~~~~~ +**String**: the string to convert. + +Usage +~~~~~ + +:: + + {Base64: "convert this string please."} + +Returns +~~~~~~~ +Base64 of the input string. + +Fn::FindInMap +------------- +returns the value corresponding to keys into a two-level map declared in the Mappings section. + +Parameters +~~~~~~~~~~ +**MapName**: The logical name of a mapping declared in the Mappings section that contains the keys and values. + +**TopLevelKey**: The top-level key name. It's value is a list of key-value pairs. + +**SecondLevelKey**: The second-level key name, which is set to one of the keys from the list assigned to TopLevelKey. + +Usage +~~~~~ + +:: + Mapping: + MyContacts: + jone: {phone: 337, email: a@b.com} + jim: {phone: 908, email: g@b.com} + + {"Fn::FindInMap": ["MyContacts", "jim", "phone" ] } + +Returns +~~~~~~~ + +In the case above it will return **908** + +Fn::GetAtt +---------- +Returns an attribute of a Resource within the template. + +Parameters +~~~~~~~~~~ +**Resource**: the name of the Resource. + +**Attribute**: the name of the attribute. + +Usage +~~~~~ + +:: + + {Fn::GetAtt: [my_server, PublicIp]} + +Returns +~~~~~~~ +In the case above it would return an Ipaddress like **10.0.0.2** + +Fn::GetAZs +---------- +Return the Availablity Zones within the given region. + +*Note: AZ's and regions are not fully implemented in Heat.* + +Parameters +~~~~~~~~~~ +region: the name of the region. + +Usage +~~~~~ +:: + + {Fn::GetAZs: ""} + +Returns +~~~~~~~ +This returns what nova returns from availablity_zones.list() + +Fn::Join +-------- +Like python join, it joins a list of strings with the given delimiter. + +Parameters +~~~~~~~~~~ +**delimiter**: a string to join the list with. + +**list**: a list of strings + +Usage +~~~~~ + +:: + + {Fn::Join: [",", ["beer", "wine", "more beer"]]} + +Returns +~~~~~~~ + +The above example would return "beer, wine, more beer". + +Fn::Select +---------- +Select an item from a list. + +*Heat extension: Select an item from a dict* + +Parameters +~~~~~~~~~~ +Selector: the number of item in the list or the name of the item in +the dict. + +Usage +~~~~~ + +:: + (for a list lookup) + { "Fn::Select" : [ "2", [ "apples", "grapes", "mangoes" ] ] } + returns "mangoes" + + (for a dict lookup) + { "Fn::Select" : [ "red", {"red": "a", "flu": "b"} ] } + returns "a" + +Fn::Split +--------- +This is the reverse of Join. Convert a string into a list based on the +delimiter. + +Parameters +~~~~~~~~~~ +**delimiter**: a string. + +**string**: the string to split. + +Usage +~~~~~ +:: + + { "Fn::Split" : [ ",", "str1,str2,str3,str4"]} + returns + {["str1", "str2", "str3", "str4"]} + +Fn::Replace +----------- +Find an replace one string with another. + +Parameters +~~~~~~~~~~ +**subsitutions**: a map of subsitutions. + +**string**: the string to do the substitutions in. + +Usage +~~~~~ +:: + {"Fn::Replace": [ + {'$var1': 'foo', '%var2%': 'bar'}, + '$var1 is %var2%' + ]} + returns + "foo is bar" + + +Fn::ResourceFacade +------------------ +When writing a Template Resource: + - user writes a template that will fill in for a resource (the resource is the facade). + - when they are writing their template they need to access the metadata from + the facade. + + +Parameters +~~~~~~~~~~ +Attribute Name: one of Metadata, DeletionPolicy or UpdatePolicy. + +Usage +~~~~~ + +:: + {'Fn::ResourceFacade': 'Metadata'} + {'Fn::ResourceFacade': 'DeletionPolicy'} + {'Fn::ResourceFacade': 'UpdatePolicy'} + + +Example +~~~~~~~ +Here is a top level template (top.yaml) + +:: + resources: + my_server: + type: OS::Compute::Server + metadata: + key: value + some: more stuff + + +Here is a resource template (my_actual_server.yaml) + +:: + resources: + _actual_server_: + type: OS::Compute::Server + metadata: {Fn:ResourceFacade metadata} + +my environment (env.yaml) + +:: + resource_registry: + resources: + my_server: + "OS::Compute::Server": my_actual_server.yaml + +To use it + +:: + heat stack-create -f top.yaml -e env.yaml + + +What happened is the metadata in top.yaml (key: value, some: more +stuff) gets passed into the resource template via the **Fn::ResourceFacade** +function. diff --git a/doc/source/template_guide/index.rst b/doc/source/template_guide/index.rst new file mode 100644 index 00000000..3c5ed7eb --- /dev/null +++ b/doc/source/template_guide/index.rst @@ -0,0 +1,20 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +Template Guide +============== + +.. toctree:: + :maxdepth: 2 + + functions \ No newline at end of file -- 2.45.2