Using Template Parameters

For an introduction, see What are Parameters.

Some parameters are predefined and available to all templates. You do not have to explicitly define them. See List of Implicit Template Parameters.

Topics

Basic Syntax

Define template parameters within the parameters node of your template file. For each parameter, specify a type and other optional attributes and constraints. For example:

parameters:
  dbAdminUser:
    label: Database Username
    description: The admin user for the new database
    type: String
    mandatory: true
    sensitive: true
    maxLength: 15
  nodeCount:
    label: Database Nodes
    description: The number of nodes in the database cluster
    type: Number
    default: 1
    minValue: 1
    maxValue: 3

To learn more about configuring parameters, see Creating Template Parameters.

Specify the allowedValues attribute in one of these formats:

Enter a sequence of values. For example: [oc1,oc2]
Enter a single JSON object with key/value pairs. The values are displayed to the user and the GetParam function returns the selected key. For example: {"10.3.6": "WebLogic Server 11g", "12.1.3": "WebLogic Server 12c"}
Enter a sequence of JSON objects, which each object being a key/value pair. The values are displayed to the user and the GetParam function returns the selected key. For example: [{"10.3.6": "WebLogic Server 11g"}, {"12.1.3": "WebLogic Server 12c"}]

Stack Name Parameter

You do not need to explicitly define a parameter for the stack’s name. Retrieve the stack name in your template with the implicit parameter serviceName:

dbSchema: { "Fn::Join": ["-", ["Fn::GetParam": serviceName, DB]] }

However, if you want to define constraints on the stack’s name, such as the number of characters, create a String parameter with the same name in your template:

parameters:
  serviceName:
    label: Name
    type: String
    minLength: 10
    allowedPattern: "^[A-Z]+[A-Z0-9]"

Parameter Groups

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.

Define parameter groups within the parameterGroups node of your template file. This node contains a sequence. Each item in the sequence contains a group’s label and the group’s list of parameters. For example:

parameterGroups:
  - label: Database Configuration
    parameters: [dbVersion,dbComputeShape,dbSid]
  - label: Storage Configuration
    parameters: [storageUser,storagePassword]

Tip:

The parameters sequence can also be expressed with the following syntax:

parameters:
  - storageUser
  - storagePassword

Hidden Parameters

This topic does not apply to Oracle Cloud at Customer.

If you set the visible attribute to false for a parameter, it will not be displayed as an input field in the Oracle Cloud Stack console:

parameters:
  dbSchema:
    ...
    visible: false

CLI and REST API clients can specify values for hidden parameters when creating a stack.

Password Parameters

This parameter type enables users to securely enter a password in the Oracle Cloud Stack console. The password value is not displayed in the browser. The user must also enter the same password value twice in order for it to be accepted.

parameters:
  dbPassword:
    label: Database Password
    type: Password

The name of the confirmation input field is the value of label attribute prefixed with the text “Confirm”. In the example above, the confirmation text field would have the label “Confirm Database Password”.

Unlike other parameter types, the password type is case sensitive by default.

Use the GetParam function to retrieve the password value:

adminPassword: { "Fn::GetParam": dbPassword }

SSH Parameters

This parameter type enables users to enter a Secure Shell (SSH) public key. Oracle Cloud Stack console users can supply the key value as text or as a file, or let Oracle Cloud generate a value dynamically. If the key is generated, users can download it as a file.

parameters:
  sshkey:
    label: SSH Public Key
    type: Ssh

Use the GetParam function to retrieve the user-supplied or generated key value:

vmPublicKey: { "Fn::GetParam": sshkey }

Compute Shape Parameters

This parameter type enables users to select a compute shape. Oracle Cloud defines standard shapes (oc3, oc2m, and so on) that specify the number of Oracle Compute Units (OCPUs) and the amount of memory allocated to a cloud resource.

parameters:
  databaseShape:
    label: Database Compute Shape
    type: ComputeShape
    default: oc3

