[tooky]

Summary

Until now, parts of the Cloud Capture GCP tabs only made sense if you'd already read the AWS tab. For example, the workload identity checks were defined as the "counterpart" of the AWS trust policy and external ID, and the setup steps said "GCP has no equivalent of phone-home". This PR rewrites the GCP content to explain each mechanism in GCP terms first. Where an AWS comparison still helps, it follows as a short optional aside. The AWS tab content is unchanged.

Security page

• The intro above the tabs is now cloud-neutral: it describes "an identity in your cloud account" rather than an IAM role with an assume-trust policy.
• The GCP trust explanation now states the two checks the pool makes (Kosli AWS account, then your organization's Kosli-side role), with the AWS comparison as an aside.
• The kosli_role_name and attribute_condition comments in the Terraform are reworded the same way.
• "How Kosli isolates tenants" is split into AWS and GCP tabs. The AWS text moved into its tab without edits.
• "Changing security permissions" no longer assumes an IAM role.
• GKE permissions now match how snapshots actually work. The section assumed Cloud Capture calls each cluster's Kubernetes API. It reads pods from Cloud Asset Inventory, the same way kosli snapshot gke does. So:
  • the note saying clusters with a private-only control plane can't be snapshotted is removed
  • the custom role swaps container.namespaces.* and container.pods.* for cloudasset.assets.listContainerPod and serviceusage.services.use
  • the Terraform now enables cloudasset.googleapis.com
  • the security-review comment explains why a custom role is used rather than roles/cloudasset.viewer (which can also list k8s.io/Secret)

Getting started page, GCP tab:

 ### Prepare your environment
-  ...Kubernetes clusters...
+  ...GKE clusters...
-  "phone-home" paragraph
+  <Steps>
+    Download the Terraform configuration
+    Deploy with Infrastructure Manager   # gcloud apply command, copied from the security page
+    Share the outputs with Kosli         # names the two outputs
+  </Steps>
 ### Enable Cloud Capture    # now names the two values you share

The overview's first step now says "Grant Kosli read-only access to your cloud accounts" rather than "Create an IAM role".

Still to do

The items below weren't confirmed when this PR opened, so the pages carry {/* TODO */} comments for them. These are hidden on the rendered site.

• Does the Terraform downloaded from the Settings page come pre-filled with the Kosli AWS account ID and role name? If not, where does the user get them? Resolved: Not pre-filled; both pages now point to the Cloud Capture section of the Settings page.
• Where does the user submit the two outputs: a form in the Kosli UI, or Customer Success? Resolved: Registered through the Kosli API's cloud accounts endpoint. A TODO remains to link it once it's in the API reference.
• Does Cloud Capture still discover clusters with container.clusters.list and container.clusters.get? If discovery also goes through Cloud Asset Inventory, those two permissions and the discovery comment in the role need changing.

Also worth checking:

• Does gcloud infra-manager deployments describe actually show Terraform outputs? They may only appear on the revision (gcloud infra-manager revisions describe, under applyResults.outputs). The wording is unchanged from before, but it's now presented as a step users follow. Resolved: No. Both pages now use revisions describe on the latest revision.
• The GCP Terraform on the security page has no source file in this repo, capture-managed or cloud-capture. Wherever the Settings-page download is generated, it needs the same changes: the reworded comments, the Cloud Asset permissions, and enabling the Cloud Asset API.

Evidence

• pytest tests/: 59 passed.
• mint dev: both pages render with the new tabs, steps and code blocks, and the TODO comments don't appear.
• mint broken-links: one broken link, in tutorials/working_with_controls.mdx, which this PR doesn't touch.

Merge Danger

Door: two-way. This is a docs-only change to two BETA pages and can be reverted cleanly.
Blast Radius: two pages under Administration ▸ Cloud Capture. No navigation, redirect or anchor changes. Customers who already followed the old GKE permissions would have a role without the Cloud Asset permissions, but GCP support is still marked "coming soon".

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Oct 22, 2026, 12:46 PM

[claude]

Claude finished @tooky's task in 2m 24s —— View job

---

Follow-up review complete

• Fetch previous review comments
• Diff BEFORE..AFTER and map findings to changed lines (BEFORE wasn't reachable locally — fell back to gh pr diff, scoped to hunks touched by the PR's three commits 8839b3f, e5bec94, c6a5dfc)
• Classify each previous finding: resolved / partially addressed / not addressed
• Close resolved inline threads
• Flag any new bugs/regressions introduced by the fix (inline) — none found
• Post summary comment

Result

Both previously raised findings are resolved:

1. Claude's finding that gcloud infra-manager deployments describe doesn't surface Terraform outputs — fixed in all three locations (getting_started.md step, security.md prose, security.md Terraform comment) by switching to gcloud infra-manager revisions describe against the latest revision's applyResults.outputs.
2. mbevc1's finding about the undocumented "eventually consistent" freshness claim for GKE permissions — the sentence was removed.

Closed all 4 corresponding inline threads with confirmation. No new bugs, security issues, or regressions found in the newly changed lines (custom role permissions, Cloud Asset API enablement, the new AWS/GCP tenant-isolation tabs, and the restructured <Steps>), so 0 new inline comments were posted.

Full status posted as a summary comment.

[gsavage]

To answer a couple of the open questions- the Terraform code will not be prepopulated with the correct values; the values are visible in the Kosli UI only (in the new settings page).

We have a new API endpoint for registering Cloud accounts, so they "let us know" by making f a POST request there

[tooky]

@gsavage thanks. Both pages now say the inputs come from the Settings page and that you register the outputs through the cloud accounts endpoint. Is there an API reference link or example call I can add?

[claude]

Follow-up review: previous findings vs. latest commits

Checked the three previous review threads against the newest commits (8839b3f, e5bec94, c6a5dfc):

1. Claude — gcloud infra-manager deployments describe doesn't return Terraform outputs (getting_started.md step, security.md:~144, security.md Terraform comment): Resolved. All three spots now correctly point to the deployment's latest revision (applyResults.outputs) via gcloud infra-manager revisions describe, and getting_started.md spells out the full two-command sequence. Closed the three inline threads.
2. mbevc1 — no documented freshness guarantee for the "eventually consistent" claim (security.md GKE permissions): Resolved. The sentence claiming Cloud Asset Inventory can lag behind recent pod changes has been removed. Closed the inline thread.

No new bugs, security issues, or regressions found in the lines touched by these commits (GKE custom-role permissions, cloudasset.googleapis.com enablement, the AWS/GCP tenant-isolation tabs, and the restructured <Steps> in both pages) — 0 new inline comments.