Skip to main content

Terraform provider

In this tutorial we will use the Avassa Terraform provider to create resources in an environment.

The goal is to get the first building blocks in place in a repeatable way:

  • a system site (where workloads will run)
  • a local user (so you have a repeatable way to bootstrap a Control Tower user)
  • an application-owner tenant (who owns apps)
  • a tenant → site assignment (so the tenant can use the site)

Terraform is a good fit since it is easy to run locally, in CI, and to clean up.

tip

If you want to try this in a live environment, sign up for a free trial and we will set you up with a running system.

References (Terraform Registry)​

Prerequisites​

  • Terraform (version depends on your environment and provider features)
  • supctl installed and configured
  • Access to an Avassa Control Tower API endpoint
  • Credentials with permission to create sites, tenants, and assignments

Setup authentication​

Credentials​

This tutorial uses a supctl profile for authentication and API endpoint configuration. This keeps credentials out of Terraform variables and matches how you typically work with supctl.

Create/select a supctl profile​

If you have not installed supctl yet, see how to install supctl. For a walkthrough, see Introduction to supctl.

Create a profile for your environment and log in (example):

supctl profile create --host api.example.avassa.net testing
supctl do oidc-login

Confirm the profile is active:

supctl profile show

The provider loads profiles from $XDG_CONFIG_HOME/supctl/profiles/{profile}/ (or ~/.config/supctl/profiles/{profile}/). You can also select the profile via AVASSA_PROFILE, and override the base directory via AVASSA_PROFILE_DIR (or SUPCTL_PROFILE_DIR).

Create the Terraform configuration​

Create a new folder and add a main.tf with the configuration below.

This file contains three steps:

  1. Create a system site
  2. Create a local user (userpass)
  3. Create a tenant
  4. Assign the site to the tenant

main.tf​

terraform {
  required_providers {
    avassa = {
      source  = "avassa-systems/avassa"
      version = ">= 0.0.2"
    }
  }
}

provider "avassa" {
  # Must match a local supctl profile name
  profile = "testing"
}

# 1) Create a minimal system site.
resource "avassa_system_site" "example" {
  name             = "example-site"
  descriptive_name = "Example site"
  type             = "edge"
}

# 2) Create a local Control Tower user in the *current* tenant (from your supctl profile).
#
# Note: Prefer the write-only argument `password_wo` so the plaintext password is not stored
# in Terraform state (requires Terraform 1.11+).
resource "avassa_userpass" "example_user" {
  name     = "example.user@example.com"
  fullname = "Example User"

  password_wo         = "ChangeMe-UseAVarOrSecretManager"
  password_wo_version = 1

  # Policies depend on your Avassa installation. Adjust to match what exists
  # in your environment.
  token_policies = ["default", "user"]

  distribute = {
    to = "inherit"
  }
}

# 3) Create an application-owner tenant.
resource "avassa_tenant" "example" {
  name             = "example-tenant"
  descriptive_name = "Example tenant"
  kind             = "application-owner"

  # Policies depend on your Avassa installation. Adjust to match what exists
  # in your environment.
  policies = ["app-owner-tenant"]
}

# 4) Assign the site to the tenant.
resource "avassa_assigned_site" "example" {
  tenant = avassa_tenant.example.name
  site   = avassa_system_site.example.name
}

Apply the configuration​

In the same directory as main.tf, run:

terraform init
terraform plan
terraform apply

Verify​

Use supctl or the UI to verify the created resources. You should see resources for the site, tenant, and the assigned site.

Clean up​

To remove everything created by this guide:

terraform destroy

Notes and troubleshooting​

  • Policies: the avassa_tenant.policies values must exist in your Avassa environment. If "default" is not valid, replace it.
  • Site configuration: avassa_system_site can be configured with hosts, ingress settings, labels, and more. This guide intentionally keeps it small.
  • Tenant → site assignment: this tutorial uses avassa_assigned_site to assign the site to the tenant. If your environment requires additional restrictions or configuration, consult the Registry docs.
  • Users: avassa_userpass creates a local userpass entry in the tenant you are authenticated as (the tenant in your supctl profile). If you want to create users inside the new tenant, you typically create a tenant root token and then add userpass entries within that tenant (see the multi-tenancy tutorial).
  • Password handling: don’t hardcode passwords in Git. Use Terraform variables, a secrets manager, and (preferably) the write-only password_wo argument.
  • Running in CI: if you cannot use a supctl profile in CI, configure the provider directly with api_url and auth_token (see the provider docs in the Registry).