Armory Docs – Get Started with Terraform Integration

Plugins: Enable the Terraform Integration Stage in Armory Continuous Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Overview of enabling Terraform Integration

Enabling the Terraform Integration stage consists of these steps:

Configure Armory CD
Enable Terraform Integration
Apply the update

Compatibility

Spinnaker Version	Terraform Integration Service Version	Terraform Integration Plugin Version
1.30.x	2.30	0.0.2
1.29.x	2.28	0.0.1
1.28.x	2.28	0.0.1

Before you begin

You have read the Terraform Integration Overview.
You are running Armory Continuous Deployment.
You manage your instance using the Armory Operator.

Terraform Integration is a built-in feature of Armory CD.

If you are running open source Spinnaker, see the Terraform Integration Overview for installation paths based on whether you are using Halyard or the Spinnaker Operator.

Terraform Integration requirements

Basic auth credentials for the Git repository where your store your Terraform scripts. The Terraform Integration plugin needs access to credentials to download directories that house your Terraform templates.
- You can configure your Git repo with any of the following:
  - A Personal Access Token (potentially associated with a service account).
  - SSH protocol in the form of an SSH key or an SSH key file
  - Basic auth in the form of a user and password, or a user-password file
A source for Terraform Input Variable files (tfvar) or a backend config. You must have a separate artifact provider that can pull your tfvar file(s). The Terraform Integration plugin supports the following artifact providers for tfvar files and backend configs:
- GitHub
- BitBucket
- HTTP artifact
A dedicated external Redis instance
- Armory requires configuring a dedicated external Redis instance for production usage of the Terraform Integration plugin. This is to ensure that you do not encounter scaling or stability issues in production.

Configure Armory CD

Configure Redis

Terraform Integration uses Redis to store Terraform logs and plans.

You can only configure the Terraform Integration feature to use a password with the default Redis user.

Configure Redis settings in your Armory CD configuration and then apply your changes.

You need to modify spinnaker-kustomize-patches/armory/features/patch-terraformer.yml. Add Redis configuration in the profiles section.

profiles:
 redis:
 baseUrl: "<your-redis-url>"
 password: "<your-redis-password>"

spec:
 spinnakerConfig:
 profiles:
 terraformer:
 redis:
 baseUrl: "<your-redis-url>"
 password: "<your-redis-password>"

Configure your artifact account

The Terraform Integration uses the following artifact accounts:

Git Repo - To fetch the repo housing your main Terraform files.
GitHub, BitBucket or HTTP - Optional. To fetch single files such as var-files or backend config files.

Spinnaker uses the Git Repo Artifact Provider to download the repo containing your main Terraform templates. For more configuration options, see Configure a Git Repo Artifact Account.

You need to modify spinnaker-kustomize-patches/armory/features/patch-terraformer.yml. Configure artifacts in the spec.spinnakerConfig.config.artifacts section.

spec:
 spinnakerConfig:
 config:
 armory:
 terraform:
 enabled: true
 artifacts:
 gitrepo:
 enabled: true
 accounts:
 - name: gitrepo
 username: <username>
 token: <git-token>
 # password:
 # tokenFile: 
 # usernamePasswordFile: 
 # sshPrivateKeyFilePath:
 # sshPrivateKeyPassphrase:
 # sshKnownHostsFilePath: 
 # sshTrustUnknownHosts:

spec:
 spinnakerConfig:
 profiles:
 clouddriver:
 artifacts:
 gitRepo:
 enabled: true
 accounts:
 - name: gitrepo
 token: <your-personal-access-token>

Configure additional repos

You need to modify spinnaker-kustomize-patches/armory/features/patch-terraformer.yml. Configure additional artifacts in the spec.spinnakerConfig.config.artifacts section.

This step is optional.

These optional steps describe how to configure GitHub as an artifact provider for the Terraform Integration.

Spinnaker uses the Github Artifact Provider to download any referenced tfvar files.

Configure your GitHub artifact:

spec:
 spinnakerConfig:
 config:
 artifacts:
 github:
 accounts:
 - name: <github-for-terraform>
 token: <your-github-personal-access-token>
 enabled: true

name: the name for this account; replace github-for-terraform with a unique identifier for the artifact account.
token: GitHub personal access token; this field supports “encrypted” field references.

Spinnaker uses the BitBucket Artifact Provider to download any referenced tfvar files, so it must be configured with the BitBucket token to pull these files.

spec:
 spinnakerConfig:
 config:
 artifacts:
 bitbucket:
 enabled: true
 accounts:
 - name: <bitbucket-for-terraform>
 username: <your-bitbucket-username>
 password: <your-bitbucket-password>

name: the name for this account; replace <bitbucket-for-terraform> with a unique identifier for the artifact account.
username: Your Bitbucket username.
password: Your Bitbucket password; this field supports “encrypted” field references.

Enable Terraform Integration

You need to modify your Kustomization recipe to include patch-terraformer.yml.

patchesStrategicMerge:
 - armory/features/patch-terraformer.yml

Add enabled: true to your terraform section.

spec:
 spinnakerConfig:
 config:
 armory:
 terraform:
 enabled: true

Apply the update

After you finish your Terraform Integration configuration, apply your changes. Confirm that the Terraform Integration service (Terraformer) is deployed with your Armory CD deployment:

kubectl get pods -n <your-spinnaker-namespace>

In the command output, look for a line similar to the following:

spin-terraformer-d4334g795-sv4vz 2/2 Running 0 0d

What’s next

Plugins: Install Terraform Integration in Spinnaker (Spinnaker Operator)

Mon, 01 Jan 0001 00:00:00 +0000

Overview of installing Terraform Integration

In this guide, you use the Kustomize files in the spinnaker-kustomize-patches repo to install the plugin. You do need to update the contents of some files.

Configure Spinnaker
Get the Terraform Integration installation files
Configure the service
Configure the plugin
Deploy Terraform Integration

Compatibility

Spinnaker Version	Terraform Integration Service Version	Terraform Integration Plugin Version
1.30.x	2.30	0.0.2
1.29.x	2.28	0.0.1
1.28.x	2.28	0.0.1

Before you begin

You have read the Terraform Integration Overview.

Spinnaker requirements

You are running open source Spinnaker.
You manage your instance using the Spinnaker Operator and the spinnaker-kustomize-patches repo. If you are using Halyard, see Install Terraform Integration in Spinnaker (Halyard).

Terraform Integration requirements

Basic auth credentials for the Git repository where your store your Terraform scripts. The Terraform Integration plugin needs access to credentials to download directories that house your Terraform templates.
- You can configure your Git repo with any of the following:
  - A Personal Access Token (potentially associated with a service account).
  - SSH protocol in the form of an SSH key or an SSH key file
  - Basic auth in the form of a user and password, or a user-password file
A source for Terraform Input Variable files (tfvar) or a backend config. You must have a separate artifact provider that can pull your tfvar file(s). The Terraform Integration plugin supports the following artifact providers for tfvar files and backend configs:
- GitHub
- BitBucket
- HTTP artifact
A dedicated external Redis instance
- Armory requires configuring a dedicated external Redis instance for production usage of the Terraform Integration plugin. This is to ensure that you do not encounter scaling or stability issues in production.

Configure Spinnaker

Configure Redis

Terraform Integration uses Redis to store Terraform logs and plans.

You can only configure the Terraform Integration feature to use a password with the default Redis user.

Configure Redis settings in your configuration and then apply.

spec:
 spinnakerConfig:
 profiles:
 terraformer:
 redis:
 baseUrl: "redis://spin-redis:6379"
 password: "password"

Configure your artifact account

The Terraform Integration uses the following artifact accounts:

Git Repo - To fetch the repo housing your main Terraform files.
GitHub, BitBucket or HTTP - Optional. To fetch single files such as var-files or backend config files.

Configure the Git Repo artifact

Spinnaker uses the Git Repo Artifact Provider to download the repo containing your main Terraform templates.

Edit your configuration to add the following:

spec:
 spinnakerConfig:
 profiles:
 clouddriver:
 artifacts:
 gitRepo:
 enabled: true
 accounts:
 - name: gitrepo
 token: <your-personal-access-token> # personal access token

For more configuration options, see Configure a Git Repo Artifact Account.

Configure additional repos

This step is optional.

These optional steps describe how to configure GitHub as an artifact provider for the Terraform Integration.

Spinnaker uses the Github Artifact Provider to download any referenced tfvar files.

Configure your GitHub artifact:

spec:
 spinnakerConfig:
 config:
 artifacts:
 github:
 accounts:
 - name: <github-for-terraform>
 token: <your-github-personal-access-token>
 enabled: true

name: the name for this account; replace github-for-terraform with a unique identifier for the artifact account.
token: GitHub personal access token; this field supports “encrypted” field references.

Spinnaker uses the BitBucket Artifact Provider to download any referenced tfvar files, so it must be configured with the BitBucket token to pull these files.

spec:
 spinnakerConfig:
 config:
 artifacts:
 bitbucket:
 enabled: true
 accounts:
 - name: <bitbucket-for-terraform>
 username: <your-bitbucket-username>
 password: <your-bitbucket-password>

name: the name for this account; replace <bitbucket-for-terraform> with a unique identifier for the artifact account.
username: Your Bitbucket username.
password: Your Bitbucket password; this field supports “encrypted” field references.

Get the Terraform Integration installation files

You can find the Terraform Integration service and plugin files in the spinnaker-kustomize-patches repo’s plugins/oss/terraformer directory.

kustomization.yml: Kustomize build file
deployment.yml: spin-terraformer Deployment manifest
service.yml: spin-terraformer Service manifest
terraformer-plugin-config.yml: plugin installation
terraformer.yml: config file
terraformer-local.yml: config file for Named Profiles
spinnaker.yml: Spinnaker service mapping
versions directory: contains version-specific values that Kustomize inserts into the manifest during generation

The spinnaker-kustomize-patches/recipes directory contains the example kustomization-oss-terraformer.yml recipe. You can use that recipe or copy the entries to your recipe. This guide uses the kustomization-oss-terraformer.yml recipe for examples.

Configure the service

Make sure the service version is compatible with your Spinnaker version.

You specify the version in the patchesStrategicMerge section of plugins/oss/terraformer/kustomization.yml. You can find supported versions in the plugins/oss/terraformer/versions directory. For example, if you are running Spinnaker 1.27.x, replace ./versions/v-1.28.yml with ./versions/v-1.27.yml.

patchesStrategicMerge:
 - ./pac-plugin-config.yml
 - ./versions/v-1.28.yml

Configure the plugin

In terraformer-plugin-config.yml, make sure the version number is compatible with your Spinnaker instance.

...
 spinnaker:
 extensibility:
 plugins:
 Armory.Terraformer:
 enabled: true
 version: &pluginversion 0.0.1

For example, if you want to use plugin version 0.0.2, your version value would be &pluginversion 0.0.2.

Deploy Terraform Integration

This step deploys the Terraformer service and installs the plugin. If you want to see the generated manifest before you deploy, execute kubectl kustomize.

Apply the updates to your Kustomization file.

kubectl apply -k <kustomization-directory-path>

What’s next

Plugins: Install Terraform Integration in Spinnaker (Halyard)

Mon, 01 Jan 0001 00:00:00 +0000

Overview of installing Terraform Integration

Installing the Terraform Integration plugin consists of these steps:

Configure Spinnaker: Redis, gitrepo artifact, and optional repos
Install the service: Kubernetes manifests
Install the plugin: Local config files

Compatibility

Spinnaker Version	Terraform Integration Service Version	Terraform Integration Plugin Version
1.30.x	2.30	0.0.2
1.29.x	2.28	0.0.1
1.28.x	2.28	0.0.1

Before you begin

You have read the Terraform Integration Overview.

Spinnaker requirements

You are running open source Spinnaker.
You manage your instance using Halyard. If you are using the Spinnaker Operator, see Install Terraform Integration in Spinnaker (Spinnaker Operator)

Warning

The examples in this guide are for a vanilla Spinnaker installation. You may need to adjust them for your environment.

Terraform Integration requirements

Basic auth credentials for the Git repository where your store your Terraform scripts. The Terraform Integration plugin needs access to credentials to download directories that house your Terraform templates.
- You can configure your Git repo with any of the following:
  - A Personal Access Token (potentially associated with a service account).
  - SSH protocol in the form of an SSH key or an SSH key file
  - Basic auth in the form of a user and password, or a user-password file
A source for Terraform Input Variable files (tfvar) or a backend config. You must have a separate artifact provider that can pull your tfvar file(s). The Terraform Integration plugin supports the following artifact providers for tfvar files and backend configs:
- GitHub
- BitBucket
- HTTP artifact
A dedicated external Redis instance
- Armory requires configuring a dedicated external Redis instance for production usage of the Terraform Integration plugin. This is to ensure that you do not encounter scaling or stability issues in production.

Configure Spinnaker

Configure Redis

Terraform Integration uses Redis to store Terraform logs and plans.

You can only configure the Terraform Integration feature to use a password with the default Redis user.

Configure Redis settings in your configuration and then apply.

spec:
 spinnakerConfig:
 profiles:
 terraformer:
 redis:
 baseUrl: "redis://spin-redis:6379"
 password: "password"

Configure your artifact account

The Terraform Integration uses the following artifact accounts:

Git Repo - To fetch the repo housing your main Terraform files.
GitHub, BitBucket or HTTP - Optional. To fetch single files such as var-files or backend config files.

Configure the Git Repo artifact

Spinnaker uses the Git Repo Artifact Provider to download the repo containing your main Terraform templates.

Edit your configuration to add the following:

spec:
 spinnakerConfig:
 profiles:
 clouddriver:
 artifacts:
 gitRepo:
 enabled: true
 accounts:
 - name: gitrepo
 token: <your-personal-access-token> # personal access token

For more configuration options, see Configure a Git Repo Artifact Account.

Configure additional repos

This step is optional.

These optional steps describe how to configure GitHub as an artifact provider for the Terraform Integration.

Spinnaker uses the Github Artifact Provider to download any referenced tfvar files.

Configure your GitHub artifact:

spec:
 spinnakerConfig:
 config:
 artifacts:
 github:
 accounts:
 - name: <github-for-terraform>
 token: <your-github-personal-access-token>
 enabled: true

name: the name for this account; replace github-for-terraform with a unique identifier for the artifact account.
token: GitHub personal access token; this field supports “encrypted” field references.

Spinnaker uses the BitBucket Artifact Provider to download any referenced tfvar files, so it must be configured with the BitBucket token to pull these files.

spec:
 spinnakerConfig:
 config:
 artifacts:
 bitbucket:
 enabled: true
 accounts:
 - name: <bitbucket-for-terraform>
 username: <your-bitbucket-username>
 password: <your-bitbucket-password>

name: the name for this account; replace <bitbucket-for-terraform> with a unique identifier for the artifact account.
username: Your Bitbucket username.
password: Your Bitbucket password; this field supports “encrypted” field references.

Install the service

Configure Kubernetes permissions

The following manifest creates a ServiceAccount, ClusterRole, and ClusterRoleBinding. Apply the manifest in your spinnaker namespace.

apiVersion: v1
kind: ServiceAccount
metadata:
 name: terraformer-sa
 namespace: spinnaker
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
 name: terraformer-cluster-role
rules:
- apiGroups:
 - extensions
 resources:
 - ingresses
 - ingresses/status
 verbs:
 - get
 - list
 - watch
 - create
 - update
 - patch
 - delete
- apiGroups:
 - networking.k8s.io
 resources:
 - ingresses
 - ingresses/status
 verbs:
 - get
 - list
 - watch
 - create
 - update
 - patch
 - delete
- apiGroups:
 - ""
 resources:
 - pods
 - endpoints
 verbs:
 - get
 - list
 - watch
 - create
 - update
 - patch
 - delete
- apiGroups:
 - ""
 resources:
 - services
 - services/finalizers
 - events
 - configmaps
 - secrets
 - namespaces
 - jobs
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
 - delete
- apiGroups:
 - batch
 resources:
 - jobs
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
- apiGroups:
 - apps
 - extensions
 resources:
 - deployments
 - deployments/finalizers
 - deployments/scale
 - daemonsets
 - replicasets
 - statefulsets
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
 - delete
- apiGroups:
 - monitoring.coreos.com
 resources:
 - servicemonitors
 verbs:
 - get
 - create
- apiGroups:
 - spinnaker.armory.io
 resources:
 - '*'
 - spinnakerservices
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
- apiGroups:
 - admissionregistration.k8s.io
 resources:
 - validatingwebhookconfigurations
 verbs:
 - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
 name: terraformer-cluster-role-binding
roleRef:
 apiGroup: rbac.authorization.k8s.io
 kind: ClusterRole
 name: terraformer-cluster-role
subjects:
- kind: ServiceAccount
 name: terraformer-sa
 namespace: spinnaker

Configure the service

Create a ConfigMap to contain your Terraformer Integration service configuration. Be sure to check the spinnaker.yml entry in the data section to ensure the values match your Spinnaker installation.

