How to Create Terraform Custom Job in Spinnaker

Configure and use Terraform Custom Job Stage

What you’ll learn:

  1. How to configure and set up Terraform stage in Spinnaker as a custom stage job

  2. How to execute Terraform operations through

Prerequisites:

  1. Understanding of spinnaker and spinnaker custom job.

  2. Running spinnaker with Kubernetes cluster account configured in it.

    • Get detailed information about Spinnaker Custom Job

    • At OpsMx we have developed open-source TerraSpin micro-service which seamlessly integrates with spinnaker through spinnaker custom job. Which Ideally creates three stages in spinnaker ( TSPlanJob, TSApplyJob, and TSDestroyJob ). Each stage has its own input fields and output.

Configuration Steps:

Execute the below steps to configure Spinnaker with TerraSpin Custom Job.

  1. Create a file ‘artifactaccounts.json’ add the below content and replace values according to your artifact account. The artifactaccounts.json contains account details from where the job pulls terraform code

    • accountname : This can be any descriptive name without spaces

    • artifacttype: Github, S3 or any of the supported artifiact repositories

    • Username and Password: These are the credentials for accessing the repo that will be specified during the stage input ( show later)

Note: Ensure GIT Username & Password doesn't have ‘@’ included.

artifactaccounts.json Available here

2.Create a config map from where TerraSpin Job will read the information provided in artifactaccount.json kubectl create cm terraspinbackendconfig --from-file=artifactaccounts.json -n default => ”default” namespace that is planned for using the TerraSpin Jobs. Ensure that access to this namespace is limited as credentials are available here.

3.Create a file “orca-local.yml” with the following contents and replace ALL occurrences of:

  • account: Name of the spinnaker kubernetes account.

  • application: Name of the application in Spinnaker.

  • credentials: Provide the same Kubernetes Account Name provided above.

  • namespace (under metadata): Namespace where the Terraform Job should run. This should be the same namespace where terraspinbackendconfig configmap was created in (a) above.

Orca-local.yml Available here

  1. Navigate to the following location ~/.hal/default/profiles in halyard pod/machine and then copy the orca-local.yml file created above. In case an orca-local.yml already exists, please append the contents as appropriate.

  2. Execute hal deploy apply (in halyard pod or on halyard machine)

At this point spinnaker configuration for Terraform Customer Job stage is complete. Please wait for all pods to restart and stabilize.

Executing Terraform Scripts via the custom job stage

Once spinnaker configuration for Terraform Customer Job stage is complete, the following stages should be available in pipeline configuration:

  1. TSPlanJob

  2. TSApplyJob

  3. TSDestroyJob

An example set of screen shots with valid inputs is provided towards the end of this document.

TSPlanJob:

This stage does Terraform infra-code initial formal run basically (terraform init and terraform plan). This stage has the following five inputs.

  1. Artifact account : This must be one of the “account” values that were defined in artifactaccounts.json .

  2. Terraform plan:

    • This is a location of Terraform Script.

    • Provide the location in the form of ‘username/repo-name.git//folder’.

    Note

    The two // separting the repo and the folder containing the terraform root module script. E.g. for github: OpsMx/staging-terraform-pm.git//azure/k8cluster. The credentials for accessing this repo were provided in artifactaccounts.json.

  3. Override file (optional): If present, the file specified here will be applied on the root module. Possible use-case might be to provide a tfvars file.

    Note

    Note: If you would like to ignore this option, ensure the block is empty by removing the help text available

  4. State repo: This is repo where the terraform state files are stored and retrieved across multiple stages such as between plan and apply, apply and destroy. This is mandatory for the Terraform Custom Job Stage to function.

    Note

    As state-information can contain credentials in plain-text, this repo should have control access. Same account name and their credentials will be used to access this repo (E.g. opsmx/staging-terraform-states.git).

  5. UUId: This can be any unique string based on user choice to identify the terraform state across multiple stages. It is not mandatory to have all the stages(TSPlan, TSApply, TSDestroy) in the same pipeline. However, they all should have the same UUid.

Output: This stage will show terraform init and plan command output.

TSApplyJob:

Functionality of this stage is to create terraform infra-code( terraform apply ). Here stage output will have properties with terraform infra-code output-values in a key-value format so that user can use those values in the next subsequent stage of pipeline this stage has four inputs.

1.Artifact account.

2.Override file.

3.State repo.

4.UUId.

Output: This stage will show terraform apply command output.

TSDestroyJob:

Functionality of this stage to destroy terraform infra-code basically ( terraform destroy ) this stage has four inputs.

1.Artifact account.

2.State repo.

3.UUId.

Output: This stage will show terraform destroy command output