Skip to content

docs: improve GCP service account authentication documentation #839

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.

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

Merged
merged 1 commit into from
Aug 21, 2025

Conversation

d-bytebase
Copy link
Contributor

Summary

  • Rewrote GCP Secret Manager documentation to use the most secure authentication method (GCE VM service accounts)
  • Created unified service account setup section that works for both GCE and GKE deployments
  • Significantly improved documentation clarity and reduced wordiness

Changes

Security Improvements

  • Primary method now uses GCE VM service accounts - eliminates need for service account keys
  • Added GKE Workload Identity support - secure authentication for Kubernetes deployments
  • Moved service account keys to "Alternative" section with clear warnings about security risks

Documentation Structure

  • Created shared Prerequisites section - eliminates duplication between Cloud SQL and Secret Manager
  • Consolidated to single bytebase service account - simpler than managing multiple accounts
  • Removed 7 obsolete screenshots - replaced with clear text instructions

Technical Corrections

  • Fixed IAM user creation - now correctly shows gcloud/Console methods (not SQL commands)
  • Corrected username formats:
    • MySQL: bytebase (service account name only)
    • PostgreSQL: bytebase@PROJECT_ID.iam (without .gserviceaccount.com suffix)
  • Updated all Google Cloud documentation links - verified all links are valid

Content Improvements

  • Reduced word count by ~50% while maintaining clarity
  • Added comprehensive references to official Google Cloud documentation
  • Improved step-by-step instructions with clearer navigation paths

Test Plan

  • Verified all documentation links are valid and accessible
  • Checked technical accuracy against Google Cloud documentation
  • Ensured internal anchor links work correctly
  • Confirmed deleted images are not referenced elsewhere

🤖 Generated with Claude Code

- Rewrite GCP Secret Manager section to use GCE VM service accounts (most secure method)
- Create shared Prerequisites section for service account setup (GCE and GKE)
- Consolidate to single 'bytebase' service account instead of multiple accounts
- Add GKE with Workload Identity support
- Remove duplicate content between Cloud SQL and Secret Manager sections
- Fix IAM user creation methods (gcloud/Console, not SQL commands)
- Correct username formats for MySQL and PostgreSQL
- Reduce documentation wordiness by ~50%
- Remove 7 obsolete screenshot images
- Add comprehensive Google Cloud documentation references

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@Copilot Copilot AI review requested due to automatic review settings August 20, 2025 14:54
Copy link

vercel bot commented Aug 20, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
bytebase-com Ready Ready Preview Comment Aug 20, 2025 2:56pm

Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull Request Overview

This PR improves GCP service account authentication documentation by prioritizing secure authentication methods and consolidating redundant content. The changes make the documentation more secure, clearer, and easier to follow.

Key changes:

  • Restructured to use GCE VM service accounts as the primary authentication method instead of service account keys
  • Created unified Prerequisites section that eliminates duplication between Cloud SQL and Secret Manager configurations
  • Significantly reduced content length while improving clarity and removing obsolete screenshots

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

Copy link

📝 Broken Links Check Report

Note: Entries under /api-reference/ are likely false positives and can be ignored.

The following is the output from the broken links check:

found 16 broken links in 9 files

integrations/api/audit-log.mdx
 ⎿  /api-reference/auditlogservice/post-v1auditlogs:search

integrations/api/authentication.mdx
 ⎿  /api-reference/authservice/post-v1authlogin

integrations/api/data-classification.mdx
 ⎿  /api-reference/settingservice/patch-v1settings
 ⎿  /api-reference/databaseservice/patch-v1instances-databases

integrations/api/issue.mdx
 ⎿  /api-reference/issueservice/post-v1projects-issues

integrations/api/permission.mdx
 ⎿  /api-reference/workspaceservice/get-v1workspaces-:getIamPolicy
 ⎿  /api-reference/projectservice/get-v1projects-:getIamPolicy
 ⎿  /api-reference/roleservice/get-v1roles
 ⎿  /api-reference/userservice/get-v1users
 ⎿  /api-reference/groupservice/get-v1groups

integrations/api/plan.mdx
 ⎿  /api-reference/planservice/post-v1projects-plans
 ⎿  /api-reference/sheetservice/post-v1projects-sheets

integrations/api/release.mdx
 ⎿  /api-reference/releaseservice/post-v1projects-releases

integrations/api/rollout.mdx
 ⎿  /api-reference/rolloutservice/post-v1projects-rollouts

integrations/api/sql-review.mdx
 ⎿  /api-reference/releaseservice/post-v1projects-releases:check
 ⎿  /api-reference/sqlservice/post-v1sqlcheck

@d-bytebase d-bytebase merged commit 5a28bd7 into main Aug 21, 2025
5 checks passed
@d-bytebase d-bytebase deleted the docs/gcp-service-account-improvements branch August 21, 2025 00:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants