Agentic docs part 2: operator patterns, practices, workflows, and ADRs - #2049
Open
Prashanth684 wants to merge 2 commits into
Open
Agentic docs part 2: operator patterns, practices, workflows, and ADRs#2049Prashanth684 wants to merge 2 commits into
Prashanth684 wants to merge 2 commits into
Conversation
Expand the ai-docs/ tree with platform documentation, engineering practices, process workflows, and architectural decision records. Operator patterns (ai-docs/platform/): - controller-runtime: reconcile loop, watches, requeue strategies, Hypershift placement guidance - finalizers: cleanup lifecycle, external resource management - RBAC: service account permissions, least-privilege patterns - webhooks: validation, mutation, conversion webhook patterns - openshift-specifics index: pointers to upgrade strategies Engineering practices (ai-docs/practices/): - testing/pyramid: unit/integration/e2e guidance, envtest examples, CI integration, coverage targets - development/api-evolution: safe vs breaking changes, graduation path policy (alpha→beta→GA or alpha→GA), versioning strategy, conversion webhooks, migration strategies, decision table - security index: STRIDE threat model, SCC/RBAC/NetworkPolicy - reliability index: SLI/SLO/SLA definitions, degraded-mode patterns, HA patterns (PDB, leader election) Workflows (ai-docs/workflows/): - enhancement-process: AI-optimized checklist version of the enhancement template with API design checklist and review stages - implementing-features: spec→plan→build→test→review→ship pipeline, multi-PR strategy, rollout and graduation paths - exec-plans: guidance and template for tracking multi-week feature implementation across PRs and components Architectural Decision Records (ai-docs/decisions/): - ADR-0001: CVO orchestrates cluster upgrades — runlevel ordering, upgrade completion criteria, self-managing design - ADR-0002: immutable node infrastructure — RHCOS + rpm-ostree + Ignition + MCO, reboot-by-default principle - ADR-0003: standardized status conditions — Available/Progressing/ Degraded contract, CVO decision table, message conventions - ADR template and index Updates AGENTS.md: - Remove must-gather reference (no standalone doc) - Replace etcd ADR with status conditions ADR - Narrow domain tree description to match current files Updates KNOWLEDGE_GRAPH.md: - Replace must-gather doc reference with `oc adm must-gather --help`
Contributor
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Prashanth684
force-pushed
the
agentic-docs-part-2
branch
from
June 29, 2026 20:56
837acfe to
c2792a9
Compare
Prashanth684
force-pushed
the
agentic-docs-part-2
branch
from
July 17, 2026 15:35
c2792a9 to
b71e41b
Compare
…s, SNO detection, and guard pods Correct several inaccuracies and add missing details across ai-docs: - ClusterVersion: CVO checks Available/Degraded (not Progressing) for runlevel advancement; add missing conditions and runlevels 70/80 - ClusterOperator: separate required vs optional conditions; fix CreateOrUpdate guidance to note status subresource two-step pattern - CRDs: clarify conversion webhook guidance applies to CVO-managed operators; OLM operators commonly use them - Upgrade strategies: fix guard pod description (bare Pods, not Deployments); correct pre-upgrade Upgradeable check semantics - Topology guide: use Infrastructure.Status.ControlPlaneTopology instead of deprecated node label for SNO detection - Set DESIGN_PHILOSOPHY.md last-updated date - Add path for optional operator workflow
Prashanth684
force-pushed
the
agentic-docs-part-2
branch
from
July 22, 2026 22:37
b71e41b to
244e4d3
Compare
Prashanth684
commented
Jul 22, 2026
|
|
||
| Assigned runlevels (from [CVO dev guide: operators.md](../../dev-guide/cluster-version-operator/dev/operators.md) and [upgrades.md](../../dev-guide/cluster-version-operator/dev/upgrades.md)): | ||
|
|
||
| | Runlevel | Components | |
Contributor
Author
There was a problem hiding this comment.
the agent couldn't make up its mind about what was correct for the runlevels. Individual subagents would repeatedly flag incosistencies even after multiple reviews.
Contributor
|
@Prashanth684: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
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.
Expand the ai-docs/ tree with platform documentation, engineering
practices, process workflows, and architectural decision records.
Operator patterns (ai-docs/platform/):
Hypershift placement guidance
Engineering practices (ai-docs/practices/):
examples, CI integration, coverage targets
path policy (alpha→beta→GA or alpha→GA), versioning strategy,
conversion webhooks, migration strategies, decision table
patterns, HA patterns (PDB, leader election)
Workflows (ai-docs/workflows/):
enhancement template with API design checklist and review stages
multi-PR strategy, rollout and graduation paths
implementation across PRs and components
Architectural Decision Records (ai-docs/decisions/):
upgrade completion criteria, self-managing design
Ignition + MCO, reboot-by-default principle
Degraded contract, CVO decision table, message conventions
Updates AGENTS.md: