1. Terraform driver Common

1.1. Introduction

This document explains the common functions of the ""Terraform Cloud/EP driver" and "Terraform CLI driver" (Hereinafter written as Terraform Driver).

1.2. Overview

This section explains Terraform and the Terraform driver.

1.2.1. Terraform

Terraform is an Orchestration tool created by HashiCorp for optimizing infrastructures.

It uses infrastructure files coded in HCL (HashiCorp Configuration Language) to generate an Execution plan before executing the construction process.

Terraform Cloud and Terraform Enterprise can also codify Access policies through something called Policy as Code and manage them on the system.

For more information regarding Terraform, see the Terraform product manuals..

1.2.2. Terrform driver

The Terraform driver is an ITA Function that allows users to execute Terraform and fetch execution logs.

The module files used for executions (Plan/Apply) and Policy files used to run PolicyChecks are turned into parts on the ITA system where they can be re-used.

The Terraform Driver can also configure variables within the Module files.

For more information, see "Handling Variables".

図 1.82 ITA system overview

There are 2 types of Terraform drivers.

• Terraform Cloud/EP driver

  Allows users to Create Organizations, Workspaces, execute operations (Plan/PolicyCheck/Apply) to Terraform Cloud and Terraform Enterprises registered to ITA and fetch operation logs.

  For more information, see "Terraform Cloud/EP driver".
• Terraform CLI driver

  Allows users to execute operations (Plan/Apply) to and fetch operation logs from Terraform systems installed on the same environment as ITA.

  For more information, see "Terraform CLI driver".

1.3. Handling Variables

1.3.1. Variable types

In the Terraform driver, users can configure Specific values within Modules from the ITA settings page.

※For more information, see "Terraform Cloud/EP driver -> Substitute value auto registration settings" and "Terraform CLI driver -> Substitute value auto registration settings".

The Variable blocks defined within the Module files can be handled as Variables.

1.3.2. Extracting Variables and registering Specific values,

User can register specific values by extrating variables out from module files uploaded to ITA.

The extracted specific values are registered as specific values in the "Terraform Cloud/EP driver -> Substitute value auto registration settings" and "Terraform CLI driver -> Substitute value auto registration settings" by linking with the Parameter sheets..

In the Terraform Cloud/EP driver, registered values and specific values are registered as "Key" for "Variable name" and "Value" for "Specific value" to the Link Terraform's Workspace.

In the Terraform CLI driver, registered variables and specific values are described and applied as "Key" for the "Variable name" and "Value" for the "Specific value" in the terraform.tfvars file which is generated when execution starts.

1.3.3. Types of variables

Users can configure the type within the variables.

The variables within the Module must follow the HCL (HashiCorp ConfigurationLanguage) variable rules.

The variables handled by ITA are as following.

表 1.117 Variable type

type	Details	Member variable target ※1	Substitute order target ※2	type description example	default description example
string	String type	×	×	string	ABC
number	Number type	×	×	number	123
bool	Boolean type (True or false).	×	×	bool	true
list	Array type.	×	〇	list(string)	["A", "B", "C"]
set	Array type. Asks for unique values. ITA does not check if the specific value is unique or not.	×	〇	set(number)	[1, 2, 3]
tuple	Array type.The user must decide what number is what type in beforehand. The value's input number is decided, meaning that they can be selected from pulldown selections as Member variables.	〇	×	tuple([string, number])	["ABC", 2023]
map	key-value (associative array) type. If a type containing more map types on ITA, the key value cannot be specified from the type information, meaning that the HCL settings must be set to ON if the user is using substitute value auto registration settings. For more information regarding HCL settings, see "Substitute value auto registration settings".	×	×	map(string)	{"test_key" = "test_value"}
object	key-value (associative array) type. in ITA, the key name is handled as Member variables. the key name cannot contain Japanese characters.	〇	×	object({test_key = string})	{"test_key" = "test_value"}
any	A type that fits everything. however, it will be handled the same way as string types on ITA.	×	×	any	ABC
No description	If no type is described, it will be handled the same way as string types on ITA.	×	×		ABC

