Defining the structure of Managed services template

The Managed services supported Terraform template is made up of datatypes, modules, metadata files and .tf files. This section provides you with the structure of the template so that you can build a new Terraform template from scratch.

Using the locally installed Template Designer, you can create templates in a user friendly way, however, it does not support some of the content types and is limited in scope. For more information about the locally installed Template Designer, see Managed services local Template Designer.

The following block depicts the structure of a template:

- License
- README.md
- main.tf
- variables.tf
- output.tf
- camtemplate.json
- camvariables.json
- datatypes/
  - datatype.json
  - ...
- modules
  - moduleA/
    - LICENSE
    - main.tf
    - output.tf
    - scripts
      - script.sh
    - variables.tf
  - moduleB/
    - ...
- examples/
  - exampleA
    - main.tf
  - exampleB
    - main.tf
  - ...
- scripts
  - script.sh
  - ...

The following table describes the different components of a template structure:

Component	Description
cam_template_structure	This is the repository name or root folder of the template.
License	The license under which the template is made available.
README.md	This file contains a description of the template, expected usage, and variables required.
main.tf	The main entry point for the template.
variables.tf	Provides information and defaults of variables that are needed to execute the template.
output.tf	Provides information on important variables, which can be queried after deployment through Terraform and Managed services user interface.
camtemplate.json	A metadata file which provides information such as the short/long name, description, version and more for presentation in the Managed services Catalog.
camvariables.json	A metadata file describing how each variable is presented in the Managed services user interface. This creates an improved deployment experience with features such as: optional drop-downs, secure (masking), regex validation and descriptions.
datatypes directory	Directory contains json files to be loaded into Managed services Shared Parameters.
datatypes/datatype.json	Contains information about the Data Types which can be used by templates to facilitate dynamic binding at deployment time.
modules directory	This is optional and only used if nested Modules are included. Nested Modules allow you to break up complexity to provide more flexible configuration options.
modules/module	Directory for a specific nested Module. It must at least include a main.tf, output.tf and variables.tf.
modules/moduleA/main.tf / variables.tf / output.tf	Files are scoped to Module execution only but have the same definition as the preceding definition.
modules/moduleA/scripts directory	Directory contains scripts or files used by the Module.
scripts	Directory contains scripts or files used by the template.
examples	Directory containing an example(s) of additional configurations.

Modules

Modules are Terraform files in a folder. Even the working directory of a Terraform configuration where you run "Terraform apply" is considered as a root Module.

The Terraform Module is achieved by abstracting common configuration as building blocks, which can be reused by you and the rest of the organization. The Terraform configuration is by itself a Module sourcing other common building blocks (Modules) all with the right level of abstraction to enable reuse. The Terraform Modules provide developers with a structure to define reusable building blocks. You can define reusable configuration to meet industry guidelines and/or certify against your organization’s unique standards. Large organizations can take advantage of structuring Terraform Modules by specialties like networking, security or by team ownership. When developing Terraform, use the Modules approach.

The following block depicts the structure of a module:

- modules
  - moduleA/
    - LICENSE
    - main.tf
    - output.tf
    - scripts
      - script.sh
    - variables.tf
  - moduleB/
    - ...

Tags module

For more information about system tags and user tags, see Tags module.

Managed services JSON files

You can create camtemplate.json and camvariables.json files for your template. It is not mandatory to have them in the template but its presence simplifies the deployment process.

camtemplate.json

The camtemplate.json file contains template metadata. It defines the function and features of the template.

In the Managed services, the template Overview page includes the details defined in this JSON file.

For example, you can go through this camtemplate.json file to understand its structure at - Sample camtemplate.json .

camvariables.json

The camvariables.json file contains metadata that is used in Managed services to augment the support for variables in Terraform. Metadata adds additional parameters for existing variables that are understood and handled by Managed services. Here, define template_input_params for all the variables in main.tf file.

When you deploy the template in the Managed services user interface, all these defined variables are displayed. After you enter the values in the user interface, they are passed on to a JSON file which is in turn sent for execution to Terraform. Terraform matches these parameters with the variables in the .tf file.

The structure of camvariables.json file is as follows:

 {
 "terraform_version": "~> 0.11.0",
 "input_datatypes": [{"name": "namespacename", "label": "Formatted Name"},],
 "output_datatypes": [{""},],
 "input_groups":[{},],
 "output_groups":[{},],
 "template_input_params": [{},],
 "template_output_params":[{},]
 }

Managed services variables structure to deploy content runtime:

  {
  "output_datatypes": "content_runtime_chef",
  "template_input_params": [{},],
  "template_output_params":[{},]
  }

Managed services variable structure to consume content runtime in a new deployment:

 {
  "input_namespaces": [{"name": "content_runtime_chef", "label": "Content Runtime: Chef"}],
  "template_input_params": [{},],
  "template_output_params": [{},]
  }

