Write policy plugins

Plugins provide a way to extend Terraform policy with additional functions that you can use to customize your policy authoring experience. Write Terraform policy plugins in Golang using the terraform-policy-plugin-framework open source library.

You must compile Terraform policy plugins and include them in your policy VCS repository before you can use them in your policies. In your policy files, use the core::<functionname> syntax to refer to functions built into Terraform or Terraform policy. Use the plugin::<pluginname>::<functionname> syntax to refer to functions from plugins that you write.

Author a plugin

To author your own plugins, create a new Go package, import the Terraform policy plugin framework library, and then author a main() function to register your plugin's functions and Go functions to implement each of them.

The following is an example of a plugin that defines two functions, echo, and trim:

package main

import (
  "strings"
  "github.com/hashicorp/terraform-policy-plugin-framework/policy-plugin/plugins"
)

func main() {
  plugins.RegisterFunction("echo", echo)
  plugins.RegisterFunction("trim", trim)
  plugins.Serve()
}

func echo(value string) (string, error) {
  return value, nil
}

func trim(value, prefix string) (string, error) {
  return strings.TrimPrefix(value, prefix), nil
}

After you implement your plugin in Go, build it into a binary with the go build command, and store both the source and binary in the same VCS repository as your policy files.

Plugin directory structure

Set up the following directory structure for your plugin to ensure Terraform policy can read it:

./
├── policies/
├── tests/
├── plugins/
│   ├── src/
│   │   └── example/
│   │       ├── main.go
│   │       ├── go.mod
│   │       └── go.sum
│   └── bin/
│       └── example
└── README.md

When you enforce your policies in HCP Terraform, your VCS repository must also contain the plugin binary.

Compile a plugin

Before you can use your plugin in your policies, you must compile it.

Change into the plugin source directory.

$ cd plugins/src/example

Initialize go modules.

$ go mod init example

Download and verify go modules.

$ go mod tidy

Build the plugin.

$ go build -o ../../bin/example main.go

Use plugins in policies

Specify plugins by using the plugins {} block within the policy {} block of your .policy.hcl files. Refer to The policy {} block for more information.

policy {
  plugins {
    example = {
      source = "../plugins/bin/example"
    }
    second_example = {
      source = "path/to/second-bin"
    }
  }
}

locals {
  instance_type = plugin::example::trim("foo.t3.micro", "foo.")
}

The value of the source attribute must be a string that is the relative path to a binary in the same VCS repository as your policies. The binary must be a valid Terraform policy Go plugin server. Use the terraform-policy-plugin-framework open source library to ensure your plugin provides the correct interface.

Reference your functions with the plugin:: prefix in your policies.

Requirements

You must precompile function plugins in order to execute policies that include on HCP Terraform. Terraform policy assumes that a precompiled binary is available with the appropriate directory structure when you configure the policies into a policy set.