• ※1 …Member variable target

  If the variable is a key-value type, it will be a key name..

  If the variable type is object, <KEY> = <TYPE>'s <KEY> will be member variable.

  If the variable type is tuple, the variables defined within the tuple will be numbered from [0],[1],[2]… and become Member variables.
  If the Variable type is registered to the Variable nest management menu, they will be numbered from [0],[1],[2]… and become Member variables based on the maximum cycle number.

  For more information regarding variable nests, see "Terraform Cloud/EP driver -> Variable nest management" and "Terraform CLI driver -> Variable nest management".

  • Example: When variable type is object

  1. tf file and registration values

     variable "VAR_hoge" {
         type = object({
           NAME = string,
           IP = string
         })
         default = {
           “NAME” = “machine_01”,
           “IP” = “127.0.0.1”
        }
     }
     

  2. Substitute value example(Substitute value auto registration settings)

     Item number	Variable name	Member variable	Substitute order	Parameter sheet input value
     1	VAR_hoge	NAME	No input	my_machine
     2	VAR_hoge	IP	No input	192.168.100.1

  3. Value sent to Terraform

     {
         NAME = "my_machine"
         IP = "192.168.100.1"
     }
     

  
  

  • Example: When Variable type is tuple

  1. tf file and registration value

     variable "VAR_hoge" {
         type = tuple([string,number])
         default = ["abc",2023]
     }
     

  2. Substitute value example(Substitute value auto registration settings)

     Item number	Variable name	Member variable	Substitute order	Parameter sheet input value
     1	VAR_hoge	[0]	No input	def
     2	VAR_hoge	[1]	No input	2024

  3. Value sent to Terraform

     ["def", 2024]
     

  
  

  • Example: When variable type is nest management target

  1. tf file and registration value

     variable "VAR_hoge"{
         type = list(set(string))
         default = [
           ["aaa","bbb"]
           ["ccc","ddd"]
         ]
     }
     

  2. Substitute value example(Substitute value auto registration settings)

     Item number	Variable name	Member variable	Substitute order	Parameter sheet input value
     1	VAR_hoge	[0]	1	AAA
     2	VAR_hoge	[0]	2	BBB
     3	VAR_hoge	[1]	1	CCC
     4	VAR_hoge	[1]	2	DDD

  3. Value sent to Terraform

     [
        ["AAA", "BBB"],
        ["CCC", "DDD"]
     ]
     

• ※2 …Substitute order target

  The substitute order is the order of which specific values are set to variables (starting from top).

  If the variable type (or the type for the lowest variable in a hierarchy configuration) is "list" or "set", they can be configured in the "Terraform Cloud/EP driver -> Substitute value auto registration settings" and "Terraform CLI driver -> Substitute value auto registration settings menus.

  • Example: When Variable type is list

  1. tf file and registration value

     variable "VAR_hoge" {
        type = list(string)
     }
     

  2. Substitute value example(Substitute value auto registration settings)

     Item number	Variable name	Member variable	Substitute order	Parameter sheet input value
     1	VAR_hoge	Input not required	1	ABC
     2	VAR_hoge	Input not required	2	DEF

  3. Value sent to Terraform

     ["ABC","DEF"]
     

  
  

  • Example: When the Hierarchy variable's lowest variable type is "set"

  1. tf file and registration value

     variable "VAR_hoge" {
        type = object({
           key = set(number)
        })
     }
     

  2. Substitute value example(Substitute value auto registration settings)

     Item number	Variable name	Member variable	Substitute order	Parameter sheet input value
     1	VAR_hoge	key	1	1
     2	VAR_hoge	key	2	2

  3. Value sent to Terraform

     {
         key = [1,2]
     }
     

1.4. Describing construction code

This section explains how to write Modules and Policies for the Terraform driver.

The Policy function is only activate for the Terraform Cloud/EP driver.

1.4.1. Describing Module

Module files are written in HasiCorp's original language, HCL (HashiCorp ConfigurationLanguage).

For more information, see the Terraform product manuals.

1.4.2. Describing Policy

Policy files are written in HasiCorp's original language, Sentinel language.

For more information, see the Terraform product manuals.

1.5. Appendix

1.5.1. Module file "Variable block" input/register example

This section contains substitute value auto registration settings registration examples and "Variable block" description examples for each variable type.

1. Simple pattern
   1. string type

      

   2. number type

      

   3. bool type

      

   4. list type

      

   5. set type

      

   6. tuple type

      

   7. map type

      

   8. object type

      

   9. any type

      

   10. No type description

       

2. Complicated patterns
   1. list type within list type

      

   2. object type within list type

      

   3. object type within list type within object type

      

3. Special pattern
   1. map type within list type

      

1.5.2. Variable nest management flow example

This section contains examples on operating the Variable nest management menu.

1. Increasing maximum number of cycles

   

2. Decreasing maximum number of cycles