docs(abctl): expand docs with troubleshooting, flag reference, and scope limitations by ian-at-airbyte · Pull Request #74094 · airbytehq/airbyte

Ian Alton (ian-at-airbyte) · 2026-02-27T23:32:06Z

What

Addresses gaps in abctl documentation identified through Kapa.ai chatbot conversations where users could not find answers to common questions:

Installer script failures (e.g. Is a directory error)
Customizing the abctl binary install location
How to use --chart and --chart-version flags
Whether abctl works with an existing Kubernetes cluster

How

docs/platform/deploying-airbyte/abctl/index.md:

Rewrote the "When to use abctl" paragraph to include scope limitation inline: abctl only manages its own kind cluster and can't target an existing Kubernetes cluster, with a link to the Helm chart deployment guide
Added "Customize the install location" subsection documenting DIR_INSTALL, RELEASE_TAG, and DEBUG env vars from the installer script
Added "Pin a specific Helm chart version" and "Install from a local Helm chart" usage examples under the install section
Expanded --chart and --chart-version descriptions in the reference table with fuller explanations and a link to ArtifactHub for finding chart versions

docs/platform/deploying-airbyte/troubleshoot-deploy.md:

Added new "Installer Script Errors" section before the existing "Common Errors" (which covers abctl local install runtime errors, not the installer script itself)
Documented the "Is a directory" error with debug workaround and alternative install methods
Documented "Permission denied" error with DIR_INSTALL workaround
Added installer env var reference table
Added FAQ entry: "Can I use abctl with an existing Kubernetes cluster?"

Review guide

docs/platform/deploying-airbyte/abctl/index.md — scope limitation (inline in paragraph), install customization section, chart version examples, expanded flag descriptions
docs/platform/deploying-airbyte/troubleshoot-deploy.md — new installer errors section and existing-cluster FAQ

Human review checklist:

Verify the claim that --chart-version is ignored when --chart is set (inferred from abctl README and typical Helm behavior — worth confirming against the Go source)
Confirm the installer env vars (DIR_INSTALL, RELEASE_TAG, DEBUG) still match the current abctl_install.sh

User Impact

Users and the Kapa.ai chatbot will have documentation to answer four previously unanswerable question categories. No runtime changes.

Can this PR be safely reverted and rolled back?

YES 💚

Link to Devin run: https://app.devin.ai/sessions/5c0047049398462797605f1fd644996d
Requested by: Ian Alton (@ian-at-airbyte)

…ope limitations - Add installer script troubleshooting section (Is a directory error, permission denied) - Document installer env vars (DIR_INSTALL, RELEASE_TAG, DEBUG) - Add customize install location subsection with DIR_INSTALL example - Expand --chart and --chart-version flag descriptions with usage examples - Add explicit scope limitation: abctl only manages its own kind cluster - Add FAQ entry about existing Kubernetes cluster support Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>

devin-ai-integration · 2026-02-27T23:32:09Z

🤖 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 · 2026-02-27T23:32:29Z

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

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

🛠️ Quick Fixes
- /format-fix - Fixes most formatting issues.
- /bump-version - Bumps connector versions, scraping changelog description from the PR title.
❇️ AI Testing and Review (internal link: AI-SDLC Docs):
- /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
- /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
- /ai-review - AI-powered PR review for connector safety and quality gates.
🚀 Connector Releases:
- /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
- /bump-progressive-rollout-version - Bumps connector version with an RC suffix (2.16.10-rc.1) for progressive rollouts (enableProgressiveRollout: true).
  - Example: /bump-progressive-rollout-version changelog="Add new feature for progressive rollout"
☕️ 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 bump=patch changelog='foo' - Bump the Bulk CDK's version. bump 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.
⚙️ Admin commands:
- /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
  Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
Developing Connectors Locally
Managing Connector Secrets
On-Demand Regression Tests
#connector-ci-issues
#connector-publish-updates
#connector-build-statuses

📝 Edit this welcome message.

github-actions · 2026-02-27T23:36:43Z

Deploy preview for airbyte-docs ready!

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

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

Ian Alton (ian-at-airbyte) · 2026-02-28T01:35:31Z

docs/platform/deploying-airbyte/abctl/index.md

 You use abctl to run Airbyte on a machine that isn't running a Kubernetes cluster, but is running Docker. Normally, you don't use abctl to manage enterprise deployments, because they use dedicated Kubernetes infrastructure. However, it's possible to use abctl this way if you want to.

+:::warning
+abctl only manages its own kind cluster. It cannot install Airbyte on an existing Kubernetes cluster. If you already have a Kubernetes cluster, use the [Helm chart deployment guide](../chart-v2-community.mdx) instead.
+:::
+