apiVersion: v1
kind: ConfigMap
metadata:
 name: spin-terraformer-config
 namespace: spinnaker
data:
 terraformer.yml: |
 clouddriver:
 baseUrl: ${services.clouddriver.baseUrl}
 enabled: true
 executor:
 scrapeLogsIntervalSecs: 5
 workers: 3
 git:
 enabled: false
 redis:
 baseUrl: ${services.redis.baseUrl}
 enabled: ${services.redis.enabled}
 server:
 host: ${services.terraformer.host}
 port: ${services.terraformer.port}
 spectator:
 applicationName: ${spring.application.name}
 webEndpoint:
 enabled: false
 spinnaker:
 extensibility:
 plugins: {}
 plugins-root-path: /opt/terraformer/plugins
 repositories: {}
 strict-plugin-loading: false
 spinnaker.yml: |
 global.spinnaker.timezone: America/Los_Angeles
 services:
 clouddriver:
 baseUrl: http://spin-clouddriver:7002
 enabled: true
 host: 0.0.0.0
 port: 7002
 clouddriverCaching:
 baseUrl: http://spin-clouddriver-caching:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 clouddriverRo:
 baseUrl: http://spin-clouddriver-ro:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 clouddriverRoDeck:
 baseUrl: http://spin-clouddriver-ro-deck:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 clouddriverRw:
 baseUrl: http://spin-clouddriver-rw:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 deck:
 baseUrl: http://localhost:9000
 enabled: true
 host: 0.0.0.0
 port: 9000
 dinghy:
 baseUrl: http://spin-dinghy:8081
 enabled: true
 host: 0.0.0.0
 port: 8081
 echo:
 baseUrl: http://spin-echo:8089
 enabled: true
 host: 0.0.0.0
 port: 8089
 echoScheduler:
 baseUrl: http://spin-echo-scheduler:8089
 enabled: false
 host: 0.0.0.0
 port: 8089
 echoWorker:
 baseUrl: http://spin-echo-worker:8089
 enabled: false
 host: 0.0.0.0
 port: 8089
 fiat:
 baseUrl: http://spin-fiat:7003
 enabled: false
 host: 0.0.0.0
 port: 7003
 front50:
 baseUrl: http://spin-front50:8080
 enabled: true
 host: 0.0.0.0
 port: 8080
 gate:
 baseUrl: http://localhost:8084
 enabled: true
 host: 0.0.0.0
 port: 8084
 igor:
 baseUrl: http://spin-igor:8088
 enabled: false
 host: 0.0.0.0
 port: 8088
 kayenta:
 baseUrl: http://spin-kayenta:8090
 enabled: false
 host: 0.0.0.0
 port: 8090
 monitoringDaemon:
 baseUrl: http://spin-monitoring-daemon:8008
 enabled: false
 host: 0.0.0.0
 port: 8008
 orca:
 baseUrl: http://spin-orca:8083
 enabled: true
 host: 0.0.0.0
 port: 8083
 redis:
 baseUrl: redis://spin-redis:6379
 enabled: true
 host: 0.0.0.0
 port: 6379
 rosco:
 baseUrl: http://spin-rosco:8087
 enabled: true
 host: 0.0.0.0
 port: 8087
 terraformer:
 baseUrl: http://spin-terraformer:7088
 enabled: false
 host: 0.0.0.0
 port: 7088

Deploy the service

Replace <version> with the Terraform Integration service version compatible with your Spinnaker version.

apiVersion: v1
kind: Service
metadata:
 name: spin-terraformer
 labels:
 app: spin
 cluster: spin-terraformer
spec:
 selector:
 app: spin
 cluster: spin-terraformer
 ports:
 - name: http
 port: 7088
 protocol: TCP
 targetPort: 7088
---
apiVersion: apps/v1
kind: Deployment
metadata:
 name: spin-terraformer
 annotations:
 deployment.kubernetes.io/revision: "1"
 moniker.spinnaker.io/application: '"spin"'
 moniker.spinnaker.io/cluster: '"terraformer"'
 labels:
 app: spin
 app.kubernetes.io/managed-by: armory
 app.kubernetes.io/name: terraformer
 app.kubernetes.io/part-of: spinnaker
 app.kubernetes.io/version: <version> # CHANGE
 cluster: spin-terraformer
