Skip to content

docs: fix Helm chart V2 GCS storage configuration #68638

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

Jump to bottom
Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: fix Helm chart V2 GCS storage configuration #68638

wants to merge 3 commits into from
+122 −24

Conversation

@devin-ai-integration
Copy link
Contributor

What

Fixes GCS storage configuration documentation for Helm chart V2 across all platform documentation. The documentation contained two critical errors that would cause GCS storage to fail:

  1. Wrong secret field name: Documentation showed secretName but the chart actually uses storageSecretName for GCS external secrets
  2. Double base64 encoding: Documentation instructed users to provide base64-encoded credentials, but the chart uses stringData which automatically base64-encodes, causing double encoding

Fixes #68178
Fixes #48842

How

Updated four documentation files to correct the GCS configuration examples:

  1. Removed incorrect secretName: "" field that doesn't apply to GCS
  2. Changed credentialsJson: <base64-encoded> to credentialsJson: <raw-json-content> with explicit comment
  3. Added documentation for two options:
    • Option 1: Provide credentials inline in values.yaml (stored in auto-generated Kubernetes secret)
    • Option 2: Use storageSecretName to reference an external Kubernetes secret
  4. In storage.md, explicitly changed secretName → storageSecretName for the external secret example

Review guide

  1. chart-v2-community.mdx (lines 227-258) - Community upgrade guide GCS section
  2. chart-v2-enterprise.mdx (lines 239-270) - Enterprise upgrade guide GCS section
  3. storage.md (lines 153-164) - Storage integration page V2 example
  4. implementation-guide.md (lines 558-575) - Enterprise implementation guide V2 example

Key things to verify:

  • Technical accuracy: Does Helm chart V2 actually use storageSecretName (not secretName) for GCS? ✅ Verified by checking templates - all services use .Values.global.storage.storageSecretName
  • Does the chart expect raw JSON (not base64)? ✅ Verified - templates use stringData which auto-encodes
  • Are the two options clearly explained and correct?
  • Were any historical versioned docs accidentally modified? ✅ Only modified files in /docs/platform/, not /docusaurus/platform_versioned_docs/

User Impact

Positive impact:

  • Users can now successfully configure GCS storage for Helm chart V2 without encountering double-encoding errors or wrong secret field issues
  • Clear documentation of both inline credentials and external secret approaches

No negative side effects - this is documentation-only

Can this PR be safely reverted and rolled back?

  • YES 💚

Link to Devin run: https://app.devin.ai/sessions/a2787ec2044e4bdeaa5b64574c642e6b
Requested by: ian.alton@airbyte.io

@devin-ai-integration @ian-at-airbyte
docs: fix Helm chart V2 GCS storage configuration
09ebba0 
- Fix secretName -> storageSecretName for GCS external secrets
- Clarify credentialsJson should be raw JSON, not base64-encoded
- Add documentation for both inline and external secret options
- Affects: chart-v2-community, chart-v2-enterprise, storage integration, and implementation guide

Fixes #68178, #48842

Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>
@devin-ai-integration
Copy link
Contributor Author

Original prompt from ian.alton@airbyte.io 
@Devin I'd like to ensure that the documentation in this page <https://docs.airbyte.com/platform/next/deploying-airbyte/chart-v2-community#update-your-valuesyaml-file> is still accurate to the current state of the helm chart V2 (2.0.18 or 2.0.19 I think).

Specifically check the Google Cloud storage portion, but any divergence between the docs and that helm chart should be investigated.
Thread URL: https://airbytehq-team.slack.com/archives/D08FX8EC9L0/p1761329728369169?thread_ts=1761329728.369169

Preview of a link: https://docs.airbyte.com/platform/next/deploying-airbyte/chart-v2-community#update-your-valuesyaml-file
> # docs.airbyte.com
> ## [Upgrade to Helm chart V2 (Core) | Airbyte Docs](https://docs.airbyte.com/platform/next/deploying-airbyte/chart-v2-community#update-your-valuesyaml-file)
> Airbyte has upgraded its Helm chart to a new version called "V2." Using Helm chart V2 is currently optional. At some future date the V2 Helm chart will become the standard, so we advise that you upgrade your existing deployment to use the new chart before the transition. If you're a new Airbyte user, you can skip the upgrade altogether and start with the new chart.

@devin-ai-integration
Copy link
Contributor Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@github-actions
Copy link
Contributor

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Helpful Resources

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions.
    • You can specify a custom changelog by passing changelog. Example: /bump-version changelog="My cool update"
    • Leaving the changelog arg blank will auto-populate the changelog from the PR title.
  • /run-cat-tests - Runs legacy CAT tests (Connector Acceptance Tests)
  • /build-connector-images - Builds and publishes a pre-release docker image for the modified connector(s).
  • JVM connectors:
    • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
      Example: /update-connector-cdk-version connector=destination-bigquery
    • /bump-bulk-cdk-version type=patch changelog='foo' - Bump the Bulk CDK's version. type can be major/minor/patch.
  • Python connectors:
    • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
    • /poe source example lock - Alias for /poe connector source-example lock.
    • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
    • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.

📝 Edit this welcome message.

@github-actions
Copy link
Contributor

github-actions bot commented Oct 24, 2025 •
edited
Loading

Deploy preview for airbyte-docs ready!

✅ Preview
https://airbyte-docs-cok4lmeyx-airbyte-growth.vercel.app

Built with commit 3e63021.
This pull request is being automatically deployed with vercel-action

ian-at-airbyte
ian-at-airbyte reviewed Oct 24, 2025
View reviewed changes
docs/platform/deploying-airbyte/integrations/storage.md
storage:
type: "GCS"
secretName: airbyte-config-secrets
storageSecretName: airbyte-config-secrets # Use storageSecretName (not secretName) for GCS external secrets
Copy link
Contributor

Choose a reason for hiding this comment

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

I assume this should also be applied to the helm chart V1 sample to resolve #48842

docs/platform/deploying-airbyte/chart-v2-community.mdx
```yaml
global:
storage:
secretName: ""
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this not used for anything anymore in s3/azure? I'm thinking at this point these docs are too confusing. It might be better to create a 3-tab interface with AWS, GCS, and Azure configurations defined separately. It seems like they're different enough that this is warranted. You should apply the same treatment to the enterprise migration guide for chart V2 too.

@devin-ai-integration @ian-at-airbyte
docs: use 3-tab interface for storage configuration and fix V1 GCS
0cb42a1 
- Replace single code block with AWS/GCS/Azure tabs in chart-v2-community.mdx
- Replace single code block with AWS/GCS/Azure tabs in chart-v2-enterprise.mdx
- Fix Helm chart V1 GCS example to use storageSecretName in storage.md
- Clarify GCS has two options: inline credentials vs external secret
- Remove confusing secretName field that doesn't apply to GCS

Addresses PR feedback from ian-at-airbyte

Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>
@ian-at-airbyte
Copy link
Contributor

secretName: is missing for AWS and Azure migration guides, but present in the log storage documentation. Have you forgotten to add it to the migration guide, or have you omitted it for some reason?

@devin-ai-integration @ian-at-airbyte
docs: add secretName back for S3 and Azure storage types
3e63021 
S3 and Azure use secretName (unlike GCS which uses storageSecretName).
Added it back to both migration guides.

Addresses feedback from ian-at-airbyte

Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ian-at-airbyte ian-at-airbyte ian-at-airbyte left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

1 participant

@ian-at-airbyte