Outputs

Outputs are templates that defines how and where your grants should materialize. An Output will generate native Terraform code to be stored in your Version Control System (VCS).

Output Spec

output = {
    # RFC 3986 URI string that points to the location of your generated HCL code.
    # Example: github://{organization}/{repository}/path/to/my/access.tf
    location = "..."
    append = <<-EOT
    EOT
}

Writing Outputs For Your Grant Kit

Outputs are written using the Grant Kit's Workflows DSL as native Terraform HCL code.

Writing Outputs consists of four steps:

1. Define a location.

2. Choose an Output Strategy.

3. Leverage Terraform Providers.

4. Optionally interpolate variables.

Define a location

A Grant Kit's Output defines how and where your access grants should materialize. The location attribute represents the where.

The location defines which file and at what path you want your access changes to materialize into. This is a RFC 3986 URI string. You can configure any path and any file name. Abbey will create the paths and file for you if they don't exist.

Example location Configurations

// Organization: abbeylabs
// Repository: starter-kit-quickstart
// Access changes are materialized to: access.tf at the directory root
location = "github://abbeylabs/starter-kit-quickstart/access.tf"

// Organization: jeffchao (personal, not a GitHub org)
// Repository: my-starter-kit
// Access changes are materialized to: access.tf at the abbey-managed subdirectory.
location = "github://jeffchao/my-starter-kit/abbey-managed/access.tf"

// Organization: jeffchao (personal, not a GitHub org)
// Repository: my-starter-kit
// Access changes are materialized to: access.tf
//   under `resource "github_team_membership" "my_group"`
location = "github://jeffchao/my-starter-kit/abbey-managed/access.tf#github_team_membership.my_group"

// Organization: jeffchao (personal, not a GitHub org)
// Repository: my-starter-kit
// Access changes are materialized to: access.tf
//   under `resource "okta_group_memberships" "my_group"`
//   appended to users attribute
location = "github://jeffchao/my-starter-kit/abbey-managed/access.tf#okta_group_memberships.my_group.users"

Currently Abbey supports the github:// scheme. Future schemes such as file://, s3://, and https:// coming soon.

Choose an Output Strategy

Abbey will automatically manage access through the file you specified at location.

Abbey supports one Output Strategy:

1. append: Access changes are treated as a new Terraform Resource block and appended to the access Terraform file at location.

Leverage Terraform Providers

A Grant Kit's Output defines how and where your access grants should materialize. The Output's append block represents the how.

It contains a string value, typically a multiline Heredoc string for better visibility. The contents of this string is HCL code generally using OSS Terraform Providers from the Terraform Provider Registry that map to the resources you want Abbey to manage.

Examples of Leveraging Terraform Providers in Your Grant Kit Output

# Statically append to your `access.tf` file the `snowflake_role_grants` resource.
append = <<-EOT
    resource "snowflake_role_grants" "pii_role" {
        role_name = "ROLE"
        users     = ["USER"]
    }
EOT

# Statically append to your `access.tf` file the `mongodbatlas_database_user`
# resource with the `readWrite` role for the database `dbforApp`.
append = <<-EOT
    resource "mongodbatlas_database_user" "test" {
        username           = "test-acc-username"
        password           = "test-acc-password"
        project_id         = "<PROJECT-ID>"
        auth_database_name = "admin"

        roles {
            role_name     = "readWrite"
            database_name = "dbforApp"
        }
    } 
EOT

Optionally Interpolate Variables

In order to configure meaningful Grant Kit Outputs, you need to be able to configure dynamic strings rather that static strings from the examples above. Abbey supports this through variable interpolation.

When an access request is made, Abbey performs two layers of variable interpolation:

1. Terraform String Interpolation.
2. Go text/template Interpolation.

Terraform String Interpolation

Abbey will first perform Terraform String Interpolation. This happens when an access request is made it's now time to generate Output based on your append block.

Since the contents of the append block is a Terraform string, Abbey will interpolate variables using native Terraform syntax.

Usage

• To interpolate variables, use ${some_variable_name}.

• You can interpolate any of your existing Terraform objects such as resource and data objects.

Example

# This example builds on the above. It shows how you can replace
# the value at `role_name` with the `name` attribute of
# a `snowflake_role_grants` Terraform resource named `pii_readonly_role__...`.
#
# This example assumes a `snowflake_role_grants` resource
# named `pii_readonly_role` already exists.
#
# The value is replaced when when `terraform apply` is run.
append = <<-EOT
    resource "snowflake_role_grants" "pii_readonly__USERNAME" {
        role_name = ""
        users     = ["USER"]
    }
EOT

• You can also interpolate the resource name of the output. This can be used to create multiple of the same resources for different requests.

Example

# NOTE: Due to how terraform generates random values, issuing multiple requests 
# at once will cause the this following example to use the same random string.
# The random string is changed every time terraform apply is called.
append = <<-EOT
      resource "abbey_demo" "grant_read_write_access_${random_pet.random_pet_name.id}" {
        permission = "read_write"
        email = "{{ .user.email }}"
      }
EOT

resource "random_pet" "random_pet_name" {
  keepers = {
    first = "${timestamp()}"
  }
  length = 5
  separator = "_"
}

Go text/template Interpolation

Next, Abbey will perform Go text/template Interpolation. This happens after the output of Terraform String Interpolation.

Usage

• To interpolate variables, use {{ .some_variable_name }}.

• Abbey provides Enriched Data as variables for you to interpolate.

Example

# This example shows how you can replace the statically-named
# `pii_readonly` role with a dynamically-named name using the
# `snowflake.username` attribute from Enriched Data.
append = <<-EOT
    resource "snowflake_role_grants" "pii_readonly__" {
        role_name = "ROLE"
        users     = ["USER"]
    }
EOT

Notice the preceding . in the string template. This is required to access the object.

Also notice that even though Abbey uses Go's text/template, Abbey automatically converts this to snake_case naming so the experience is consistent across the entire Grant Kit configuration flow.

Output Materialization

Abbey materializes output to a Terraform file based on what you configured in your append block and after applying Terraform String Interpolation and Go text/template Interpolation.

Output Materialization.

Output Materialization has three stages:

1. Interpolate Terraform variables.

2. Interpolate Enriched Data variables.

3. Generate Output to your location.

Troubleshooting

A common deployment failure for grant kits is a misconfigured location field in the output block

• Double check it starts with github://

• Double check repository and username or org name is correct

  • These fields are case-sensitive so double check any upper/lowercase letters

• Double check for any extra : or /'s

• Double check the path to your output location exists

  • Note: Abbey will create the file for you if it doesn't exist, but will not create directories.