Boundary Docs: Configure workers refactor - #3077
Open
stellarsquall wants to merge 7 commits into
Open
Conversation
Adds 16 PNGs covering eight diagrams, each rebuilt with light/dark variants: concepts-multihop multi-hop session flow multi-hop-workers worker chain and upstream direction worker-tags tag-based session routing worker-deployment recommended worker deployment single-region single-region controller deployment boundary-architecture HCP Boundary on AWS data-at-rest storage encryption data-in-transit session encryption This commit only adds files. No page references them yet and theoriginals remain in place, so the build is unchanged.
Replaces 12 Admin UI screenshots used by the workers, filters, and session recording pages. Filenames are unchanged, so no page references are affected. Four light/dark pairs had mismatched dimensions, which made the image jump when a reader switched themes. All six pairs now match.
Reorganizes the workers usage docs book around the deployment lifecycle and splits bloated content into new pages. Registration: Splits workers/registration.mdx into an overview plus one page per method: controller-led, worker-led, and external KMS. The overview compares the three so readers can choose. Inbound links in the Helm chart and data encryption pages are updated to the new paths. New lifecycle pages: Adds workers/start, workers/manage, and workers/troubleshoot, covering how to start and verify a worker, day-two operations (tags, config reload, graceful shutdown, upgrade, decommission, cleanup and re-registration), and ten symptom-driven troubleshooting entries. Multi-hop: Restructures the multi-hop book into siblings for Enterprise and HCP, and adds a page on authenticating downstream workers with a separate KMS trust domain. Standardizes on "intermediate" rather than "intermediary". Shared content: Extracts eight partials so worker configuration, registration steps, verification output, and filter examples are written once and reused across the workers and self-managed deployment books. Navigation: Moves "Route traffic through a worker" and "Configure a worker filter" ahead of the multi-hop section, which depends on both. The procedural path (create, start, register) stays unbroken. Also documents worker cleanup and re-registration, and corrects the TLS handshake troubleshooting entry by adding stale worker credentials that produce the same error.
Updates the six image references that live outside the workers book, so every diagram on these pages now resolves to the light and dark variants added earlier: - architecture/recommended-architecture: single-region, worker-deployment - concepts/workers: worker-tags - secure/security-model, boundary-architecture, data-at-rest, data-in-transit Alt text is rewritten in the same pass. No prose changes. These pages only contain image references.
Deletes the eight single-theme diagrams replaced by the light/dark variants added earlier in this branch: - concepts-multihop.png - multi-hop-workers.png - worker-tags.png - worker-deployment.png - single-region.png - security-model/boundary-architecture.png - security-model/data-at-rest.png - security-model/data-in-transit.png No file in v1.0.x references these paths anymore. Older versions keep their own copies, so earlier versions should not be affected.
Contributor
Vercel Previews Deployed
|
Contributor
Broken Link CheckerThis PR contains broken links, but won't be blocked. Use this report to improve content quality: Quick Actions
Need Help?
Internal LinksExternal Links |
stellarsquall
marked this pull request as ready for review
August 10, 2026 23:52
stellarsquall
changed the title
11 tasks
stellarsquall
added a commit
that referenced
this pull request
Aug 12, 2026
<!-- **Merge branch** Make sure your PR uses the correct **base** branch for the merge destination. For more information, refer to **Change the branch range and destination repository** (https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). To update: - Existing content Choose **base: main** to update existing documentation. Your content will be published when the PR is merged. - Content for an upcoming Boundary release Choose the branch for the relevant upcoming Boundary release. Boundary release branches use the `boundary/<exact-release-number>` format. Your content will be published when the upcoming release goes live. If you are not sure which base branch to use, or you cannot find the release branch you are looking for: - Choose the `main` branch. - Add the "do not merge" label. - Convert the PR to a DRAFT. - Explain the update in the **Description**. **Back porting to older versions** This repo stores versioned documentation in folders instead of branches. There are no backport labels. If your update applies to multiple versions, you must update the content in each of the corresponding version folders. For example, you make an update to the Boundary code in the current release, 0.21.0, and back port it to versions 0.20.x and 0.19.x. To document the update for each of the relevant versions, you would update the documentation in the v0.21.x, v0.20.x, and v0.19.x folders. --> ## Description <!-- Describe why you're making this change and point out any important details the reviewers should be aware of. --> Rebuilds nine Boundary diagrams with light and dark variants, and commits the SVG sources for all rebuilt diagrams so they can be edited rather than redrawn. This is the second of two diagram PRs. The first covers the diagrams in the workers documentation branch; the two sets are completely disjoint and touch no common files: [Boundary Docs: Configure workers refactor - #3077](#3077) Four commits, in order: **1. Add rebuilt diagram assets** — 18 PNGs, nine diagrams with light and dark variants, rebuilt from the Helios design system (Flight Icons v5.0.0). `how-boundary-works` was already a themed pair, so those two files are replaced in place under the same filenames. **2. Point pages at the rebuilt diagrams** — six references across four pages. **3. Remove superseded and unreferenced originals** — eight deletions. **4. Add SVG sources** — 34 files under `content/boundary/v1.0.x/diagram-sources/`, deliberately outside `img/` so they aren't served as static assets. ### Diagrams | Diagram | Page | |---|---| | `boundary-domain-model-overview` | Domain model | | `component-relationship` | Domain model | | `credential-brokering` | Credential management | | `credential-injection` | Credential management | | `iam-example-structure` | Identity and access management | | `pagination-workflow` | API pagination | | `how-boundary-works` | Workers (replaced in place) | | `architecture-overview` | not referenced | | `boundary` | not referenced | ### Notes for reviewers **The credential pair now shows the distinction it exists to illustrate.** `credential-brokering` and `credential-injection` were near-identical images, and in both the User box was drawn disconnected from everything else. The red credential path now terminates where the prose says it does — at the **user** for brokering, at the **worker** for injection, with the worker authenticating to the server on the user's behalf. That contrast was previously invisible. **Two references had empty alt text** — `` and `` — so screen readers announced nothing on the domain model page. All six references now describe their diagram. **The domain model overview changes file type**, `.jpg` → `.png`. No page redirect is needed (no routes moved), but any external link directly to the old image path will 404. **Two diagrams are intentionally unreferenced.** `architecture-overview` and `boundary` were already orphaned on `main` — they went unused when `what-is-boundary`, `getting-started`, and `oss/installing` were restructured after v0.12.x. This PR removes the stale originals and adds rebuilt pairs, so the branch carries four unreferenced files where `main` carried two. These assets may be removed in the future if there is no use for them going forward. **Eight SVG sources have no matching image here.** They belong to the diagrams in the workers branch on PR 3077. If that PR's diagrams change in review, these sources and those PNGs will drift — merging this after it avoids that. Older version folders are untouched; every deleted file remains byte-identical in v0.18.x–v0.21.x (and v0.7.x–v0.12.x for the two orphans). ## Links <!-- Include links to any associated pull requests, GitHub issues, or documentation that is relevant to this update. // GH-Jira integration generates the link and updates the Jira ticket. Jira: [<jira-ticket-number>] // for example, Jira: [ICU-1234] GitHub Issue: <issue-link> --> [Jira ticket](https://hashicorp.atlassian.net/browse/SPE-1816?atlOrigin=eyJpIjoiMTYyMzdjMTI1ZDUxNDM0MTljNjc5ZmMyZDg1ODNmNDMiLCJwIjoiaiJ9) [PR #3077: Configure workers refactor](#3077) ## Contributor checklists <!-- Help your reviewer understand the type of review you need by selecting the scope and urgency. --> Review urgency: - [ ] ASAP: Bug fixes, broken content, imminent releases - [ ] 3 days: Small changes, easy reviews - [x] 1 week: Default expectation - [ ] Best effort: No urgency Pull request: - [ ] Verify that the PR is set to merge into the correct base branch - [ ] Verify that all status checks passed - [ ] Verify that the preview environment deployed successfully - [ ] Add additional reviewers if they are not part of assigned groups Content: - [ ] I added redirects for any moved or removed pages - [ ] I followed the [Education style guide](https://github.com/hashicorp/web-unified-docs/tree/main/docs/style-guide) - [ ] I looked at the local or Vercel build to make sure the content rendered correctly [ICU-1234]: https://hashicorp.atlassian.net/browse/ICU-1234?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Refactors the Boundary workers documentation and rebuilds the diagrams it depends on. The workers book previously mixed registration methods, lifecycle operations, and troubleshooting into a few overloaded pages, with no coverage of day-two operations.
Reviewable as five commits, in order:
Add rebuilt diagram assets — 16 PNGs, eight diagrams with light and dark variants.
Refresh worker UI screenshots from 12 Admin UI captures. Four light/dark pairs had mismatched dimensions, which made images jump on theme toggle; all six pairs now match.
Restructure workers documentation
Point remaining pages at rebuilt diagrams. Six image references outside the workers book, plus rewritten alt text.
Remove superseded diagram originals. Eight orphaned files, copies retained in v0.20.x and v0.21.x.
Validation
Worker usage procedures for all workflows were run against a live HCP Boundary cluster using docker workers, which surfaced several corrections to existing docs:
Terraform examples were checked with validate and plan, filters.mdx was missing a required scope_id.
No redirects needed. registration.mdx → registration/index.mdx serves the same route, and no routes were removed.
Seven routes added.
Links
Jira: Worker Refactor ticket
Jira: Worker cleanup and re-registration
Jira: Self-managed worker KMS updates
Deploy Preview
Contributor checklists
Review urgency:
Pull request:
Content: