This doc is good for Terraform Operator release v0.10.0 and covers the resource apiVersion: v1alpha2

The following is a list of configurable parameters of the Terraform CRD. A brief description about each parameter will be defined here. Fore more in-depth details about the features, see Core Concepts.

Terraform v1alpha2 tf.isaaguilar.com

KindGroupVersion
Terraformtf.isaaguilar.comv1alpha2
FieldDescription
apiVersion
string		 APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kind
string		 Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadata
k8s.io/apimachinery/pkg/apis/meta/v1.ObjectMeta
spec
TerraformSpec
status
TerraformStatus

Copy TerraformSpec v1alpha2 tf.isaaguilar.com

FieldDescription
backend
string		 Backend is mandatory terraform backend configuration. Must use a valid terraform backend block. For more information see https://www.terraform.io/language/settings/backends/configuration

Example usage of the kubernetes cluster as a backend:

  terraform {
   backend "kubernetes" {
    secret_suffix     = "all-task-types"
    namespace         = "default"
    in_cluster_config = true
   }
  }

Example of a remote backend:

  terraform {
   backend "remote" {
    organization = "example_corp"
    workspaces {
      name = "my-app-prod"
    }
   }
  }

Usage of the kubernetes backend is only available as of terraform v0.13+.

credentials
array[Credentials]		 Credentials is an array of credentials generally used for Terraform providers
ignoreDelete
boolean		 IgnoreDelete will bypass the finalization process and remove the tf resource without running any delete jobs.
images
Images		 Images describes the container images used by task classes.
keepCompletedPods
boolean		 KeepCompletedPods when true will keep completed pods. Default is false and completed pods are removed.
keepLatestPodsOnly
boolean		 KeepLatestPodsOnly when true will keep only the pods that match the current generation of the terraform k8s-resource. This overrides the behavior of `keepCompletedPods`.
outputsSecret
string		 OutputsSecret will create a secret with the outputs from the module. All outputs from the module will be written to the secret unless the user defines "outputsToInclude" or "outputsToOmit".
outputsToInclude
array[string]		 OutputsToInclude is a whitelist of outputs to write when writing the outputs to kubernetes.
outputsToOmit
array[string]		 OutputsToOmit is a blacklist of outputs to omit when writing the outputs to kubernetes.
persistentVolumeSize
k8s.io/apimachinery/pkg/api/resource.Quantity		 PersistentVolumeSize define the size of the disk used to store terraform run data. If not defined, a default of "2Gi" is used.
plugins
object		 Plugins are tasks that run during a workflow but are not part of the main workflow. Plugins can be treated as just another task, however, plugins do not have completion or failure detection.

Example definition of a plugin:

  plugins:
    monitor:
      image: ghcr.io/galleybytes/monitor:latest
      imagePullPolicy: IfNotPresent
      when: After
      task: setup

The above plugin task will run after the setup task has completed.

Alternatively, a plugin can be triggered to start at the same time of another task. For example:

  plugins:
    monitor:
      image: ghcr.io/galleybytes/monitor:latest
      imagePullPolicy: IfNotPresent
      when: At
      task: setup

Each plugin is run once per generation. Plugins that are older than the current generation are automatically reaped.

requireApproval
boolean		 RequireApproval will place a hold after completing a plan that prevents the workflow from continuing. However, the implementation of the hold takes place in the tf.sh script.

