DOC-7003 retarget dead k8s API anchors to the local reference - #3865
Merged
Conversation
Upstream restructured redis_enterprise_cluster_api.md and redis_enterprise_database_api.md on master so each file now holds a single heading, which killed every Go-type anchor we linked. Four live pages pointed at those anchors; all four now use the local generated API reference instead. The ticket flagged this as a judgment call rather than a mechanical retarget, because the local pages are organised by field path and the string LdapSpec appears nowhere in them. Resolved per link, on what the prose promises rather than on the old anchor's name. LdapSpec and SsoSpec become the field sections spec.ldap and spec.sso, whose lead sentences describe cluster-level LDAP and SSO configuration, so the target matches the "full details on the available fields" the sentence offers. RedisEnterpriseClusterSpec becomes spec, the whole spec table, because the link text is the bare custom resource name and narrowing it to the node-resources field would say something the sentence doesn't. The RedisEnterpriseDatabaseSpec link was deleted outright rather than retargeted; the same line already carried a relref to that exact page, so retargeting would have produced the same link twice. The reassuring find is that the local anchors are more stable than the ones they replace, and not by luck. They exist because k8s_apis_sync.yaml runs a sed pass over crdoc's output that strips the RedisEnterpriseCluster prefix from every heading, so the scheme is ours to keep rather than upstream's to break. That is a different stability story from the pinned-SHA links the audit noted surviving, and a better one. Learned: the generated k8s API reference's anchors come from our own sed normalisation in the sync workflow, not from upstream headings, so they rot only if we change that workflow. Constraint: these four links depend on the heading-prefix strip in k8s_apis_sync.yaml; altering that sed renames every anchor on both API reference pages at once. Directive: don't repoint these at redis-enterprise-k8s-docs on master — the *Spec anchors are gone from it entirely, and only its pinned-SHA URLs still resolve. Ticket: DOC-7003 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
Contributor
Contributor
🧠 Redis MemoryFound 5 related items from repository history (5 new this commit):
Memory updated at 0c6d85e |
This was referenced Aug 26, 2026
This was referenced Aug 26, 2026
kaitlynmichael
approved these changes
Aug 26, 2026
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
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.
Third PR for DOC-7003, covering Part A2 — the Kubernetes API anchor retargets.
Independent of #3863 and #3864, based directly on
main, so it can be reviewed andmerged on its own.
The problem
Upstream restructured
redis_enterprise_cluster_api.mdandredis_enterprise_database_api.mdonmaster: each file now contains exactly oneheading, so every Go-type anchor we linked (
#ldapspec,#ssospec,#redisenterpriseclusterspec,#redisenterprisedatabasespec) is gone. Four live pagespointed at them.
Instructive detail from the audit worth keeping in mind for the house rules in a later
PR: our pinned-SHA links to these same upstream files still resolve. Pinning survived;
masterrotted.The judgment calls
The ticket flagged this as not a mechanical retarget, and it isn't — the local pages are
organised by field path (
### spec.ldap), not by Go type name, and the stringLdapSpecappears nowhere in them. Each link was resolved on what its sentence promises:security/authentication/ldap.md:50#ldapspec…cluster_api#specldapsecurity/authentication/sso.md:364#ssospec…cluster_api#specssorecommendations/node-resources.md:45#redisenterpriseclusterspec…cluster_api#specRedisEnterpriseClusteridentifier, so the whole spec table is the faithful target; narrowing to#specredisenterprisenoderesourceswould make the link say something the sentence doesn'tre-databases/db-controller.md:91#redisenterprisedatabasespecrelrefto that exact page. Retargeting would have produced the same link twice, so the dead one came outPer
content/operate/kubernetes/AGENTS.md, theRedisEnterpriseClusterlink text is leftexactly as it is — custom resource identifiers are never reworded.
These anchors are more stable than the ones they replace
Not by luck.
k8s_apis_sync.yamlruns asedpass overcrdoc's output that strips theRedisEnterpriseCluster.prefix from every heading, which is why the headings read### spec.ldap. The anchor scheme is ours, not upstream's — these links now rot onlyif we change our own sync workflow, rather than whenever upstream renames a Go type.
Recorded as a
Constraint:trailer on the commit so a future edit to thatsedknows whatdepends on it.
Verification
Built the site and checked the rendered ids, not assumed slugs — the ticket specifically
warned not to assume the slug for headings containing dots. The dots are stripped:
### spec.ldaprenders asid="specldap".id="spec",id="specldap",id="specsso"on the built cluster API pageid="spec"on the built database API pagehref=""on the four edited pagesOnly the unversioned current pages are touched. The same dead anchors appear across the
7.22/,7.8.x/and8.0/snapshots; perAGENTS.mda current-version change is neverpropagated backward into a frozen snapshot, and the ticket scopes archived trees out.
🤖 Generated with Claude Code
Note
Low Risk
Documentation-only link fixes with no runtime, security, or configuration behavior changes.
Overview
Replaces dead upstream GitHub API anchors (removed when
redis-enterprise-k8s-docsrestructured headings) with in-siterelreflinks to the synced Kubernetes API reference pages.On LDAP and SSO auth docs, the
RedisEnterpriseClusterAPI reference now points to#specldapand#specssoonredis_enterprise_cluster_api. Node resources linksRedisEnterpriseClusterto#specinstead of#redisenterpriseclusterspec. Database controller drops the redundant GitHubRedisEnterpriseDatabaseSpeclink because the same line already links to the local database API page.Reviewed by Cursor Bugbot for commit 0c6d85e. Bugbot is set up for automated code reviews on this repo. Configure here.