Skip to content
Terrateam
If you like Terrateam, give us a star 🌟 on GitHub.

Migrating from Terraform Cloud

Terraform Cloud (TFC) is HashiCorp’s managed service offering remote state management, execution, and collaboration features via a web UI. Terrateam is an open-source GitOps CI/CD platform tightly integrated with GitHub for automating Terraform workflows. Rather than a separate TFC interface, Terrateam manages infrastructure changes through GitHub pull requests and GitHub Actions.

Pre-Migration Planning

A successful migration starts with a thorough plan. Begin by taking an inventory of your TFC setup:

  1. List Organizations and Workspaces

    • Note each workspace’s purpose (project, environment, etc.) and the Terraform code repository/directory it connects to.
    • Record the Terraform version and any relevant workspace settings.

  2. State Location and Names

    • TFC stores state within each workspace. Note each workspace name, since it often forms part of the key path if you use an S3-like backend after migration.

  3. Variables and Secrets

    • Document all TFC workspace variables, both sensitive and non-sensitive. Sensitive values can’t be viewed directly in TFC if you never saved them elsewhere, so plan to regenerate or locate them securely.

  4. Workflow Triggers

    • Understand how runs are triggered (automatic via VCS push, manual in UI, CLI-driven, etc.). If you rely on TFC’s run tasks or webhooks, decide how you’ll replicate them with Terrateam.

  5. Compliance/Approvals

    • Check if TFC used Sentinel, manual approvals, or RBAC. Decide how you’ll replicate or improve those controls in Terrateam using GitHub reviews, built-in Terrateam features like Access Controls or Apply Requirements, OPA, or other policy tools.

  6. Choose a New Backend

    • Terrateam doesn’t host your state. Common choices include AWS S3 (+ DynamoDB for locking), Azure Blob, GCS, or another remote backend. Create the backend, ensuring versioning/encryption for compliance.

  7. Security, Governance, and Secrets

    • Evaluate how you’ll store secrets going forward (e.g. GitHub Secrets). Review how you’ll replicate TFC’s role/team restrictions, usually via GitHub team permissions and .terrateam/config.yml access controls.

Compile these into a migration checklist for each workspace so nothing (like a crucial API key) is overlooked.

Migrating Terraform State to S3

Below is an example migration to AWS S3. If you use other cloud backends, adapt accordingly:

  1. Export State from TFC

    Terminal window
    terraform login            # authenticate with TFC
    terraform state pull > terraform.tfstate

    This pulls the current TFC state into a local file.

  2. Set Up S3

    • Create an S3 bucket (e.g., mycompany-terraform-state) with versioning and encryption.

  3. Update Terraform Backend

    • In your Terraform config (backend.tf or within terraform { backend "s3" { ... } }): 
      terraform {
        backend "s3" {
          bucket         = "mycompany-terraform-state"
          key            = "prod/network/terraform.tfstate"
          region         = "us-west-2"
          dynamodb_table = "terraform-state-locks"
          encrypt        = true
        }
      }

  4. Migrate the State

    • Run terraform init -migrate-state, and approve the migration.

  5. Verify

    • Run terraform plan to confirm no changes.
    • Repeat for each workspace, adjusting the key path accordingly.

Handling Secrets & Environment Variables

  1. Identify Secrets in TFC

    • Non-sensitive values can be viewed in the TFC UI.
    • Sensitive variables are masked. If you didn’t store them elsewhere, you may need to regenerate new credentials or rotate them accordingly.

  2. Storing Secrets in GitHub

    • GitHub Secrets: Store sensitive credentials (AWS keys, DB passwords, etc.).
    • GitHub Variables: For non-sensitive configs.
    • GitHub Environments: For dev/staging/prod scopes.

Terrateam automatically injects these secrets as environment variables during plan/apply. Any variable prefixed with TF_VAR_ is recognized by Terraform as an input variable.

Use OIDC

Rather than static credentials, set up Terrateam to use OIDC so it can assume roles in AWS/GCP/Azure without storing long-lived secrets in GitHub.

Logs

Make sure your Terraform or custom scripts don’t accidentally print sensitive information. Terrateam will mask matches for any secrets defined in GitHub Secrets and in your .terrateam/config.yml if they are marked as sensitive.

Execution & Workflow Migration

  1. Set Up Terrateam

  2. Mirror Existing TFC Workflows

    • Automatic Plan on PR: Terrateam comments plan results in the PR.
    • Manual Approvals: Instead of TFC’s “Confirm & Apply,” you comment terrateam apply on the PR, or you configure merges to trigger an apply.
    • Multiple Environments: If TFC used multiple workspaces, replicate that in .terrateam/config.yml with separate directories, tags, or CLI workspaces.

  3. Configure .terrateam/config.yml

    • Directories or Branches to represent each environment.
    • Apply Requirements: e.g., require PR approval, successful checks.
    • Access Control: Restrict who can run applies in different environments.

  4. Testing

    • Open a test PR, ensure plan output shows up, confirm secrets are recognized, then do a test terrateam apply.
    • Verify it references the correct new S3 backend.

Compliance, Logging, and Auditability

Policy Enforcement

  • Sentinel -> OPA/Checkov: Rewrite or replicate TFC’s Sentinel policies with OPA/Checkov. Terrateam can automatically run these checks on each pull request.

Approvals

  • GitHub code reviews and branch protections can replace TFC’s manual apply. Terrateam can also require certain statuses or approvals from GitHub identities (teams, users, roles).

Audit Logging

  • GitHub PR History: Each plan/apply is commented in the PR.
  • Terrateam Audit Trail: Terrateam keeps an audit trail in the UI.
  • GitHub Actions Logs: Each run is a job log you can store or export.

Cost Estimation & Other Checks

  • Terrateam provides cost estimates in PRs.
  • Additional scripts or checks can be added in .terrateam/config.yml using custom workflows and hooks.

Custom Workflows & Automation

Terrateam is highly configurable and can fit into any workflow.

Hooks

Run scripts pre or post plan/apply to integrate policy checks, custom validations, notifications, etc.

Parallel or Layered Runs

For multiple directories, run them in parallel or define dependencies so certain directories apply before others.

Branching Strategies

Automate multi-environment setups using branch naming or tags referencing directories.

Notifications

Post Slack or Teams messages on plan/apply success/failure.

Monorepo vs Multiple Repos

If TFC used multiple repos, you can replicate that or consolidate into one repository with subdirectories.

Validating the Migration

Test in a Non-Prod Environment

Try it out on dev/staging. Compare TFC plan output to Terrateam if needed.

Compare Terraform State

Run terraform state list to ensure it matches your resources in the new backend.

Check Secrets

Confirm GitHub secrets are set properly and recognized in the workflow.

Check Drift

If TFC wasn’t up-to-date, Terrateam might highlight differences. Evaluate carefully.

Best Practices for Enterprise Adoption

  • Security & Access Control: Use GitHub teams, code owners, and Terrateam’s access_control or production safety.
  • Policy & Governance: Replace Sentinel with OPA or Checkov, use branch protection for merges, and configure apply_requirements.
  • Secrets Management: Use ephemeral credentials (OIDC) where possible. If static secrets are required, store them in GitHub Secrets or an external vault.
  • Monitoring & Audits: Export logs to a central store. Use Terrateam’s dashboard for a consolidated view of runs.
  • Training & Documentation: Provide internal docs or a short tutorial so your team knows how to open PRs, read plan outputs, and apply changes with Terrateam’s commands.

Final Steps and Next Actions

  1. Decommission TFC

    • After all workspaces are migrated and validated, remove or disable them in TFC, and cancel any paid subscriptions.

  2. Optimize Terrateam

    • Refine your .terrateam/config.yml based on real usage: parallel runs, environment-based tags, advanced hooks, etc.

  3. Continuous Improvement

    • Monitor runs, gather feedback, and add improvements, like OPA policies, additional validations, or new environment setups.

  4. Wrap-Up

    • You’ve successfully transitioned to a more GitOps-style approach with Terrateam. All infra changes now go through GitHub pull requests, providing better transparency, collaboration, and control.

Support

Need help migrating? Reach out via Slack or email.