(See https://github.com/GalleyBytes/terraform-operator-tasks/blob/master/tf.sh)

Depending on the script that executes during the workflow, this field may be ignored if not implemented by the user properly. To approve a workflow using the official galleybytes implementation, a file needs to be placed on the workflow’s persistent-volume:

  • $TFO_GENERATION_PATH/_approved_<uuid-of-plan-pod> - to approve the workflow

  • $TFO_GENERATION_PATH/_canceled_<uuid-of-plan-pod> - to deny and cancel the workflow

Deleting the plan that is holding will spawn a new plan and a new approval will be required.

scmAuthMethods
array[SCMAuthMethod]		 SCMAuthMethods define multiple SCMs that require tokens/keys
serviceAccount
string		 ServiceAccount use a specific kubernetes ServiceAccount for running the create + destroy pods. If not specified we create a new ServiceAccount per Terraform
setup
Setup		 Setup is configuration generally used once in the setup task
sshTunnel
ProxyOpts		 SSHTunnel can be defined for pulling from scm sources that cannot be accessed by the network the operator/runner runs in. An example is enterprise-Github servers running on a private network.
taskOptions
array[TaskOption]		 TaskOptions are a list of configuration options to be injected into task pods.
terraformModule
Module		 TerraformModule is used to configure the source of the terraform module.
terraformVersion
string		 TerraformVersion is the version of terraform which is used to run the module. The terraform version is used as the tag of the terraform image regardless if images.terraform.image is defined with a tag. In that case, the tag is stripped and replace with this value.
writeOutputsToStatus
boolean		 WriteOutputsToStatus will add the outputs from the module to the status of the Terraform CustomResource.

Copy TerraformStatus v1alpha2 tf.isaaguilar.com

FieldDescription
lastCompletedGeneration
integer
outputs
object
phase
string
plugins
array[string]		 Plugins is a list of plugins that have been executed by the controller. Will get refreshed each generation.
podNamePrefix
string		 PodNamePrefix is used to identify this installation of the resource. For very long resource names, like those greater than 220 characters, the prefix ensures resource uniqueness for runners and other resources used by the runner. Another case for the pod name prefix is when rapidly deleteing a resource and recreating it, the chance of recycling existing resources is reduced to virtually nil.
stage
Stage
stages
array[Stage]

Copy Credentials v1alpha2 tf.isaaguilar.com

FieldDescription
aws
AWSCredentials		 AWSCredentials contains the different methods to load AWS credentials for the Terraform AWS Provider. If using AWS_ACCESS_KEY_ID and/or environment variables for credentials, use fromEnvs.
secretNameRef
SecretNameRef		 SecretNameRef will load environment variables into the terraform runner from a kubernetes secret
serviceAccountAnnotations
object		 ServiceAccountAnnotations allows the service account to be annotated with cloud IAM roles such as Workload Identity on GCP

Copy Images v1alpha2 tf.isaaguilar.com

FieldDescription
script
ImageConfig		 Script task type container image definition
setup
ImageConfig		 Setup task type container image definition
terraform
ImageConfig		 Terraform task type container image definition

Copy Module v1alpha2 tf.isaaguilar.com

FieldDescription
configMapSeclector
ConfigMapSelector		 ConfigMapSelector is an option that points to an existing configmap on the executing cluster. The configmap is expected to contains has the terraform module (ie keys ending with .tf). The configmap would need to live in the same namespace as the tfo resource.

The configmap is mounted as a volume and put into the TFO_MAIN_MODULE path by the setup task.

If a key is defined, the value is used as the module else the entirety of the data objects will be loaded as files.

inline
string		 Inline used to define an entire terraform module inline and then mounted in the TFO_MAIN_MODULE path.
source
string		 Source accepts a subset of the terraform "Module Source" ways of defining a module. Terraform Operator prefers modules that are defined in a git repo as opposed to other scm types. Refer to https://www.terraform.io/language/modules/sources#module-sources for more details.
version
string		 Version to select from a terraform registry. For version to be used, source must be defined. Refer to https://www.terraform.io/language/modules/sources#module-sources for more details

Copy Plugin v1alpha2 tf.isaaguilar.com

FieldDescription
image
string		 The container image from the registry; tags must be omitted
imagePullPolicy
string		 Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
task
string		 Task is the second part of a two-part selector of when the plugin gets run in the workflow. This should correspond to one of the tfo task names.
when
string		 When is a keyword of a two-part selector of when the plugin gets run in the workflow. The value must be one of

  • At to run at the same time as the defined task

  • After to run after the defined task has completed.

Copy ProxyOpts v1alpha2 tf.isaaguilar.com

FieldDescription
host
string
sshKeySecretRef
SSHKeySecretRef
user
string

Copy SCMAuthMethod v1alpha2 tf.isaaguilar.com

FieldDescription
git
GitSCM		 Git configuration options for auth methods of git
host
string

Copy Setup v1alpha2 tf.isaaguilar.com

FieldDescription
cleanupDisk
boolean		 CleanupDisk will clear out previous terraform run data from the persistent volume.
resourceDownloads
array[ResourceDownload]		 ResourceDownloads defines other files to download into the module directory that can be used by the terraform workflow runners. The `tfvar` type will also be fetched by the `exportRepo` option (if defined) to aggregate the set of tfvars to save to an scm system.

Copy TaskOption v1alpha2 tf.isaaguilar.com

FieldDescription
annotations
object		 Annotaitons extra annotaitons to add the task pods
env
array[k8s.io/api/core/v1.EnvVar]		 List of environment variables to set in the task pods.
envFrom
array[k8s.io/api/core/v1.EnvFromSource]		 List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
for
array[string]		 For is a list of tasks these options will get applied to.
labels
object		 Labels extra labels to add task pods.
policyRules
array[k8s.io/api/rbac/v1.PolicyRule]		 RunnerRules are RBAC rules that will be added to all runner pods.
resources
k8s.io/api/core/v1.ResourceRequirements		 Compute Resources required by the task pods.
restartPolicy
string		 RestartPolicy describes how the task should be restarted. Only one of the following restart policies may be specified. 
  const (
    RestartPolicyAlways    RestartPolicy = "Always"
    RestartPolicyOnFailure RestartPolicy = "OnFailure"
    RestartPolicyNever     RestartPolicy = "Never"
  )

If no policy is specified, the restart policy is set to “Never”.

script
StageScript		 Script is used to configure the source of the task's executable script.

Copy Stage v1alpha2 tf.isaaguilar.com

FieldDescription
generation
integer		 Generation is the generation of the resource when the task got started.
interruptible
boolean		 Interruptible is set to false when the pod should not be terminated such as when doing a terraform apply.
message
string		 Message stores the last message displayed in the logs. It is stored and checked by the controller to reduce the noise in the logs by only displying the message once.
podName
string		 PodName is the pod assigned to execute the stage.
podType
string		 TaskType is which task is currently running.
podUID
string		 PodUID is the pod uid of the pod assigned to execute the stage.
reason
string		 Reason is a message of what is happening with the pod. The controller uses this field when certain reasons occur to make scheduling decisions.
startTime
k8s.io/apimachinery/pkg/apis/meta/v1.Time		 StartTime is when the task got created by the controller, not when a pod got started.
state
string		 State is the phase of the task pod.
stopTime
k8s.io/apimachinery/pkg/apis/meta/v1.Time		 StopTime is when the task went into a stopped phase.

Copy AWSCredentials v1alpha2 tf.isaaguilar.com

FieldDescription
irsa
string		 IRSA requires the irsa role-arn as the string input. This will create a serice account named tf-. In order for the pod to be able to use this role, the "Trusted Entity" of the IAM role must allow this serice account name and namespace.

Using a TrustEntity policy that includes “StringEquals” setting it as the serivce account name is the most secure way to use IRSA.

However, for a reusable policy consider “StringLike” with a few wildcards to make the irsa role usable by pods created by terraform-operator. The example below is pretty liberal, but will work for any pod created by the terraform-operator.

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Federated": "${OIDC_ARN}"
        },
        "Action": "sts:AssumeRoleWithWebIdentity",
        "Condition": {
          "StringLike": {
            "${OIDC_URL}:sub": "system:serviceaccount:*:tf-*"
          }
        }
      }
    ]
  }

