Manage Bytebase Settings with Terraform

This tutorial is part of the Manage Bytebase with Terraform series:

• Part 1: Manage Databases with Terraform - Set up instances and environments
• Part 2: Manage Projects with Terraform - Organize databases into projects
• Part 3: Manage Bytebase Settings with Terraform (This one) - Configure workspace settings, approval flows, and risk management
• Part 4: Configure Database Access with Terraform (Coming next) - Set up access controls and permissions

📚 Complete examples: GitHub - Bytebase Terraform Provider

In the previous tutorials, you learned how to manage database instances and projects with Terraform. Now let’s configure Bytebase’s core settings for workspace management, approval workflows, and risk policies to establish proper governance for your database operations.

​

What You’ll Learn

Building on the previous tutorials, you’ll learn how to:

• Configure workspace profile settings for team collaboration
• Set up approval flows for database change management (also applies to queries and exports)
• Define risk management policies for operational safety
• Implement governance controls using infrastructure as code

​

Prerequisites

Before starting, ensure you have completed the previous tutorials and have:

• Bytebase running with service account configured
• Terraform provider set up and working
• Your existing main.tf file with the Terraform provider configured

​

Understanding Bytebase Settings

Bytebase provides several workspace-level settings that control how your team collaborates and manages database changes:

• Workspace Profile: Basic workspace configuration including name, logo, and branding
• Approval Flow: Custom approval workflows for database changes, data queries, and exports
• Risk Management: Policies that assess and control risky database operations

​

Step 1 - Configure Workspace Profile Settings

The workspace profile contains basic information about your Bytebase workspace that affects branding and team collaboration.

​

Query Current Workspace Profile

First, let’s see what workspace profile settings currently exist:

# Query current workspace profile settings
data "bytebase_setting" "workspace_profile" {
  name = "settings/WORKSPACE_PROFILE"
}

output "current_workspace_profile" {
  value = data.bytebase_setting.workspace_profile
}

Add this to your main.tf and run terraform apply to see the current configuration.

​

Configure Workspace Profile

Now let’s configure the workspace profile settings:

# Configure workspace profile
resource "bytebase_setting" "workspace_profile" {
  name = "settings/WORKSPACE_PROFILE"

  workspace_profile {
    # Security settings
    disallow_signup = true
    domains         = ["example.com"]
    enforce_identity_domain = true

    # External URL configuration
    external_url = "https://your-bytebase-instance.com"

    # Optional: Disable password signin to enforce SSO
    # disallow_password_signin = false
  }
}

This configuration:

• Security: Disables public signup and enforces domain restrictions
• Domain Control: Only allows users from specified domains (example.com)
• Identity Management: Enforces identity domain matching for user access
• External URL: Sets the workspace’s external URL for integrations and notifications

​

Step 2 - Set Up Approval Flows

Approval flows control how database changes are reviewed and approved before execution. These flows also apply to data queries and exports for comprehensive governance.

​

Query Current Approval Flow Settings

# Query current approval flow settings
data "bytebase_setting" "approval_flow" {
  name = "settings/WORKSPACE_APPROVAL"
}

output "current_approval_flow" {
  value = data.bytebase_setting.approval_flow
}

​

Configure Custom Approval Flow

# Approval Flow Configuration
resource "bytebase_setting" "approval_flow" {
  name = "settings/WORKSPACE_APPROVAL"

  approval_flow {
    rules {
      flow {
        title = "Project Owner -> DBA -> Admin"
        description = "Need DBA and workspace admin approval"

        steps {
          role = "roles/projectOwner"
        }

        steps {
          role = "roles/workspaceDBA"
        }

        steps {
          role = "roles/workspaceAdmin"
        }
      }

      conditions {
        source = "DML"
        level = "MODERATE"
      }

      conditions {
        source = "DDL"
        level = "HIGH"
      }
    }
  }
}

This approval flow configuration:

• Multi-step Flow: Requires sequential approvals from Project Owner → DBA → Admin
• Operation-Based Triggering: Activates for moderate-risk DML and high-risk DDL operations
• Role-Based Approvals: Uses Bytebase’s built-in role system for approval authority
• Comprehensive Coverage: Also applies to queries and exports for complete governance

​

Step 3 - Configure Risk Management Policies

Risk management policies automatically assess database operations and assign risk levels based on your organization’s policies.

​

Query Current Risk Policies

# Query existing risk policies
data "bytebase_risk_list" "all" {}

output "current_risks" {
  value = data.bytebase_risk_list.all
}

​

Define Risk Management Policies

# Risk Configuration - Aligned with Approval Flow
resource "bytebase_risk" "dml_moderate_risk" {
  title     = "DML Moderate Risk"
  source    = "DML"
  level     = 200  # MODERATE level
  active    = true
  condition = "environment_id == \"prod\" && affected_rows >= 100"
}

resource "bytebase_risk" "ddl_high_risk" {
  title     = "DDL High Risk"
  source    = "DDL"
  level     = 300  # HIGH level
  active    = true
  condition = "environment_id == \"prod\""
}

These risk policies:

• DML Moderate Risk: Triggers for production DML operations affecting 100+ rows
• DDL High Risk: Activates for all DDL operations in production environment
• Condition-Based: Uses flexible condition expressions for precise risk assessment
• Level Alignment: Risk levels (200=MODERATE, 300=HIGH) align with approval flow conditions
• Automatic Triggering: Policies automatically assess operations and trigger appropriate approval flows

​

Deploy Your Configuration

Run the Terraform commands to apply your settings:

terraform plan
terraform apply

​

Verification and Testing

After applying your Terraform configuration, verify that the settings are properly configured in Bytebase:

​

1. Verify Workspace Profile Settings

1. In Bytebase workspace, click Settings > General on the left side bar
2. Review the workspace profile settings
3. Confirm these settings match your Terraform configuration:
   • External URL is set correctly
   • Domain restrictions are enforced
   • Sign-up controls are configured as expected

​

2. Verify Approval Flow Configuration

1. In Bytebase workspace, click CI/CD > Custom Approval on the left side bar
2. Verify the “Project Owner → DBA → Admin” flow is listed
3. Confirm the flow triggers for:
   • DML operations with MODERATE level
   • DDL operations with HIGH level

​

3. Verify Risk Policies

1. In Bytebase workspace, click CI/CD > Risks on the left side bar
2. Verify your risk policies are listed and active:
   • DML Moderate Risk: For production DML with 100+ affected rows
   • DDL High Risk: For all production DDL operations
3. Ensure the condition expressions are correctly configured

​

4. Test the Workflow

Create a database change in production to verify that:

• Risk policies correctly evaluate the operation
• Approval flows are triggered based on risk level
• The complete approval process works as expected

​

Summary

You’ve successfully configured Bytebase workspace settings, approval flows, and risk policies using Terraform. Your database operations now have automated governance and approval workflows in place.

​

Next Steps

In the next tutorial, you’ll learn how to use Terraform to configure database access controls and permissions, completing your infrastructure-as-code setup for Bytebase.

For more advanced configurations, check the Terraform Provider examples on GitHub.