Onboard an AWS account for Kompass with Terraform

Prev Next

This topic describes how to use Terraform to onboard AWS accounts for use with Zesty Kompass products.

Terraform enables flexible and repeatable onboarding with Kompass Insights within your infrastructure.

Limitations and Lifecycle

Limitations

  • Products: Only Kompass solutions are supported (other Zesty products will be supported in the future).

  • Lifecycle: After onboarding with Terraform, all future changes must also use Terraform.

Lifecycle management

You can onboard an account using either the Zesty platform UI or Terraform. The method you choose to begin the process determines which tools you must use to manage changes throughout the product lifecycle.

Account updating is determined by the onboarding source:

  • If an account was onboarded using Terraform, the account can be updated only with Terraform.

  • If an account was onboarded using the UI, the account can be updated only with the UI.

To onboard AWS accounts with the Zesty platform UI or to onboard for other Zesty products, see Onboard an AWS account with Zesty platform.

Select the tab that matches the account type to onboard:

The Terraform module does the following during onboarding:

  • Creates a secure cross-account IAM role: Generates an external ID and trusted role that Zesty can assume to access account, infrastructure, and billing metadata.

  • Grants read-only visibility into services and costs: Attaches permissions for EC2, EKS, CloudWatch, Organizations, Cost Explorer, Savings Plans, quotas, and related resources.

  • Creates a CUR and storage bucket: Provisions a private S3 bucket and configures AWS Billing to generate an hourly Parquet CUR delivered to that location.

  • Prepares CUR data for Athena analysis: Creates the Glue database, external table schema, and Athena workgroup required to query cost data.

  • Registers the account and outputs Kompass configuration: Sends account, role, CUR, and Athena details to Zesty and writes the Kompass values file for onboarding.

Prerequisites

  • API token for Zesty platform, provided by a Zesty representative

  • Access to AWS account to onboard

  • Terraform AWS provider v6.0, or later

  • Terraform v1.3.0, or later

To onboard an AWS management account using Terraform:

  1. Log in to the AWS account to be onboarded.

  2. Set up the Terraform configuration:

    1. Copy the Terraform module code from the Example Usage section of Terraform Zesty Module.

      module "master-aws-eks-cluster" {
  source  = "zesty-co/master-aws-eks-cluster/zesty"
}

    2. Save the configuration, for example, main.tf.

  3. Use Terraform to deploy:

    1. Initialize Terraform:

      terraform init

    2. (Optional) Preview changes:

      terraform plan

    3. Apply the configuration:

      terraform apply

Optional adjustments

Before deploying, you can customize the following:

  • Name of the IAM role: You can change the name of the IAM role (ZestyIAMrole, by default).

  • AWS provider: If you don’t have an AWS provider defined, define one in the configuration.

  • Helm provider: If you don’t have a Helm provider defined, define one in the configuration.

Set a custom IAM role name

The default IAM role name is ZestyIAMrole.

To change the IAM role name:

  1. Copy the role_name code line and add it under the source line in the module section of main.tf.

    module "zesty" {
  source              = "zesty-co/aws-eks-cluster/zesty"
  role_name = <NAME THE ROLE> //the default is ZestyIAMRole
}

  2. Type the new role name.

  3. Save the file.

Set an AWS provider

If you don’t have an AWS provider defined, configure that.

To set an AWS provider:

  1. Copy the following code and paste it into main.tf above the Cloud Provider Block.

    provider "aws" {
  profile = <PROFILE-NAME>
  region  = <AWS-REGION>
}

  2. Replace the values of the variables.

  3. Save the file.

Set a Helm provider

If you don’t have a Helm provider defined, configure that.

To set a Helm provider:

Copy the following code and paste it into main.tf above the helm Provider Block:

provider "helm" {
  kubernetes = {
    config_path    = "~/.kube/config"
    config_context = "CONTEXT_NAME"
  }
}

You can use Terraform to:

  • Onboard a Linked AWS account for use with Kompass and install the Insights agent in the same step.

  • Onboard a Linked AWS account for use with Kompass without installing the Insights agent.

The following limitations relate to installing and updating the Insights agent (in addition to the limitations described in Lifecycle management):

  • Insights agent installation (and updating) is determined by the onboarding source:

    • If an account was onboarded using the UI, the Insights agent can be installed (and updated) only with the UI.

    • If an account was onboarded using Terraform, the Insights agent can be installed (and updated) with either Terraform or the UI.

Best practice: After onboarding an account with Terraform, continue to use Terraform to install the Insights agent, update, etc.

Prerequisites

  • API token for Zesty platform, provided by a Zesty representative

  • Access to AWS account to onboard

  • Terraform AWS provider v6.0, or later

  • Terraform v1.3.0, or later

  • If installing the Insights agent, Terraform Helm provider v2.14.1, or later

You must install the Insights agent before installing other Kompass solutions.

Proceed with one of the following:

Onboard a Linked account and install the Insights agent

This procedure onboards an AWS Linked account and installs the Kompass Insights agent using Terraform.

To onboard an AWS Linked account and install the Insights agent:

  1. Log in to the AWS account to be onboarded.

  2. From the AWS console, connect to the target cluster.

  3. Set the Zesty API token environment variable:
    export ZESTY_API_TOKEN=<API-KEY>

  4. Set up Terraform configuration:

    1. Copy the Terraform module code from the Example Usage section of Terraform Zesty Module.

      module "zesty" {
  source              = "zesty-co/aws-eks-cluster/zesty"
}
resource "helm_release" "kompass" {
  name             = "kompass"
  repository       = "https://zesty-co.github.io/kompass"
  chart            = "kompass"
  namespace        = "zesty-system"
  cleanup_on_fail  = true
  create_namespace = true
  values = [module.zesty.kompass_values_yaml]
}

    2. (Optional) Customize the configuration, as described in Optional adjustments.

    3. Save the configuration, for example, main.tf.

  5. Use Terraform to deploy:

    1. Initialize Terraform:

      terraform init

    2. (Optional) Preview changes:

      terraform plan

    3. Apply the configuration:

      terraform apply

Optional adjustments

Before deploying, you can customize the following:

  • Name of the IAM role: You can change the name of the IAM role (ZestyIAMrole, by default).

  • Storage class value: If you are installing the Insights agent, you must set the name of the storage class in your environment. The default value is ebs-sc

  • AWS provider: If you don’t have an AWS provider defined, define one in the configuration.

  • Helm provider: If you don’t have a Helm provider defined, define one in the configuration.

Set a custom IAM role name

The default IAM role name is ZestyIAMrole.

To change the IAM role name:

  1. Copy the role_name code line and add it under the source line in the module section of main.tf.

    module "zesty" {
  source              = "zesty-co/aws-eks-cluster/zesty"
  role_name = <NAME THE ROLE> //the default is ZestyIAMRole
}

  2. Type the new role name.

  3. Save the file.

Set the storage class name

If you are installing the Insights agent with Terraform, you must set the name of the storage class to match the name used in your environment.

The default value for storageClassName is ebs-sc.

To get the storage class name in your environment, run kubectl get storageclass on the cluster.

To set the storage class name:

  1. Copy the following code:

     set = [{
    name  = "global.storageClassName"
    value = "gp2"
    }, {
    name  = "grafana.persistentVolume.storageClassName"
    value = "gp2"
    }, {
    name  = "victoriaMetrics.server.persistentVolume.storageClassName"
    value = "gp2"
    }, {
    name  = "kompass-insights.persistence.spec.storageClassName"
    value = "gp2"
  }]

  2. Paste it into the main.tf file under the values.

  3. Replace gp2 with the name of your storage class.

  4. Save the file.

Set an AWS provider

If you don’t have an AWS provider defined, configure that.

To set an AWS provider:

  1. Copy the following code and paste it into main.tf above the Cloud Provider Block.

    provider "aws" {
  profile = <PROFILE-NAME>
  region  = <AWS-REGION>
}

  2. Replace the values of the variables.

  3. Save the file.

Set a Helm provider

If you don’t have a Helm provider defined, configure that.

To set a Helm provider:

Copy the following code and paste it into main.tf above the helm Provider Block:

provider "helm" {
  kubernetes = {
    config_path    = "~/.kube/config"
    config_context = "CONTEXT_NAME"
  }
}

Onboard an account only

This procedure onboards an AWS Linked account using Terraform.

To onboard an AWS Linked account only:

  1. Log in to the AWS account to be onboarded.

  2. Set up the Terraform configuration:

    1. Copy the Terraform module code from the Example Usage section of Terraform Zesty Module.

      module "zesty" {
  source              = "zesty-co/aws-eks-cluster/zesty"
}
resource "helm_release" "kompass" {
  name             = "kompass"
  repository       = "https://zesty-co.github.io/kompass"
  chart            = "kompass"
  namespace        = "zesty-system"
  cleanup_on_fail  = true
  create_namespace = true
  values = [module.zesty.kompass_values_yaml]
}

    2. Comment (or delete) the helm_release "kompass" block.

    3. Save the configuration, for example, main.tf.

  3. Use Terraform to deploy:

    1. Initialize Terraform:

      terraform init

    2. (Optional) Preview changes:

      terraform plan

    3. Apply the configuration:

      terraform apply

© 2026 Zesty. All Rights Reserved

info@zesty.co