Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/.node-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
22
2 changes: 1 addition & 1 deletion docs/changelog/bytebase-3-16-1.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,6 @@ import InstallUpgrade from '/snippets/install/install-upgrade.mdx';

- Harden 3.16 upgrade migration scripts to be idempotent and handle edge cases.

- **PolarDB** — Fix schema dump incorrectly including pg_bitmapindex system schema.
- **PostgreSQL** — Fix schema dump incorrectly including pg_bitmapindex system schema.

<InstallUpgrade />
105 changes: 39 additions & 66 deletions docs/tutorials/manage-general-settings-with-terraform.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -83,55 +83,22 @@ This configuration:
- Restricts users to specific email domains
- Sets your Bytebase workspace's external URL

### Step 2 - Risk Management Policies

| | |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Terraform resource | [bytebase_risk](https://registry.terraform.io/providers/bytebase/bytebase/latest/docs/resources/risk) |
| Sample file | [4-2-risk.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/tutorials/4-2-risk.tf) |

Create `4-2-risk.tf` with risk policies to assess the database operations' risk level:

```hcl 4-2-risk.tf
# Risk management policies
resource "bytebase_risk" "dml_moderate" {
title = "DML Moderate Risk"
source = "DML"
level = 200
active = true
condition = "environment_id == \"prod\" && affected_rows >= 100"
}

resource "bytebase_risk" "ddl_high" {
title = "DDL High Risk"
source = "DDL"
level = 300
active = true
condition = "environment_id == \"prod\""
}
```

Risk levels:

- **100 (LOW)**.
- **200 (MODERATE)**: DML operations in production affecting 100+ rows
- **300 (HIGH)**: All DDL operations in production

### Step 3 - Approval Flow Settings
### Step 2 - Approval Flow Settings

| | |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Terraform resource | [bytebase_setting](https://registry.terraform.io/providers/bytebase/bytebase/latest/docs/resources/setting) |
| Sample file | [4-3-approval-flow.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/tutorials/4-3-approval-flow.tf) |
| Sample file | [approval_flow.tf](https://github.com/bytebase/terraform-provider-bytebase/blob/main/examples/setup/approval_flow.tf) |

Create `4-3-approval-flow.tf` with approval flow configuration that requires multiple approvals for risky operations:
Create `4-2-approval-flow.tf` with approval flow configuration. Conditions are defined directly on each rule using CEL expressions:
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table links to a sample file named approval_flow.tf, but the tutorial instructs creating 4-2-approval-flow.tf. Consider aligning the filenames (or explicitly stating that the local filename is arbitrary and the linked file is just a reference) to reduce confusion.

Suggested change
Create `4-2-approval-flow.tf` with approval flow configuration. Conditions are defined directly on each rule using CEL expressions:
Create a local file (for example, `4-2-approval-flow.tf`) with the following approval flow configuration. Conditions are defined directly on each rule using CEL expressions:

Copilot uses AI. Check for mistakes.

```hcl 4-3-approval-flow.tf
```hcl 4-2-approval-flow.tf
# Approval flow settings
resource "bytebase_setting" "approval_flow" {
name = "settings/WORKSPACE_APPROVAL"

approval_flow {
# Rule for database changes in production with high impact
rules {
flow {
title = "Project Owner → DBA → Admin"
Expand All @@ -141,25 +108,43 @@ resource "bytebase_setting" "approval_flow" {
steps { role = "roles/workspaceDBA" }
steps { role = "roles/workspaceAdmin" }
}
conditions {
source = "DML"
level = "MODERATE"
source = "CHANGE_DATABASE"
condition = "resource.environment_id == \"prod\" && statement.affected_rows >= 100"
}

# Rule for data exports from sensitive tables
rules {
flow {
title = "Project Owner review"
description = "Need project owner approval"

steps { role = "roles/projectOwner" }
}
conditions {
source = "DDL"
level = "HIGH"
source = "EXPORT_DATA"
condition = "resource.environment_id == \"prod\" && resource.table_name == \"employee\""
}

# Fallback rule - catches all unmatched operations
rules {
flow {
title = "Fallback rule"
description = "Default approval for unmatched operations"

steps { role = "roles/workspaceDBA" }
}
condition = "true"
}
}
}
```

This creates a three-step approval flow that triggers for:
This creates approval rules that:

- DML operations with MODERATE risk level
- DDL operations with HIGH risk level
- Require three-step approval (Project Owner -> DBA -> Admin) for database changes in production affecting 100+ rows
- Require Project Owner approval for exporting data from the `employee` table in production
- Fall back to DBA approval for all other operations
Comment on lines +141 to +145
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section was updated to use approval rules/CEL conditions and no longer introduces Terraform risk policies, but the earlier "What You'll Learn" bullets still mention defining risk policies and risk-based approval flows. Please update that intro section to match the new approach (approval rules defined via CEL, without a separate risk-policy Terraform step).

Copilot uses AI. Check for mistakes.

### Step 4 - Apply Configuration
### Step 3 - Apply Configuration
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The step numbering is now inconsistent after removing the old Risk step: this section is labeled "Step 3", but the next heading is still "Step 5 - Verify Configuration". Please renumber the remaining steps so they are sequential (e.g., Apply = Step 3, Verify = Step 4) to avoid confusing readers.

Copilot uses AI. Check for mistakes.

```bash
terraform plan
Expand All @@ -174,39 +159,27 @@ terraform apply
1. Log out and try to signup which should be disabled.
1. Visit the external URL to verify it is set.

#### Risk Policies

1. Go to **CI/CD > Risks** to view risk policies.

![risks](/content/docs/tutorials/manage-general-settings-with-terraform/bb-risks.webp)
#### Approval Rules

1. You should see both "DML Moderate Risk" and "DDL High Risk" policies active.

#### Approval Flows

1. Go to **CI/CD > Custom Approval** to see the approval flow.
1. Go to **CI/CD > Custom Approval** to see the approval rules.

![custom-approval](/content/docs/tutorials/manage-general-settings-with-terraform/bb-custom-approval.webp)

1. Verify the `Project Owner → DBA → Admin` flow is configured.
1. Verify the approval rules are configured with their CEL conditions and approval flows.

#### Test the Flow

1. Go to `Project Two`, click **Database > Databases** on the left sidebar.
1. Check `hr_prod`, click **Edit Schema**, add a new table `t0`.
1. After creating the issue, you should see:

- Risk level: `DDL High`
- Approval flow: `Project Owner → DBA → Admin`
1. After creating the issue, you should see the matching approval flow applied.

![issue-risk-high](/content/docs/tutorials/manage-general-settings-with-terraform/bb-issue-risk-high.webp)

## Key Points

- **Workspace Profile**: Controls signup, domain restrictions, and external URL for your entire Bytebase workspace
- **Risk Policies**: Automatically assess database operations based on conditions like environment and affected rows
- **Approval Flows**: Define multi-step approval processes that trigger based on risk levels
- **Integration**: Risk policies and approval flows work together to ensure proper governance for database changes
- **Approval Rules**: Define conditions using CEL expressions to route database operations to the appropriate approval flow
- **First-match-wins**: Rules are evaluated in order; the first matching rule determines the approval flow

<Tip>
You can configure additional
Expand Down
Loading