Let's combine these ideas into one. No need for a warning.

"You use abctl to run Airbyte on a machine that isn't running a Kubernetes cluster, but is running Docker. abctl only manages its own kind cluster. It can't install Airbyte on an existing Kubernetes cluster. If you already have a Kubernetes cluster, use the Helm chart deployment guide instead."

Done — merged the scope limitation into the paragraph and removed the :::warning box, as suggested.

Devin session

Ian Alton (ian-at-airbyte) · 2026-02-28T01:36:19Z

docs/platform/deploying-airbyte/abctl/index.md

+| `DEBUG` | unset | Set to any value to enable verbose installer output. |
+
+:::note
+`DIR_INSTALL` controls only where the **abctl binary** lives. Airbyte state data (kubeconfig, cluster data) is stored separately at `~/.airbyte/abctl/` and is not affected by this setting. There is currently no flag to relocate the data directory.


Suggested change

`DIR_INSTALL` controls only where the **abctl binary** lives. Airbyte state data (kubeconfig, cluster data) is stored separately at `~/.airbyte/abctl/` and is not affected by this setting. There is currently no flag to relocate the data directory.

`DIR_INSTALL` controls only where the **abctl binary** lives. Airbyte state data (kubeconfig, cluster data) is stored separately at `~/.airbyte/abctl/. It's not affected by this setting and you can't relocate it.

Updated to use the suggested wording.

Devin session

Ian Alton (ian-at-airbyte) · 2026-02-28T01:38:04Z

docs/platform/deploying-airbyte/abctl/index.md

+abctl local install --chart-version 0.422.2 --values values.yaml --secret secret.yaml --port 8000
+```
+
+The `--chart-version` value is the Helm chart version, not the Airbyte platform version. To find available versions, see the [Airbyte Helm chart releases](https://github.com/airbytehq/airbyte-platform/releases).


I don't think this URL shows helm chart versions. Do we not have a centralized list of them?

Good catch — that URL shows platform releases, not Helm chart versions. Updated to link to the ArtifactHub page which has the full list of chart versions: https://artifacthub.io/packages/helm/airbyte/airbyte

Devin session

…art versions URL, update wording Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>

devin-ai-integration bot assigned Ian Alton (ian-at-airbyte) Feb 27, 2026

Ian Alton (ian-at-airbyte) commented Feb 28, 2026

View reviewed changes

docs(abctl): address review feedback - simplify scope warning, fix ch…

d23cc50

…art versions URL, update wording Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(abctl): expand docs with troubleshooting, flag reference, and scope limitations#74094

docs(abctl): expand docs with troubleshooting, flag reference, and scope limitations#74094
Ian Alton (ian-at-airbyte) wants to merge 2 commits intomasterfrom
devin/1772235015-abctl-docs-improvements

Ian Alton (ian-at-airbyte) commented Feb 27, 2026 •

edited by devin-ai-integration bot

Loading

Uh oh!

devin-ai-integration bot commented Feb 27, 2026

Uh oh!

github-actions bot commented Feb 27, 2026

PR Slash Commands

Helpful Resources

Uh oh!

github-actions bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

Ian Alton (ian-at-airbyte) Feb 28, 2026

Uh oh!

devin-ai-integration bot Feb 28, 2026

Uh oh!

Ian Alton (ian-at-airbyte) Feb 28, 2026

Uh oh!

devin-ai-integration bot Feb 28, 2026

Uh oh!

Ian Alton (ian-at-airbyte) Feb 28, 2026

Uh oh!

devin-ai-integration bot Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	`DIR_INSTALL` controls only where the abctl binary lives. Airbyte state data (kubeconfig, cluster data) is stored separately at `~/.airbyte/abctl/` and is not affected by this setting. There is currently no flag to relocate the data directory.
	`DIR_INSTALL` controls only where the abctl binary lives. Airbyte state data (kubeconfig, cluster data) is stored separately at `~/.airbyte/abctl/. It's not affected by this setting and you can't relocate it.

Conversation

Ian Alton (ian-at-airbyte) commented Feb 27, 2026 • edited by devin-ai-integration bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How

Review guide

User Impact

Can this PR be safely reverted and rolled back?

Uh oh!

devin-ai-integration bot commented Feb 27, 2026

🤖 Devin AI Engineer

Uh oh!

github-actions bot commented Feb 27, 2026

👋 Greetings, Airbyte Team Member!

PR Slash Commands

Helpful Resources

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ian Alton (ian-at-airbyte) Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Ian Alton (ian-at-airbyte) Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Ian Alton (ian-at-airbyte) Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Ian Alton (ian-at-airbyte) commented Feb 27, 2026 •

edited by devin-ai-integration bot

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading