Stack Template Syntax

Stack template is a UTF8-encoded file.

You can quickly create a resource stack based on a stack template. With a stack template, you can define what cloud resources you need, the dependency between the resources, and the resource configuration. CloudFormation analyzes the stack template and automatically creates and configures all resources.

Stack Template Structure

The stack template structure is as follows.
{
    "ZStackTemplateFormatVersion" : "YYYY-MM-DD",
    "Description" : "The description of the stack template, which is used to provide information such as application scenarios and the structure of the stack template.",
    "Parameters" : {
      // The parameters you can specify when creating a resource stack.
    },
    "Mappings" : {
      // The mapping tables. Mapping tables are nested tables.
    },
    "Resources" : {
      // The detailed information of resources, including configurations and dependencies.
    },
    "Outputs" : {
      // The outputs that are used to provide useful information such as resource properties. You can use API to obtain this information.
  }
  • ZStackTemplateFormatVersion (Required)
    The version of the stack template.
    • Format: YYYY-MM-DD
  • Description (Optional)
    The description of the stack template, which is used to provide information such as application scenarios and the structure of the stack template.
    • A detailed description can help users better understand the content of the stack template.
  • Parameters (Optional)
    The parameters you can specify when creating a resource stack.
    • For example, an instance offering is often defined as a parameter.
    • Parameters have default values.
    • Parameters can improve the flexibility and reusability of the stack template.
    • For more information about Parameters, see the Parameters topic.
  • Mappings (Optional)
    The mapping tables. Mapping tables are nested tables.
    • You can use Fn::FindInMap to select values through corresponding keys.
    • You can use parameter values as keys.
    • For example, you can search the region-image mapping table for desired images by region.
    • For more information about Mappings, see the Mappings topic.
  • Resources (Optional)
    The detailed information of resources, including configurations and dependencies.
    • For more information about Resources, see the Resources topic.
  • Outputs (Optional)
    The outputs that are used to provide useful information such as resource properties. You can use API to obtain this information.
    • For more information about Outputs, see the Outputs topic.

Parameters

The parameters you can specify when creating a resource stack.
  • When you create a stack template, you can use parameters to improve the flexibility and reusability of the stack template.
  • When you create a resource stack, you can specify parameter values as needed.

Syntax

Each parameter consists of a name and properties.
  • The parameter name can only contain letters and digits and must be unique in the template.
  • You can use the Label field to define user-friendly parameter names.
The properties of Parameters are as follows.
Property Description Required Example
Type The parameter type. Options:
  • String
  • Number (An integer or floating-point number)
  • CommaDelimitedList (List<String> in Java equivalently)
  • Boolean
Yes "Type": "String"
Label The alias of the parameter. When forms are previewed or generated using templates, labels can be mapped to parameter names. No "Label": "The password of the VM instance"
Description The string that describes the parameter. No "Description": "The login password of the VM instance"
NoEcho Specifies whether to mask a parameter value as asterisks (*****). If you set this property to true, CloudFormation returns the parameter value masked as asterisks (*****). No "NoEcho": true
Note: This property cannot be configured currently.
DefaultValue The default value of the parameter. No "DefaultValue": "password"
CloudFormation also provides some pseudo parameters.
  • Pseudo parameters are parameters that are predefined by CloudFormation. They can be referenced directly. You do not need to declare them in Parameters. (You are actually not allowed to declare them.)
  • The values of the pseudo parameters are determined when CloudFormation is running.
Supported pseudo parameters are as follows.
Pseudo Parameter Name Description
ZStack::StackName The name of the current resource stack
ZStack::StackUuid The UUID of the current resource stack
ZStack::AccountUuid The AccountUuid of the current resource stack
ZStack::AccountName The AccountName of the current resource stack

Example

The following example shows the Parameters syntax.
"Parameters" : {
  "username" : {
    "Label": "Login name",
    "Description" : "Login name",
    "DefaultValue": "root",
    "Type" : "String"
  },
  "password" : {
    "Label": "Password",
    "NoEcho" : "true",
    "Description" : "Login password",
    "Type" : "String",
  }
}
In this example, two parameters are declared in Parameters.
  • username
    • A string type parameter with a default value of root.
    • The username must contain 2 to 12 characters.
    Note: The default value of username must also meet the length and valid values requirements.
  • password
    • A string type parameter with no default value.
    • If you set NoEcho to true, CloudFormation returns the parameter value masked as asterisks (*****).
      Note: The NoEcho property cannot be configured currently.
    • The password must contain 6 to 41 characters.
    • The password can contain uppercase/lowercase letters and digits.

Resources

The detailed information of resources, including configurations and dependencies.
  • Resources can reference Parameters, Mappings, and Functions.
  • Resources can be referenced by other Resources and Outputs.

Syntax

Each resource consists of a logical UUID and a description.
  • All resource descriptions are enclosed in braces { }.
  • Multiple resources are separated with commas ,.
The key fields of Resources are as follows.
Key Field Description Required Example
Type The type of the resource that is being declared. Options:
  • Resource
  • Action
Yes
  • "Type": "ZStack::Resource::VmInstance"
  • "Type": "ZStack::Action::AddIpRange"
  • For more information, see Type
Properties The resource properties that specify parameters for resource creation. Yes For more information, see Properties
DependsOn Specifies that the creation of a specific resource follows another. No
  • "DependsOn": [{"Ref": "WebServer1"}]
  • For more information, see DependsOn
DeletionPolicy
  • Specifies whether to retain a resource after its stack is deleted. Options:
    • Retain
    • Delete
  • If this field is set to Retain, a specific resource and its dependent resource will be retained. (The system automatically retains the dependent resource.)
  • The default value is Delete.
No
Description The string that describes the resource. No
  • "Description" : "attach ip range to l3 network"

Example

The following example shows the Parameters syntax.
"Resources" : {
    "UUID-1" : {
        "Description" : "The resource description",
        "Type" : "The resource type",
        "Properties" : {
            The resource properties
        }
    },
    "UUID-2" : {
        "Description" : "The resource description"
        "Type" : "The resource type",
        "Properties" : {
            The resource properties
        },
        "DependsOn":"The dependent resource. Take UUID-1 for example. Note that this dependent resource should be contained in the context.",
        "DeletionPolicy":"The deletion policy"
    }
}
In this example, two resources are declared in Resources. The description of key fields are as follows:
  • Resource UUID
    • UUID-1 and UUID-2 are the resource UUIDs. Both of them are variables.
    • You can use the resource UUID to reference the resource in other parts of the template.
    • The resource UUID is unique in a template.
  • Type
    • The type of the resource that is being declared, including the Resource type and Action type.
    • For example, "Type": "ZStack::Resource::VmInstance" indicates that the resource is a VM instance. "Type": "ZStack::Action::AddIpRange" indicates the IP range to be added.
    • For more information about the resource types supported by CloudFormation, see the Resource Index topic.
  • Properties
    • The resource properties that specify parameters for resource creation.
    • The following example shows the Properties syntax.
      "Resources" : {    
          "InstanceOffering" : {
              "Type" : "ZStack::InstanceOffering",
              "Properties" : {
                  "cpuNum" : "1",
                  "cpuSpeed" : "1",
                  "memorySize" : "1073741824",
                  "name" : "instance-offering",
                  "type" : "UserVm",
                  "sortKey": 0,
                  "allocatorStrategy": "LeastVmPreferredHostAllocatorStrategy"       
              }
          }
      }
    • The rules of defining resource property values are as follows:
      • Property values can be text strings, string lists, boolean values, references, or return values of functions.
      • Text strings are enclosed with double quotation marks "".
      • String lists are enclosed with brackets [].
      • Return values of intrinsic functions and references are enclosed with braces {}.
      • The preceding rules also apply when property values are the combinations of text strings, string lists, references, and return values of functions.
      • The following example shows how to declare different types of properties.
        "Properties" : {
            "String" : "string",
            "LiteralList" : [ "value1", "value2" ],
            "Boolean" : "true"
            "ReferenceForOneValue" :  { "Ref" : "ResourceID" } ,
            "FunctionResultWithFunctionParams" : {
                "Fn::Join" : [ "%", [ "Key=", { "Ref" : "SomeParameter" } ] ] }
        }
    • If the resource does not require you to declare a property, this part can be skipped.
  • DependsOn
    • With the DependsOn attribute, you can specify that the creation of a specific resource follows another.
    • When you add a DependsOn attribute to a resource, the resource is created only after the creation of the resource specified in the DependsOn attribute.
    • The following example shows the DependsOn syntax.
      {
          "ZStackTemplateFormatVersion" : "2018-06-18",
          "Resources" : {
              "WebServer": {
                  "Type": "ZStack::Resource::VmInstance",
                  "DependsOn": "DatabseServer"
              },
              "DatabseServer": {
                  "Type": "ZStack::Resource::VmInstance",
                  "Properties": {
                      "name": {"Fn::Join":["-",[{"Ref":"ZStack::StackName"},"VM"]]},          
                      "instanceOfferingUuid": {"Ref":"InstanceOfferingUuid"},          
                      "imageUuid":{"Ref":"ImageUuid"},
                      "l3NetworkUuids":[{"Ref":"PrivateNetworkUuid"}],
                      "dataDiskOfferingUuids":[{"Ref":"DiskOfferingUuid"}],
      	         "hostUuid":{"Ref":"HostUuid"}
                  }
              }
          }
      }

      This example indicates that WebServer is created only after DatabaseServer is created.

  • DeletionPolicy
    • DeletionPolicy specifies whether to retain a resource after its stack is deleted.
    • DeletionPolicy has two options: Retain and Delete.
      • Delete: The default value, which indicates that after a resource stack is deleted, all resources in the stack will be deleted.
      • Retain: If the DeletionPolicy attribute is set to Retain, the specific resource will be retained after its stack is deleted. Furthermore, the dependent resource of the resource will also be retained. (The system automatically retains the dependent resource.)
        The following example shows that the VM instance is retained after the template-based resource stack is deleted.
        "Resources" : {
            "VMInstance" : {
                "Type" : "ZStack::Resource::VmInstance",
                "Properties": {
                    "name": {"Fn::Join":["-",[{"Ref":"ZStack::StackName"},"VM"]]},          
                    "instanceOfferingUuid": {"Ref":"InstanceOfferingUuid"},          
                    "imageUuid":{"Ref":"ImageUuid"},
                    "l3NetworkUuids":[{"Ref":"PrivateNetworkUuid"}],
                    "dataDiskOfferingUuids":[{"Ref":"DiskOfferingUuid"}],
        	     "hostUuid":{"Ref":"HostUuid"}
            },
            "DeletionPolicy" : "Retain"
          }
        }






Download

Already filled the basic info? Click here.

Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

An email with a verification code will be sent to you. Make sure the address you provided is valid and correct.

Download

Not filled the basic info yet? Click here.

Invalid email address or mobile number.

Email Us

contact@zstack.io
ZStack certification training consulting
Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

Email Us

contact@zstack.io

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder. After receiving the email, click the URL to download the documentation.

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder.
Or click on the URL below. (For Internet Explorer, right-click the URL and save it.)

Thank you for using ZStack products and services.

Submit successfully.

We'll connect soon.

Thank you for choosing ZStack products and services.

Back to Top