Plural Terraform Provider

How to use our Terraform provider and other helpful doclinks

Terraform Provider

For ingesting clusters or creating net-new infrastructure, our Terraform provider is usually the most natural surface for integrating Plural with your existing processes or adopting a full IaC-based infrastructure management approach from the ground up.

Our provider is available on the Terraform Registry's Plural Provider page. It can also be used from Pulumi — see Using from Pulumi.

You can see snippets throughout our getting started guides, but some common use cases are as follows:

Configuring the Provider

terraform

terraform {
  required_providers {
    plural = {
      source = "pluralsh/plural"
      version = "0.2.32"
    }
  }
}

provider "plural" {
  # if you use Plural Stacks, authentication is auto-configured using temporary credentials
}

Ingesting a new Cluster

Used for ingesting new or existing Kubernetes clusters into Plural.

terraform

# ensure kubernetes auth is configured for the plural provider
provider "plural" {
    kubernetes = {
        # kubernetes auth configuration
    }
}

resource "plural_cluster" "example" {
  name   = "my-cluster"
  handle = "my-cluster"
  metadata = jsonencode({
    iam = {
        load_balancer = module.addons.gitops_metadata.aws_load_balancer_controller_iam_role_arn # demonstrative module references for setting up IAM
        cluster_autoscaler = module.addons.gitops_metadata.cluster_autoscaler_iam_role_arn
    }
  })
}

Call a PR automation

This is useful if your Terraform needs to trigger other changes. Some use cases:

Provision infrastructure in another repo using context from Terraform derived in the current repo
Self-service provision dev workspaces (create a repo with the GitHub Terraform provider, PR-automate GitHub Actions, docs, etc.).

terraform

data "plural_pr_automation" "this" {
    name = "my-pr-automation"
}

resource "plural_pr_automation_trigger" "new" {
    pr_automation_id = data.plural_pr_automation.this.id
    pr_automation_branch = "plrl/my-pr-automation/this"
    context = {
        input = "some-input-value"
    }
}

Create/Use a ServiceContext

Service contexts are reusable pieces of configuration that provide a mechanism to share Terraform code between isolated stacks without relying on a giant state file or a brittle CLI-based control mechanism.

They're simple to use. Here's an example of writing to one:

terraform

# example IRSA binding
module "assumable_role_externaldns" {
  source                        = "terraform-aws-modules/iam/aws//modules/iam-assumable-role-with-oidc"
  version                       = "3.14.0"
  create_role                   = true
  role_name                     = "${var.cluster_name}-externaldns"
  provider_url                  = replace(local.cluster_oidc_issuer_url, "https://", "")
  role_policy_arns              = [aws_iam_policy.externaldns.arn] # defined elsewhere
  oidc_fully_qualified_subjects = ["system:serviceaccount:${var.namespace}:${var.externaldns_serviceaccount}"]
}

resource "plural_service_context" "externaldns" {
    name = "plrl/irsa/externaldns"
    configuration = jsonencode({
        roleArn = module.assumable_role_externaldns.this_iam_role_arn
    })
}

And to read one:

terraform

data "plural_service_context" "externaldns" {
  name = "plrl/irsa/externaldns"
}

locals {
  externaldns_context = jsondecode(data.plural_service_context.externaldns.configuration) # it is json encoded coming from our api
  external_dns_arn = local.externaldns_context.roleArn 
}