Onboarding to Terraform Pipeline

1. Create a tf-<product>-<component> repository in the MuleSoft-Ops Organization

This repository is meant to host all of your Terraform (.tf) files and should be organized according to the latest Terraform standards.

There are plenty of example repositories to look at in MuleSoft-Ops to show you how to organize your variables, profiles, modules, dependencies, etc.

You can request a new repository from any channel in Slack using this ProdEng bot slash command:

/prodeng create-repo

2. Setup your Terraform resources

Once you have your repository, you will need to add the basics to get started with Terraform.

The basics are:

1. main.tf
2. variables.tf

Main

The main.tf is merely an example of a basic Terraform file. You can provide any and all resources there, or you can organize them by any other logical grouping of separate .tf files

It can often be helpful to group your Terraform code by infrastructure type, AWS service configurations, etc.

Example: If you have IAM resources, you can group them all in an iam.tf or if you have RDS databases, place the necessary configurations in rds.tf

The Terraform pipeline will not be prescriptive of how you must organize your files.

Variables

The variables.tf file will be necessary as you configure more resources. Eventually, you will need to provide data that is used throughout the repository or even supplied from another module.

If you're just getting started, the basic variables you will need can be seen in the next section because you will want to use variables to provide data for the tags module.

3. Tag your Terraform resources

This is a requirement for all of our AWS resources, and therefore is a critical part of onboarding your Terraform through the MuleSoft Terraform pipeline.

There is a module that you should take advantage of to get started, and then you may add any other necessary tags by merging them with the tags module.

Include the tags module

In your modules.tf file, add the tags module

module "tags" {
  source        = "git::git@github.com:mulesoft-ops/tf-tags-module.git?ref=v2.0.0"
  product_tag   = "${var.product_tag}"
  component_tag = "${var.component_tag}"
  asset_tag     = "${var.asset_tag}"

  u_gus_team_id      = "<id>" # your team's ID
  u_customer_data    = "None"
  p_confidentiality  = "Internal"
  u_service_tier     = "<service-tier>"
  u_scan_eligibility = "Not Applicable"
}

Add any other tags you need

If you have other tags you would like to include alongside the required tags, you can modify them in the modules.tf

locals {
  legacy_devops_tags = {
    ENV       = var.env
    OWNER     = var.owner
    ROLE      = var.role
    REPO      = "https://github.com/mulesoft-ops/tf-muleteer"
    Terraform = "true",
  }

  common_tags = merge(module.tags.tags, local.legacy_devops_tags)
}

Or you can add them to individual resources in your .tf files

resource "<type>" "<name>" {
  some_key = some_value

  # here we are merging our tags 'Name' and 'ENV' with
  # the existing tags from the tags module
  tags = merge(var.tags, tomap({"Name" = "${var.name} "ENV" = "${var.environment}"}))
}

4. Add a Jenkinsfile to your terraform repository

Finally, once your Terraform is setup, you will need a Jenkinsfile in your Terraform repository which will be discoverable by the terraform-new job in Jenkins.

You can use this Jenkinsfile as an example

Adjust your available regions according to your needs

switch (env.JENKINS_URL) {
   case devJenkins:
       supportedEnvs = ['kdev']
       supportedRegions = ['us-west-2']
       break
   case buildJenkins:
       supportedEnvs = ['kstg', 'kprod']
       supportedRegions = ['us-west-2']
       break
   case govJenkins:
       supportedEnvs = []
       supportedRegions = []
       automaticEnvs = []
       automaticRegions = []
       break
   default:
       error "unknown jenkins url ${env.JENKINS_URL}"
       break
}

NOTE: you may be concerned that the Jenkinsfile does not have a plan option. Our Terraform job runs a plan and then asks for input before running the apply. See the

5. Kick off the Terraform job

After you add your Jenkinsfile, you should be able to start a build in Jenkins using the terraform-new job.

https://jenkins.build.msap.io/job/DevOps/job/terraform-new/

The job will run a terraform plan and then ask for your input to approve the plan. Once you approve, the job will run the actual Terraform apply command.