spec:
 progressDeadlineSeconds: 600
 replicas: 1
 revisionHistoryLimit: 10
 selector:
 matchLabels:
 app: spin
 cluster: spin-terraformer
 strategy:
 rollingUpdate:
 maxSurge: 25%
 maxUnavailable: 25%
 type: RollingUpdate
 template:
 metadata:
 labels:
 app: spin
 app.kubernetes.io/managed-by: armory
 app.kubernetes.io/name: terraformer
 app.kubernetes.io/part-of: spinnaker
 app.kubernetes.io/version: <version> # CHANGE
 cluster: spin-terraformer
 spec:
 affinity: {}
 containers:
 - env:
 - name: SPRING_PROFILES_ACTIVE
 value: local
 image: docker.io/armory/terraformer
 imagePullPolicy: IfNotPresent
 lifecycle: {}
 name: terraformer
 ports:
 - containerPort: 7088
 protocol: TCP
 readinessProbe:
 exec:
 command:
 - wget
 - --no-check-certificate
 - --spider
 - -q
 - http://localhost:7088/health
 failureThreshold: 3
 periodSeconds: 10
 successThreshold: 1
 timeoutSeconds: 1
 resources: {}
 terminationMessagePath: /dev/termination-log
 terminationMessagePolicy: File
 volumeMounts:
 - mountPath: /opt/spinnaker/config
 name: spin-terraformer-config-file
 dnsPolicy: ClusterFirst
 restartPolicy: Always
 schedulerName: default-scheduler
 securityContext:
 fsGroup: 1000
 runAsUser: 1000
 terminationGracePeriodSeconds: 60
 volumes:
 - name: spin-terraformer-config-file
 secret:
 secretName: spin-terraformer-config-file

Apply the ConfigMap and Deployment manifests in your spinnaker namespace.

Install the plugin

A note about installing plugins in Spinnaker

When Halyard adds a plugin to a Spinnaker installation, it adds the plugin repository information to all services, not just the ones the plugin is for. This means that when you restart Spinnaker, each service restarts, downloads the plugin, and checks if an extension exists for that service. Each service restarting is not ideal for large Spinnaker installations due to service restart times. Clouddriver can take an hour or more to restart if you have many accounts configured.

The Terraform plugin extends Deck, Gate, and Orca. To avoid every Spinnaker service restarting and downloading the plugin, do not add the plugin using Halyard. Instead, follow the local config installation method, in which you configure the plugin in each extended service’s local profile.

Replace <version> with the plugin version [that’s compatible with your Spinnaker instance].

Add the following to gate-local.yml:

proxies:
 - id: terraform
 uri: http://spin-terraformer:7088
 methods:
 - GET
services:
 terraformer:
 enabled: true
 baseUrl: http://spin-terraformer:7088
spinnaker:
 extensibility:
 plugins:
 Armory.Terraformer:
 enabled: true
 version: <version>
 repositories:
 terraformer:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 deck-proxy:
 enabled: true
 plugins:
 Armory.Terraformer:
 enabled: true
 version: <version>

Add the following to orca-local.yml:

services:
 terraformer:
 enabled: true
 baseUrl: http://spin-terraformer:7088
spinnaker:
 extensibility:
 plugins:
 Armory.Terraformer:
 enabled: true
 version: <version>
 repositories:
 terraformer:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json

Save your files and apply your changes by running hal deploy apply.

What’s next

Plugins: Configure Terraform Integration Optional Features

Mon, 01 Jan 0001 00:00:00 +0000

Where to configure the Terraform Integration service

Spinnaker (Spinnaker Operator): spinnaker-kustomize-patches/plugins/oss/pipelines-as-code/terraformer.yml; use spinnaker-kustomize-patches/plugins/oss/pipelines-as-code/terraformer-local.yml for Named Profiles
Spinnaker (Halyard): terraformer.yml section of your ConfigMap; create a new terraformer-local.yml section to configure Named Profiles
Armory CD: spinnaker-kustomize-patches/armory/features/patch-terraformer.yml

Cloud provider

Terraform Integration is cloud provider agnostic. Terraform commands execute against the terraform binary. All methods of configuring authentication are supported as per Terraform’s compatibility and capabilities.

You can also configure a Named Profile that grants access to resources such as AWS.

Logging and metrics

If the logging URL is not responsive, Terraform Integration may not process deploys until the URL can be reached.