You can use the allowedValues constraint with the ComputeShape parameter type to limit the Oracle Cloud compute shapes that the user may choose. The Oracle Cloud Stack console will automatically display the number of OCPUs and the amount of RAM for each shape option in your list. If you do not provide an allowedValues constraint, the user can select any standard compute shape.

parameters:
  databaseShape:
    label: Database Compute Shape
    type: ComputeShape
    allowedValues: [ oc3, oc4, oc5, oc6, oc1m, oc2m, oc3m, oc4m ]

Use the GetParam function to retrieve the selected compute shape:

weblogicShape: { "Fn::GetParam": databaseShape }

Tag Parameters

This topic does not apply to Oracle Cloud at Customer.

The parameter types enables users to select one or more existing tags in this cloud account, or to create new tags.

parameters:
  dbTags:
    label: Database Tags
    type: Tag

Each tag can be a simple key, or a key:value pair. Use the GetParam function to retrieve the tags as a sequence of key:value objects. If a tag does not have a specific value, it will be an empty string.

tags: { "Fn::GetParam": dbTags }

Storage Parameters

This parameter type enables users to specify a storage container in Oracle Cloud Infrastructure Object Storage Classic. See About Oracle Storage Cloud Service in Using Oracle Storage Cloud Service.

parameters:
  backupStorage:
    label: Cloud Storage
    type: Storage

Each parameter of this type results in three separate input fields in the Oracle Cloud Stack console:

The URL of the storage container
The name of an Oracle Cloud user that has access to this container
The password for this Oracle Cloud user

Use the GetParam function to retrieve these three input values. The storage parameter’s value is a JSON object. Use a dot notation in order to access the values within this object:

dbBackupContainer: { "Fn::GetParam": backupStorage.cloudStorageContainer }
dbBackupUser: { "Fn::GetParam": backupStorage.cloudStorageUser }
dbBackupPassword: { "Fn::GetParam": backupStorage.cloudStoragePassword }

By default, the labels and descriptions for these three input fields are generated from the template parameter’s label attribute. In the previous example, the label for the first text field would be “Cloud Storage – Backup Storage Container”. Alternatively, you can specify your own label and description for each input field:

parameters:
  backupStorage:
    label: {"cloudStorageContainer": "Backup Storage Container", "cloudStorageUser": "Storage User", "cloudStoragePassword": "Storage Password"}
    description: {"cloudStorageContainer": "Oracle Storage Cloud Service container URL", "cloudStorageUser": "User with access to Oracle Storage Cloud Service", "cloudStoragePassword": "Password for the storage user"}
    type: Storage

When you use the CLI to create a stack from a template that has storage type parameters, enter the parameter value as a JSON object with these three attributes. For example:

-p backupStorage:{"cloudStorageContainer":"value","cloudStorageUser":"value","cloudStoragePassword":"value"}

Region Parameters

The Oracle Cloud Stack console automatically displays a list of available Oracle Cloud regions, such as geographical locations, which will vary depending on the user’s account settings. The default value is "No Preference", in which case Oracle Cloud will automatically select a region. Some Oracle Cloud features like IP networks and IP reservations may not be supported if a resource is not assigned to a specific region.

The Region parameter type displays a single input field in the console:

parameters:
  cloudRegion:
    label: Cloud Region
    type: Region

Use the GetParam function to retrieve the user-selected region:

dbRegion: { "Fn::GetParam": cloudRegion }

Service Parameters

The Service_Type parameter type enables users to select from a list of existing Oracle Cloud service instances. Type is the name of a resource type in Oracle Cloud Stack (see List of Resource Types). For example, if you define a parameter of type Service_dbaas, the user can select from a list of existing Oracle Database Cloud Service deployments in this cloud account:

parameters:
  dbaasService:
    label: Database
    type: Service_dbaas

Use the GetParam function to retrieve the name of the selected service instance:

dbService: { "Fn::GetParam" : dbaasService }