Manage Environments with Terraform

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

This tutorial series uses separate Terraform files for better organization. Files are numbered by tutorial part and sub-step (e.g., 1-1-env-setting.tf, 1-2-env-policy-rollout.tf for Part 1, 2-instances.tf for Part 2, etc.). Terraform automatically handles dependencies between files.

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

Run Bytebase in Docker:

docker run --rm --init \
  --name bytebase \
  --publish 8080:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:latest

Access Bytebase at http://localhost:8080.
Register an admin account with Workspace Admin role.
Complete the setup to configure Bytebase, you’ll need to select use built-in sample for this tutorial.
(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

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

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

0-provider.tf

terraform {
   required_providers {
      bytebase = {
         source  = "registry.terraform.io/bytebase/bytebase"
         version = "3.8.6"  # 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

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

Initialize Terraform

Update 0-provider.tf with your service account key.
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:

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:

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

When no rollout policy is found for an environment, Bytebase applies a default rollout policy with the following checkers:

Required Issue Approval: Changes must be approved before deployment
Plan Check Enforcement: SQL plan checks must pass (errors only)

You can explicitly configure these policies using Terraform. Create 1-2-env-policy-rollout.tf:

1-2-env-policy-rollout.tf

# Test environment - automatic deployment with default checkers
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
      roles = [
         "roles/workspaceAdmin",
         "roles/projectOwner",
         "roles/LAST_APPROVER",
         "roles/CREATOR"
      ]

      # Default checkers (explicitly configured)
      checkers {
         required_issue_approval = true
         required_status_checks {
            plan_check_enforcement = "ERROR_ONLY"  # Block on errors only
         }
      }
   }
}

# Production - manual deployment with stricter checks
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",
         "roles/LAST_APPROVER",
         "roles/CREATOR"
      ]

      # Enforce all plan checks (errors and warnings)
      checkers {
         required_issue_approval = true
         required_status_checks {
            plan_check_enforcement = "STRICT"  # Block on both errors and warnings
         }
      }
   }
}

Key Configuration Options:

automatic: When true, changes deploy automatically after approval. When false, requires manual click to deploy.
roles: List of roles allowed to manually deploy changes. Required even with automatic rollout, as manual approval is needed when checks fail.
checkers.required_issue_approval: When true, requires issue approval before rollout.
checkers.required_status_checks.plan_check_enforcement: Controls SQL plan check enforcement:
- PLAN_CHECK_ENFORCEMENT_UNSPECIFIED: Allow rollout regardless of plan check results (no enforcement)
- ERROR_ONLY: Block rollout only when plan check finds errors (default)
- STRICT: Block rollout when plan check finds errors or warnings (stricter for production)

Data Protection Policy


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

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

1-3-env-policy-data.tf

# Prevent copying data in SQL Editor from production
resource "bytebase_policy" "disable_copy_data_policy_prod" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[1].name
   type       = "DISABLE_COPY_DATA"

   disable_copy_data_policy {
      enable = true  # Block data copy
   }
}

# Restrict SQL execution in SQL Editor from production
resource "bytebase_policy" "data_source_query_policy_prod" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[1].name
   type       = "DATA_SOURCE_QUERY"

   data_source_query_policy {
      restriction  = "RESTRICTION_UNSPECIFIED"
      disallow_ddl = true  # No schema changes via SQL Editor
      disallow_dml = true  # No data changes via SQL Editor
   }
}

Here data protection policy is only applied to the Prod environment. Which means in Test environment, by default, users may execute DDL and DML statements or copy data directly in SQL Editor.
restriction controls access to the data source:
- RESTRICTION_UNSPECIFIED: Admin data source is allowed.
- DISALLOW: Admin data source is completely disallowed.
- FALLBACK: Prefer the read-only data source; use admin only if read-only is not configured.

Step 6 - Apply Configuration

Apply all configurations:

terraform plan
terraform apply

Verify in Bytebase:

Go to Environments.
Check that Prod shows a shield icon (protected).
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

UI-Driven Workflow

GitOps Workflow

Database Access Control

Terraform

Integration

Manage Environments with Terraform

What You’ll Learn

Prerequisites

Step 1 - Setup

Install Terraform

Start Bytebase

Explore Current Environments

Step 2 - Configure Terraform Provider

Set up the Provider

Create a Service Account

Initialize Terraform

Step 3 - Inspect Current Environments

Step 4 - Define the Environment Configuration

Step 5 - Configure Environment Policies

Rollout Policy

Data Protection Policy

Step 6 - Apply Configuration

Summary and Next Steps

Part 2: Manage Databases with Terraform

UI-Driven Workflow

GitOps Workflow

Database Access Control

Terraform

Integration

​What You’ll Learn

​Prerequisites

​Step 1 - Setup

​Install Terraform

​Start Bytebase

​Explore Current Environments

​Step 2 - Configure Terraform Provider

​Set up the Provider

​Create a Service Account

​Initialize Terraform

​Step 3 - Inspect Current Environments

​Step 4 - Define the Environment Configuration

​Step 5 - Configure Environment Policies

​Rollout Policy

​Data Protection Policy

​Step 6 - Apply Configuration

​Summary and Next Steps

Part 2: Manage Databases with Terraform

What You’ll Learn

Prerequisites

Step 1 - Setup

Install Terraform

Start Bytebase

Explore Current Environments

Step 2 - Configure Terraform Provider

Set up the Provider

Create a Service Account

Initialize Terraform

Step 3 - Inspect Current Environments

Step 4 - Define the Environment Configuration

Step 5 - Configure Environment Policies

Rollout Policy

Data Protection Policy

Step 6 - Apply Configuration

Summary and Next Steps