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

​

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 as 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:

   Copy

   Ask AI

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

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

3. Register an admin account with Workspace Admin role.

   

4. Follow the guide to configure, you’ll need the built-in sample data 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 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.

   

   0-provider.tf

   Copy

   Ask AI

   terraform {
      required_providers {
         bytebase = {
            source  = "registry.terraform.io/bytebase/bytebase"
            version = "3.8.2"  # 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 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 changes, let’s see what environments exist.

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 Environment Configuration

Create 1-1-env-setting.tf:

# Define environments as 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 🛡️ besides the environment name.
         protected = true
      }
   }
}

​

Step 5 - Configure Environment Policies

Let’s add rollout and data protection policies, you may find more details in Environment Settings.

​

Rollout Policy

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
      roles = [
         "roles/workspaceAdmin",
         "roles/projectOwner",
         "roles/LAST_APPROVER",
         "roles/CREATOR"
      ]
   }
}

# Production - manual deployment required
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"
      ]
   }
}

• roles is the list of roles that are allowed to click the button to roll out the changes manually. Even automatic rollout is enabled, manual approval is still needed while there is any automatic check failure.

​

Data Protection Policy

Create 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:

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