You can enable logging and metrics for Prometheus by adding the following configuration to the spec.spinnakerConfig.profiles.terraformer.logging.remote block in your SpinnakerService manifest:

Add the following to your terraformer.yml config:

logging:
 remote:
 enabled: true
 endpoint: <TheLoggingEndPoint> # For example, https://debug.armory.io
 version: 1.2.3
 customerId: someCustomer123 # Your Armory Customer ID
 metrics:
 enabled: true
 frequency: <Seconds> # Replace with an integer value for seconds based on how frequently you want metrics to be scraped
 prometheus:
 enabled: true
 commonTags: # The following tags are examples. Use tags that are relevant for your environment
 # env: dev
 # nf_app: exampleApp
 # nf_region: us-west-1

spec:
 spinnakerConfig:
 profiles:
 terraformer:
 logging:
 remote:
 enabled: true
 endpoint: <TheLoggingEndPoint> # For example, https://debug.armory.io
 version: 1.2.3
 customerId: someCustomer123 # Your Armory Customer ID
 metrics:
 enabled: true
 frequency: <Seconds> # Replace with an integer value for seconds based on how frequently you want metrics to be scraped
 prometheus:
 enabled: true
 commonTags: # The following tags are examples. Use tags that are relevant for your environment
 # env: dev
 # nf_app: exampleApp
 # nf_region: us-west-1

Named Profiles

When creating pipelines, a Named Profile gives you the ability to reference certain kinds of external sources, such as a private remote repository. The supported credentials are described in Types of credentials.

Configure a Named Profile

Configure profiles that you can select when creating a Terraform Integration stage.

Add profiles to the terraformer-local.yml file. The following example adds a profile named pixel-git for an SSH key secured in Vault. You can find additional profile examples at Types of credentials.

- name: pixel-git # Unique profile name displayed in Deck
 variables:
 - kind: git-ssh
 options:
 sshPrivateKey: encrypted:vault!e:<secret engine>!p:<path to secret>!k:<key>!b:<is base64 encoded?>

Add profiles to the terraformer-local.yml section of your ConfigMap. The following example adds a profile named pixel-git for an SSH key secured in Vault. You can find additional profile examples at Types of credentials.

apiVersion: v1
kind: ConfigMap
metadata:
 name: spin-terraformer-config
 namespace: spinnaker
data:
 terraformer-local.yml |
 profiles:
 - name: pixel-git # Unique profile name displayed in Deck
 variables:
 - kind: git-ssh
 options:
 sshPrivateKey: encrypted:vault!e:<secret engine>!p:<path to secret>!k:<key>!b:<is base64 encoded?>

Add profiles to the spec.spinnakerConfig.profiles.terraformer.profiles section. The following example adds a profile named pixel-git for an SSH key secured in Vault. You can find additional profile examples at Types of credentials.

- name: pixel-git # Unique profile name displayed in Deck
 variables:
 - kind: git-ssh
 options:
 sshPrivateKey: encrypted:vault!e:<secret engine>!p:<path to secret>!k:<key>!b:<is base64 encoded?>

Keep in mind:

When you create or edit a Terraform Integration stage in the UI, you can select the profile pixel-git from a dropdown.
When adding profiles:
- You can add multiple profiles under the profiles section.
- As a best practice, do not commit plain text secrets to spec.spinnakerConfig.profiles.terraformer. Instead, use a secret store: Vault, an encrypted S3 bucket, an AWS Secrets Manager, or an encrypted GCS bucket.
- For SSH keys, each profile supports only one option parameter at a time. This means that you can use a private key file (sshPrivateKeyFilePath) or the key (sshPrivateKey) as the option. To use the key file path, use sshPrivateKeyFilePath for the option and provide the path to the key file. You can also encrypt the path using a secret store such as Vault. The following option example uses sshPrivateKeyFilePath:
```
options:
sshPrivateKeyFilePath: encryptedFile:<secret_store>!e:...
```
  For more information, see the documentation for your secret store.

Add authz to Named Profiles

Armory recommends that you enable authorization for your Named Profiles to provide more granular control and give App Developers better guardrails. When you configure authz for Named Profiles, you need to explicitly grant permission to the roles you want to have access to the profile. Users who do not have permission to use a certain Named Profile do not see it as an option in the UI. Also, any stage that uses a Named Profile that a user is not authorized for fails.

