Skip to content

chore(byoc): add GCP priviledge documentation #6183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bojand wants to merge 3 commits into
base: main
Choose a base branch
from
+28 −1
Open

chore(byoc): add GCP priviledge documentation #6183

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c3460b6
chore(byoc): add GCP priviledge documentation
bojand May 8, 2026
f9905b4
Apply suggestions from code review
Blargian May 9, 2026
885a119
Apply suggestion from @bojand
bojand May 11, 2026
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
29 changes: 28 additions & 1 deletion .../guides/infrastructure/01_deployment_options/byoc/08_reference/02_priviledge.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
doc_type: 'reference'
---

## CloudFormation IAM roles {#cloudformation-iam-roles}
## AWS IAM roles {#aws-iam-roles}

### Bootstrap IAM role {#bootstrap-iam-role}

Expand All @@ -23,6 +23,7 @@
In addition to the `ClickHouseManagementRole` created via CloudFormation, the controller will create several additional roles.

These roles are assumed by applications running within the customer's EKS cluster:

- **State Exporter Role**
- ClickHouse component that reports service health information to ClickHouse Cloud.
- Requires permission to write to an SQS queue owned by ClickHouse Cloud.
Expand All @@ -39,3 +40,29 @@
**K8s-control-plane** and **k8s-worker** roles are meant to be assumed by AWS EKS services.

Lastly, **`data-plane-mgmt`** allows a ClickHouse Cloud Control Plane component to reconcile necessary custom resources, such as `ClickHouseCluster` and the Istio Virtual Service/Gateway.

## GCP service accounts {#gcp-service-accounts}

### Bootstrap service account {#bootstrap-service-account}

The bootstrap service account is granted project-scoped custom roles with the following permissions:

- **Common**: Baseline read and identity permissions.
- **VPC**: Manage the VPC, subnets, routing, and Private Service Connect attachments that host your BYOC infrastructure.
- **Cluster**: Manages GKE clusters and in-cluster resources.
- **Storage**: Used to manage Cloud Storage buckets used for ClickHouse backups, shared state, and monitoring data.
- **IAM Role**: Manages service accounts and custom roles inside the project. This role does not grant the ability to create service account keys, bind organization policies, or touch any resources in other projects.

Check notice on line 54 in docs/cloud/guides/infrastructure/01_deployment_options/byoc/08_reference/02_priviledge.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.Ability 

Suggestion: Try to replace ('ability to') with more precise language, unless this content is about security. See the word list for details.

Check notice on line 54 in docs/cloud/guides/infrastructure/01_deployment_options/byoc/08_reference/02_priviledge.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.Contractions 

Suggestion: Use 'doesn't' instead of 'does not'.

### Additional service accounts created by the controller {#additional-service-accounts-created-by-the-controller}

In addition to the `clickhouse-management` service account created via Terraform as part of onboarding. When you provision your first BYOC service, ClickHouse’s control plane (authenticating as `clickhouse-management`) creates additional service accounts in your project for specific in-cluster workloads. Each of these is created with a narrow, single-purpose permission set.

- **GKE node runtime identity**
- Attached to every GKE node virtual machine in your BYOC cluster.
- Used by kubelet, node-local agents, and the Cloud Operations collectors to emit logs and metrics, and by the image pulling subsystem to download container images.

Check warning on line 62 in docs/cloud/guides/infrastructure/01_deployment_options/byoc/08_reference/02_priviledge.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.OxfordComma 

Use a comma before the last 'and' or 'or' in a list of four or more items.
- **Billing scraper identity**
- Used by standalone scraper workload to collect billing telemetry.
- **Monitoring identity**
- Target identity for the monitoring stack running in your cluster. Used to read/write long-term metric storage in a GCS bucket dedicated to this deployment.
- **ClickHouse runtime management identity**
- Used by ClickHouse's runtime data-plane management controller which handles day-2 operations such as Private Service Connect endpoint management, bucket lifecycle adjustments, and service-account rotations.
Loading