manage-environments-with-terraform.mdx

title	Manage Environments with Terraform
author	Adela
updated_at	2025/07/15 21:15
tags	Tutorial
integrations	Terraform
category	Integration
featured	true
level	Intermediate
estimated_time	30 mins

import TerminalDockerRunVolume from '/snippets/install/terminal-docker-run-volume.mdx'; import TerraformGitHubSample from '/snippets/tutorials/terraform-github-sample.mdx';

This tutorial is part of the Bytebase Terraform Provider series:

• Part 1: Manage Environments with Terraform 👈
• Part 2: Manage Databases with Terraform - Register database instances
• Part 3: Manage Projects with Terraform - Organize databases into projects
• Part 4: Manage Bytebase Settings with Terraform - Configure workspace profile and approval policies
• Part 5: Manage SQL Review Rules with Terraform - Define SQL review policies
• Part 6: Manage Users and Groups with Terraform - Configure users and groups
• Part 7: Manage Database Access Control with Terraform - Grant database permissions
• Part 8: Manage Data Masking with Terraform - Protect sensitive data

What You'll Learn

In this tutorial, you'll use Terraform to manage Bytebase environments programmatically. You'll learn how to:

• Define environments (Test, Prod) with different protection levels
• Configure automatic vs manual deployment policies
• Set up data access restrictions for production
• Manage everything via Infrastructure as Code (IaC)

Prerequisites

Before starting this tutorial, ensure you have:

• Docker: Install Docker to run Bytebase
• Terraform: Install Terraform (version 1.0+)
• Bytebase Enterprise Plan (optional): For advanced features

Step 1 - Setup

Install Terraform

Follow the official Terraform installation guide.

Start Bytebase

1. Run Bytebase in Docker:

2. Access Bytebase at http://localhost:8080.

3. Register an admin account with Workspace Admin role.

   

4. Complete the setup to configure Bytebase, you'll need to select use built-in sample for this tutorial.

   

5. (Optional) After logging into Bytebase, activate official or trial license. Some features require the Enterprise Plan.

   

Explore Current Environments

Navigate to Environments in Bytebase. You'll see two default environments: Test and Prod. We’ll manage these environments using Terraform next.

Step 2 - Configure Terraform Provider

Set up the Provider

1. Create a new folder learn-terraform-bytebase and navigate to it.

2. Create 0-provider.tf, visit Terraform Bytebase Provider, click USE PROVIDER and copy the configuration.

   

   terraform {
      required_providers {
         bytebase = {
            source  = "registry.terraform.io/bytebase/bytebase"
            version = "3.17.1"  # Check for latest version
         }
      }
   }
   
   provider "bytebase" {
      service_account = "tf@service.bytebase.com"
      service_key     = "<Your service key>"      # We'll get this next
      url             = "http://localhost:8080"    # Your Bytebase URL
   }

Create a Service Account

1. In Bytebase, go to IAM & Admin > Users & Groups.
2. Click + Add User and create a service account:
   • Type: Service Account
   • Email: tf@service.bytebase.com
   • Roles: Workspace Admin
3. Copy the generated Service Key.

Initialize Terraform

1. Update 0-provider.tf with your service account key.
2. Initialize Terraform:

terraform init

You should see: "Terraform has been successfully initialized!"

Step 3 - Inspect Current Environments

Before making any changes, let's see what environments currently exist.

Terraform data source	bytebase_environment
Sample file	1-0-list-env.tf

Create 1-0-list-env.tf:

# Read current environment settings from Bytebase
data "bytebase_setting" "environments" {
   name = "settings/ENVIRONMENT"
}

# Display all environments
output "all_environments" {
   value = data.bytebase_setting.environments
}

Run these commands:

terraform plan
terraform apply

You'll see the existing test and prod environments.

Step 4 - Define the Environment Configuration

Terraform resource	bytebase_setting
Sample file	1-1-env-setting.tf

Create 1-1-env-setting.tf:

# Define environments via Infrastructure as Code
resource "bytebase_setting" "environments" {
   name = "settings/ENVIRONMENT"

   environment_setting {
      # Test environment - for development
      environment {
         id        = "test"
         title     = "Test"
         protected = false
      }

      # Production environment - needs protection
      environment {
         id        = "prod"
         title     = "Prod"
         ## Bytebase will attach a shield icon 🛡️ beside the environment name.
         protected = true
      }
   }
}

Step 5 - Configure Environment Policies

Let's add rollout and data protection policies, for more details, see: Environment Policy and Rollout Policy.

Rollout Policy

Terraform resource	bytebase_policy
Sample file	1-2-env-policy-rollout.tf

The rollout policy controls whether changes deploy automatically and which roles can manually roll out. Create 1-2-env-policy-rollout.tf:

# Test environment - automatic deployment
resource "bytebase_policy" "rollout_policy_test" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[0].name
   type       = "ROLLOUT_POLICY"

   rollout_policy {
      automatic = true  # Deploy changes automatically when all checks pass
      roles = [
         "roles/workspaceAdmin",
         "roles/projectOwner"
      ]
   }
}

# Production - manual deployment
resource "bytebase_policy" "rollout_policy_prod" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[1].name
   type       = "ROLLOUT_POLICY"

   rollout_policy {
      automatic = false  # Require manual deployment
      roles = [
         "roles/workspaceAdmin",
         "roles/projectOwner"
      ]
   }
}

Key Configuration Options:

• automatic: When true, changes deploy automatically after all checks pass. When false, requires manual click to deploy.
• roles: List of roles allowed to manually roll out changes. Required even with automatic rollout, as manual approval is needed when checks fail.

Data Protection Policy

Terraform resource	bytebase_policy
Sample file	1-3-env-policy-data.tf

Create 1-3-env-policy-data.tf:

# Restrict SQL Editor data access on production
resource "bytebase_policy" "query_data_policy_prod" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[1].name
   type       = "DATA_QUERY"

   query_data_policy {
      maximum_result_rows     = 1000   # Cap rows returned per query
      disable_copy_data       = true   # Block copy-to-clipboard
      disable_export          = true   # Block export
      allow_admin_data_source = false  # Force read-only data source when configured
   }
}

• The policy is only applied to the Prod environment. In Test, the defaults apply (no row cap, copy/export allowed, admin data source usable).

• allow_admin_data_source controls access to the data source:

  • true: Admin data source is allowed.
  • false: When a read-only data source is configured, users are forced onto it; otherwise falls back to admin.

Step 6 - Apply Configuration

Apply all configurations:

terraform plan
terraform apply

Verify in Bytebase:

1. Go to Environments.
2. Check that Prod shows a shield icon (protected).
3. Click each environment to see the configured policies.

Summary and Next Steps

You've successfully configured Bytebase environments using Terraform! Your setup now includes:

• Test environment: Unprotected with automatic deployment for fast development
• Prod environment: Protected with manual deployment and data restrictions for safety

<Card title="Part 2: Manage Databases with Terraform" icon="arrow-right" href="/tutorials/manage-databases-with-terraform" horizontal