Note

Before you start, make sure you enable Fiat. For more information about Fiat, see Fiat Overview and Authorization (RBAC).

This example does the following:

Grants access to the resources and accounts that you need, such as permissions to deploy to AWS via FIAT in Cloud
Enables FIAT authz to work with Terraformer

spec:
 spinnakerConfig:
 profiles:
 terraformer:
 profiles:
 fiat:
 enabled: true
 baseUrl: https://spin-fiat:7003 # ${services.fiat.baseUrl}

Types of credentials

The Terraform integration supports multiple types of credentials for Named Profiles:

AWS
SSH
Static
Terraform remote backend

If you’re not using AWS, you should configure one of the other credential types in your Named Profile.

AWS

Use the aws credential type to provide authentication to AWS. There are two methods you can use to provide authentication - by defining a static key pair or a role that should be assumed before a Terraform action is executed.

For defining a static key pair, supply an accessKeyId and a secretAccessKey:

- name: devops # Unique name for the profile. Shows up in Deck.
 variables:
 - kind: aws # Type of credential
 options:
 accessKeyId: AKIAIOWQXTLW36DV7IEA
 secretAccessKey: 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

For assuming a role instead of defining a static set of credentials, supply the ARN of the role to assume:

- name: devops # Unique name for the profile. Shows up in Deck.
 variables:
 - kind: aws # Type of credential
 options:
 assumeRole: arn:aws:iam::012345567:role/roleAssume

When assuming a role, if accessKeyId and secretAccessKey are supplied, the Terraform integration uses these credentials to assume the role. Otherwise, the environment gets used for authentication, such as a machine role or a shared credentials file.

SSH Key

Use the git-ssh credential kind to provide authentication to private Git repositories used as modules within your Terraform actions. The supplied SSH key will be available to Terraform for the duration of your execution, allowing it to fetch any modules it needs:

- name: pixel-git # Unique name for the profile. Shows up in Deck.
 variables:
 - kind: git-ssh # Type of credential
 options:
 sshPrivateKey: encrypted:vault!e:<secret engine>!p:<path to secret>!k:<key>!b:<is base64 encoded?>

Static

Use the static credential kind to provide any arbitrary key/value pair that isn’t supported by any of the other credential kinds. For example, if you want all users of the devops profile to execute against the AWS_REGION=us-west-2, use the following static credential configuration.

- name: devops # Unique name for the profile. Shows up in Deck.
 variables:
 - kind: static # Type of credential
 options:
 name: AWS_REGION
 value: us-west-2

Terraform remote backend

Use the tfc credential kind to provide authentication to remote Terraform backends.

- name: milton-tfc # Unique name for the profile. Shows up in Deck.
 variables:
 - kind: tfc
 options:
 domain: app.terraform.io # or Terraform Enterprise URL
 token: <authentication-token> # Replace with your token

Remote backends

The Terraform Integration feature supports using remote backends provided by Terraform Cloud and Terraform Enterprise.

When using remote backends, keep the following in mind:

The Terraform stage must use the same Terraform version that your Terraform Cloud/Enterprise workspace is configured to run.
The minimum supported Terraform version is 0.12.0.
In the Terraform Cloud/Enterprise UI, the type of plan action that the Terraform Integration stage performs is a “speculative plan.” For more information, see Speculative Plans in the Terraform docs.
You cannot save and apply a plan file.

Enable remote backend support

You can use remote backends by configuring the Terraform Integration stage with the following parameters:

A Terraform version that is 0.12.0 or later and matches the version that your Terraform Cloud/Enterprise runs.
Reference a remote backend in your Terraform code.

To enable support, add the following config to your terraformer-local.yml file in the .hal/default/profiles directory:

terraform:
 remoteBackendSupport: true

Retries

The Terraformer service can retry connections if it fails to fetch artifacts from Clouddriver. Configure the retry behavior in your terraformer-local.yml file by adding the following snippet:

# terraformer-local.yml
clouddriver:
 retry:
 enabled: true
 minWait: 4s # must be a duration, such as 4s for 4 seconds
 maxWait: 8s # must be a duration, such as 8s for 8 seconds
 maxRetries: 5

The preceding example enables retries and sets the minimum wait between attempts to 4 seconds, the maximum wait between attempts to 8s, and the maximum number of retries to 5.

What’s next

Use the Terraform Integration stage