This option is just a specialized version of Credentials.ServiceAccountAnnotations and will be a candidate of removal in the future.

kiam
string		 KIAM requires the kiam role-name as the string input. This will add the correct annotation to the terraform execution pod

This option is just a specialized version of Credentials.ServiceAccountAnnotations and will be a candidate of removal in the future.

Copy SecretNameRef v1alpha2 tf.isaaguilar.com

FieldDescription
key
string		 Key of the secret
name
string		 Name of the secret
namespace
string		 Namespace of the secret; Defaults to namespace of the tf resource

Copy ImageConfig v1alpha2 tf.isaaguilar.com

FieldDescription
image
string		 The container image from the registry; tags must be omitted
imagePullPolicy
string		 Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images

Copy ConfigMapSelector v1alpha2 tf.isaaguilar.com

FieldDescription
key
string
name
string

Copy SSHKeySecretRef v1alpha2 tf.isaaguilar.com

FieldDescription
key
string		 Key in the secret ref. Default to `id_rsa`
name
string		 Name the secret name that has the SSH key
namespace
string		 Namespace of the secret; Default is the namespace of the terraform resource

Copy GitSCM v1alpha2 tf.isaaguilar.com

FieldDescription
https
GitHTTPS
ssh
GitSSH

Copy ResourceDownload v1alpha2 tf.isaaguilar.com

FieldDescription
address
string		 Address defines the source address resources to fetch.
path
string		 Path will download the resources into this path which is relative to the main module directory.
useAsVar
boolean		 UseAsVar will add the file as a tfvar via the -var-file flag of the terraform plan command. The downloaded resource must not be a directory.

Copy StageScript v1alpha2 tf.isaaguilar.com

FieldDescription
configMapSelector
ConfigMapSelector		 ConfigMapSelector reads a in a script from a configmap name+key
inline
string		 Inline is used to write the entire task execution script in the tfo resource.
source
string		 Source is an http source that the task container will fetch and then execute.

Copy GitHTTPS v1alpha2 tf.isaaguilar.com

FieldDescription
requireProxy
boolean
tokenSecretRef
TokenSecretRef

Copy GitSSH v1alpha2 tf.isaaguilar.com

FieldDescription
requireProxy
boolean
sshKeySecretRef
SSHKeySecretRef

Copy TokenSecretRef v1alpha2 tf.isaaguilar.com

FieldDescription
key
string		 Key in the secret ref. Default to `token`
name
string		 Name the secret name that has the token or password
namespace
string		 Namespace of the secret; Default is the namespace of the terraform resource