About Template Components

A template in Oracle Cloud Stack is a YAML document that’s comprised of several components, including parameters, resources, attributes, and conditions.

Description of the illustration diagram_template_components.png

Topics

• What are Parameters

• What are Resources

• What are Dependencies

• What are Attributes

• What are Conditions

• What are Maps

• What are Custom Actions

• What are Functions

What are Parameters

Template parameters define the inputs that users of this template can provide to Oracle Cloud Stack when they create a cloud stack from the template.

Parameters make your templates more customizable and reusable. For example, a template’s parameters might include inputs like:

• cloudUserName

• databasePassword

• serverComputeShape

The definition for a template parameter includes its name, data type (text, number, boolean, SSH key, and so on), and whether the parameter is mandatory or optional. If a parameter is optional, you can also define a default value if one is not provided by the user. Template parameters also support various constraints that are validated at runtime, such as the allowed values, minimum value, and maximum value.

The values of these input parameters are referenced in other parts of the template by using the GetParam function.

You can optionally group related template parameters together. Each parameter group is given a label, which is used as a heading in the Details page of the Oracle Cloud Stack creation wizard. The image below depicts a parameter group named Oracle Database Cloud Service Details. This group consists of four template parameters:

Description of the illustration parameter_group_example.png

If you don't assign a parameter to a group, it will be displayed under a generic Configuration heading in the creation wizard. Standard parameters that are displayed for all templates, including Name and Description, are always displayed under the Stack Details heading.

Note:

Parameter groups have no effect on the CLI or REST API.

What are Resources

Oracle Cloud Stack provisions one or more Oracle Cloud resources when a cloud stack is created from the template.

For a list of the resource types supported by Oracle Cloud Stack see List of Resource Types.

Each resource in a template has a name and parameters, which provide the specific names and values that Oracle Cloud Stack sends to the REST endpoint for creating this type of cloud resource. For example, the REST endpoint for creating an instance of Oracle Java Cloud Service supports parameters like:

• serviceName

• cloudStorageContainer

• backupDestination

As a template author, you assign values to these resource parameters. The value can be typed directly into the template, or it can be determined dynamically through the use of functions. For instance, you can use the GetParam function to retrieve a user-supplied template parameter.

Many REST endpoints in Oracle Cloud require a request payload in JSON format, which organizes parameters into a hierarchical structure. Consequently, resource parameters in Oracle Cloud Stack are also defined as a hierarchy, with parent parameters and child parameters. For example, Oracle Java Cloud Service supports a JSON structure like the following:

serviceName: myjcs
components: {
  WLS: {
    adminUserName: myadmin
    managedServerCount: 3
  }
}

When a stack is created, Oracle Cloud Stack uses your resource definitions in the template to automatically construct these JSON payloads.

What are Dependencies

A template contains one or more resources. Dependencies control the order in which Oracle Cloud Stack provisions these resources when a new cloud stack is created from a template.

As a template author, you can define explicit dependencies between resources. For example, a template can explicitly state that the creation of ResourceC depends on the creation of ResourceA and ResourceB. In other words, when Oracle Cloud Stack executes this template it must successfully create ResourceA and ResourceB before creating ResourceC, regardless of the order in which these resources are defined in the template.

Oracle Cloud Stack will also automatically identify and honor any implicit dependencies between resources in a template, even if the author does not explicitly define them. This occurs when a template states that the value of a resource’s parameter is the runtime attribute of another resource. For example, consider a template in which the databaseURL parameter of ResourceB is configured to use the url attribute of ResourceA. Because Oracle Cloud Stack cannot retrieve this url attribute until after it successfully creates ResourceA, there is an implicit dependency between these two resources. ResourceA must be created prior to creating ResourceB.

To optimize performance, Oracle Cloud Stack creates multiple resources in parallel if no dependencies exist between them.

What are Attributes

The values of some resource parameters may not be known in advance because they are generated as part of provisioning a resource in the cloud. Therefore, these values must be retrieved at runtime by Oracle Cloud Stack after a resource has been successfully created.

Consider a scenario in which a stack template includes an application resource and a database resource. The application resource requires a parameter dbURL, which is the URL of a running database resource. The database resource’s connectionString attribute has this information. Therefore, when configuring the application resource, you can set its dbURL to the value of the database’s connectionString attribute.

Similar to creating a resource, Oracle Cloud Stack uses a REST endpoint to collect resource attributes. For example, the REST endpoint for viewing an instance of Oracle Database Cloud Service responds with attributes like:

• service_name

• num_nodes

• listenerPort

Use the GetAtt function in your template to retrieve the value of a resource’s attribute. The response payload of these REST endpoints are often in JSON format, which organizes the attributes as a hierarchy like the following example:

{
  "serviceId":1104,
  "serviceName":"MyDatabase",
  "cloudStorageContainer":
  {
    "value":"MyStorageURL",
  }
}

In order to retrieve attributes within this JSON hierarchy, templates use a dot notation. For example: cloudStorageContainer.value

When you monitor running stacks from the CLI or REST API, Oracle Cloud Stack returns a set of standard runtime attributes for each stack, such as who created the stack. But each template can also define custom stack attributes. For example, you can define a stack attribute named database that maps to a database’s connectionString attribute.

What are Conditions

Stack templates include features that allow you to customize how a stack is created under different conditions.

Working with conditions in Oracle Cloud Stack is similar to working with standard programming constructs like If/Then/Else. You can define conditional expressions in a template and then refer to these conditions within other template elements:

• Display a template parameter to the user only if the specified conditions are true.

• Provision a resource only if the specified conditions are true.

Consider the following scenario:

• If the template parameter production is true, then set a resource’s clusterSize to 3.

• If the template parameter production is false, then do not configure a resource’s clusterSize.

You can also use conditional functions like If, Equals, Not, and GreaterThan to further control the configuration of template parameters and resources.

What are Maps

Maps are data structures that allow you to define static values within a template. You refer to these values within other template components such as resources.

You organize the data within a map as follows:

• A map contains one or more submaps.

• A submap contains one or more key-value pairs.

For example, you could use a map to define:

• The compute shapes to use in development, test, and production stacks

• The user names for the resources in a stack

mymap:
  shapes: {"dev":"oc3","test":"oc4","prod":"oc5"}
  users: {"db":"mydbuser","java":"myjavauser"}

What are Custom Actions

Use Oracle Cloud Stack to execute custom operating system (OS) commands and scripts after the creation of a resource in your template.

For example, you can use custom actions to:

• Install an OS package

• Modify the default OS configuration

• Create a database schema

• Deploy an application

• Download files from cloud storage

Custom actions are only supported for Oracle Cloud services that provide access to their administration node (virtual machine) through a Secure Shell (SSH) interface. Custom actions are not supported on Oracle-managed or Autonomous cloud services.

Custom actions are defined within a special type of resource called a Software Component. These Software Components and their actions are assigned to other cloud resources in the same template.

What are Functions

Oracle Cloud Stack provides template authors with many functions to help validate, evaluate, and manipulate values.

These functions are executed at runtime by Oracle Cloud Stack when a stack is being created. Some basic functions include:

• GetParam — Retrieve the value of a template parameter.

• GetAtt — Retrieve the value of the runtime attribute from a specific resource.

• If — Evaluate a condition in this template and return different values if the condition evaluates to true or false.

See List of Functions.