Infralyst Docs

Infralyst connects to your AWS accounts through a read-only IAM role provisioned by a Terraform module. We never get write access to your infrastructure and we never store AWS credentials.

What the Terraform module creates

The module creates a single IAM role (infralyst-readonly) in your account with a trust policy that allows Infralyst's AWS account to assume it via STS. An External ID, unique to your workspace, is required for every assume-role call to prevent the confused deputy problem. No long-lived access keys are created.

What data we collect

For each supported resource type, Infralyst collects CPU utilization and memory utilization from CloudWatch, along with resource configuration metadata (instance types, launch templates, task definitions, Auto Scaling Group settings, and ECS service definitions). On first connection, we fetch up to a year of historical data. After that, we poll every 4 hours to keep the usage history current.

We use this data to build a usage profile for each resource and generate recommendations. We don't access application data, secrets, or anything outside the permissions listed above. Terraform state is loaded on demand when generating a PR, read once, and discarded. See the Supported resources section for how each type is analyzed and what thresholds trigger a recommendation.

When recommendations appear

After the initial data fetch and analysis completes, Infralyst generates up to 5 recommendations for your highest-savings opportunities first. After that, one new recommendation is generated per day as more resources are analyzed.

Each resource needs a minimum of 30 days of data at 95% uptime before it's eligible for a recommendation. This can vary by resource type. See the individual resource pages under Supported resources for specifics.

Setup

1. Add an AWS account in your workspace.
2. Follow the in-app steps to apply the Infralyst Terraform module in one of your infra repos:

module "infralyst_readonly_integration" {
  source  = "infralyst/readonly-integration/aws"
  version = "~> 1.0"

  external_id = "<your_workspace_external_id>"
}

output "infralyst_role_arn" {
  value       = module.infralyst_readonly_integration.role_arn
  description = "Paste this Role ARN into Infralyst"
}

3. Run terraform init and terraform apply.
4. Copy the infralyst_role_arn output and paste it into Infralyst.
5. Click Test connection to verify.

The app provides your External ID and walks you through each step.

View the Terraform module on the Terraform Registry →

Disconnecting

Disconnect the AWS account from your workspace settings in Infralyst. This stops all data collection and analysis immediately.

To fully remove access on your end, remove the Terraform module block from your configuration and run terraform apply to destroy the IAM role.

Infralyst opens pull requests in your repositories through a GitHub App. We never push directly to your main branch and we never merge changes on your behalf. Every change goes through your normal review process.

App permissions

The Infralyst GitHub App requests:

• Read access to repository metadata.
• Read and write access to code, pull requests, and repository hooks.

Write access to code and pull requests is what allows Infralyst to open PRs with Terraform changes. Repository hooks let us stay in sync when relevant files change.

Choosing repos

During installation you select which repositories the app can access. Choose only the repos that contain your Terraform infrastructure code. The app cannot see or interact with any repository you haven't explicitly selected.

You can change your repo selection at any time from the GitHub App settings.

What the app doesn't do

• Push to main or any protected branch.
• Merge or approve pull requests.
• Access repositories you haven't selected.
• Read or modify anything outside of Terraform files relevant to a recommendation.

Setup

1. Install the Infralyst GitHub App from your workspace.
2. Choose your GitHub organization and select the repositories that contain your Terraform code.
3. Add those repos to your workspace.

Terraform state is where everything connects. A state mapping tells Infralyst which state file belongs to which AWS account and lives in which GitHub repo. This is how recommendations turn into pull requests that land in the right place.

Why we need this

Your Terraform state file is the link between a running AWS resource and the .tf code that defines it. Infralyst uses it to match a resource identified through CloudWatch metrics to the exact file, resource block, and attribute that needs to change in a pull request.

We don't store a copy of your state. We load it on demand when generating a PR, read the resource mappings we need, and discard it.

How mapping works

For each AWS account, you add one or more Terraform states. Each state connects:

• An AWS account (the source of metrics and recommendations)
• A backend (where the state file lives, either GitHub or S3)
• A GitHub repo (the repo that contains the Terraform code for resources in that state)

This supports any infrastructure layout. One repo managing multiple AWS accounts, multiple repos for a single account, or any other combination. Just add the state mappings that match your setup.

S3 backend

If your Terraform state is stored in S3, Infralyst needs read access to the bucket. The app generates the exact bucket policy for you during setup:

# Provider alias for the region where your state bucket lives.
# If you already have this provider defined, you can skip this block.
provider "aws" {
  alias  = "infralyst_state_region"
  region = "<your-bucket-region>"
}

resource "aws_s3_bucket_policy" "infralyst_state_access" {
  provider = aws.infralyst_state_region
  bucket   = "<your-state-bucket>"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Sid    = "InfralystReadAccess"
      Effect = "Allow"
      Principal = {
        AWS = "arn:aws:iam::<infralyst_account_id>:role/infralyst-readonly"
      }
      Action = [
        "s3:GetObject",
        "s3:ListBucket"
      ]
      Resource = [
        "arn:aws:s3:::<your-state-bucket>",
        "arn:aws:s3:::<your-state-bucket>/<your-state-key>"
      ]
    }]
  })
}

The app fills in the correct values for your bucket, state path, and Infralyst's account ID. Apply this alongside the read-only integration module.

Setup

1. In your workspace, go to the AWS account you want to configure.
2. Add a Terraform state.
3. Choose the backend (GitHub or S3).
4. If using S3, apply the generated bucket policy.
5. Select the GitHub repo that owns the Terraform code for that state.
6. Repeat for each state file associated with that account.

When you click "Generate PR," an AI agent reads your Terraform repository and writes the code change. The agent locates the relevant resource definitions, applies the change, validates the syntax, and reviews the result for edge cases. For example, it detects shared variables that could affect other resources, lifecycle blocks that would prevent the change from taking effect, and launch templates shared across multiple Auto Scaling Groups.

Warnings in pull requests

PRs include warnings when a change could affect availability or performance:

• Downtime required for standalone EC2 instances (stop/start needed), single-instance Auto Scaling Groups, and single-task Fargate services. Multi-instance ASGs use instance refresh for zero downtime rollouts. Multi-task Fargate services use rolling deployments.
• Throughput and bandwidth warnings when a smaller instance type or task size could reduce network or EBS throughput ceilings.

What the AI agent doesn't do

The AI agent only generates the Terraform code change. It never pushes to your main branch, never merges pull requests, and never applies anything to your AWS infrastructure. Every change goes through your normal GitHub review and merge process.

Slack integration is optional. It lets your team get notified about new savings opportunities and manage recommendations without leaving Slack.

What you get

• Notifications when new recommendations appear.
• PR generation directly from Slack. Generate a Terraform PR from a notification without leaving the channel.
• Dismiss recommendations from Slack if a suggestion isn't relevant.
• Flexible routing so the right team sees the right recommendations. Each AWS account or GitHub repo can be assigned to a specific Slack channel.

Setup

1. Connect Slack from your workspace settings.
2. For each AWS account or GitHub repo, assign a Slack channel to receive its notifications.

You can disconnect Slack at any time from your workspace settings.

Supported resources

Recommendations are generated by deterministic analysis. No AI or machine learning is involved in deciding what to recommend. The analysis checks usage thresholds, data quality, and seasonality patterns for each resource.

Each resource type has its own page covering the specific thresholds, methodology, and what changes in the generated Terraform PR.

• EC2 Instances
• Auto Scaling Groups
• ECS Fargate
• EBS Volumes

Coming next:

• EC2 previous-gen migrations
• EC2 Graviton migrations