The template_input_params is defined for every variable and the structure is as follows:

 "template_input_params": [{
    "name": "The name of the service parameter",
    "label": "The label to be displayed in the user interface for this parameter",
    "description": "A description for this parameter",
    "type": "The type of parameter. For example, "list, string, map",
    "default": "The default value of the parameter",
    "hidden": "Specify if the parameter is not displayed in the user interface. The value must be true or false",
    "immutable": "Specify if the parameter is read only. The value must be true or false",
    "immutable_after_create": "Specify if the parameter is read only after create (e.g. cannot be changed during an update or plan/apply). The value must be true or false (default)",
    "required": "Specify if the parameter is required. The value must be true or false",
    "secured": "Specify if the parameter value is shown as ********. The value must be true or false",
    "regex": "Define the regular expression - ^[A-Za-z0-9-]{1,52}$. The value you provide must match this regular expression."
    "group_name": "The group to locate this parameter in when displaying on the UI". For example, "myGroup",
    "options": [  <--- in place of "default" for a list to select from
    {
      "value": "dc1",
      "label": "My Favorite DC",
      "default": "true"
     },
     {
      "value": "dc2",
      "label": "some other DC"
     }
    ]
       },]

The template_output_params is defined for every variable and the structure is as follows:

 "template_output_params":
 [{
    "name": "name of the output variable in the template file", output section from Terraform
    "label": "The label to be displayed in the user interface for this parameter",
    "description": "A description for this parameter",
    "type": "The type of parameter. For example: "list, string, map, url",
    "shortname": The abbreviated name for a value (e.g. URL shortname like "console link" which actually links to https://asdf.com/asdf/asdf.html"
    "hidden": "Specify if the parameter is not displayed in the user interface. The value must be true or false",
    "secured": "Specify if the parameter value is shown as ********. The value must be true or false",
    "return_type": "The type of the parameter that is returned"
    "group_name": "The group to locate this parameter in when displaying on the UI" E.g. "myGroup",
    },]

Datatypes folder

Datatypes are yet another Managed services specific metadata.

Datatypes

Administrator defined connection is required as the templates that are defined in Managed services need access to external systems that are not necessarily backed up by a Managed services instance. The Data Types and Data Objects are two admin constructs that are used to capture these shared configurations.

You must define the datatypes for a template under the datatypes folder or else they get ignored by the import code:

{
   "name": "Name of the datatype",
   "label": "Lable of the datatype",
   "description": "Description of the datatype",
   "attributes": [
    {
      "name": "Name of the attribute",
      "type": "type of the attribute",
      "description": "Description of the attribute",
      "label": "Label of the attribute",
      "required": "Is it a mandatory attribute",
      "secured": "Is it a secured attribute",
      "immutable": "Is it immutable",
      "hidden": "Is it hidden",
      "default": "The default value of the attribute",
      "options": Options of the attribute.
     },
     {
       ...
       ...
     }
    ]
}

For a sample datatype, see GitHub repository External link icon .

For more information about shared parameters, see Shared parameters.

Terraform files

The template can have main.tf and variables.tf terraform files.

main.tf

The main template that gets deployed. It describes all the variables and resource structure that gets deployed on the cloud.

Example:

 module "icam_agent_install_linux" {
 source = "./modules/icam_agent_install"
 ip_address = "${var.ip_address}"
 user = "${var.user}"
 password = "${var.password}"
 private_key = "${var.private_key}"
 icam_agent_location = "${var.icam_agent_location}"
 icam_agent_location_credentials = "${var.icam_agent_location_credentials}"
 icam_agent_source_subdir = "${var.icam_agent_source_subdir}"
 icam_agent_installation_dir = "${var.icam_agent_installation_dir}"
 icam_agent_name = "${var.icam_agent_name}"
 #######
 bastion_host        = "${var.bastion_host}"
 bastion_user        = "${var.bastion_user}"
 bastion_private_key = "${var.bastion_private_key}"
 bastion_port        = "${var.bastion_port}"
 bastion_password    = "${var.bastion_password}"
 #######
 }

variables.tf - Terraform variables are defined in this file.

For example:

 variable "ip_address" { type = "string" description = "IP Address of the host to install the IBM cloud App Management Agent"}
 variable "user" { type = "string" description ="Userid to install the IBM Cloud  App Management Agent"}
 variable "password" { type = "string" descritpion = "password of the installation user."}
 variable "private_key" { type = "string" description = "Private key of the installation user" }

These variables are referenced in camvariables.json file.

Template lifecycle through branches

It is a best practice to use dedicated repository in Git for templates and auxiliary files. Whenever you make a change, create a branch at the repository level and not at the folder level. You can have multiple templates in the same repository and multiple versions of the same template. Whenever changes do not break compatibility with older versions, you can use the same branch and merge the changes. If you have changes that break compatibility, then use a new branch. In Managed services, import the new branch and make it the default. You can run a plan and apply that upgrade instances to the new configuration.

By using the Template Designer, you can manage branches effectively. For the procedure to create a branch for a template from Template Designer, see Creating a template.