Skip to content

SPIRE-233, OAPE-880: Add agentic documentation for AI-assisted development #144

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

Open
rausingh-rh wants to merge 3 commits into
base: main
Choose a base branch
from
Open

SPIRE-233, OAPE-880: Add agentic documentation for AI-assisted development #144

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ec90657
Add agentic documentation for AI-assisted development
rausingh-rh Jul 31, 2026
0fa71a3
Address PR review comments on agentic docs
rausingh-rh Jul 31, 2026
d20d303
review feedback from cursor to improvise harness docs
nhegde07 Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Zero Trust Workload Identity Manager (ZTWIM) - Agentic Documentation

**Component**: Zero Trust Workload Identity Manager
**Repository**: openshift/zero-trust-workload-identity-manager

> **Retrieval-first**: Before generating code, read the relevant `ai-docs/` files. Start with `domain/` for API types, then `architecture/components.md` for patterns, then `ZTWIM_DEVELOPMENT.md` for workflow.
>
> **Generic Platform Patterns**: See Platform documentation (openshift/enhancements/ai-docs/) for operator patterns, testing practices, security guidelines, and cross-repo ADRs.

## What is ZTWIM?

A controller-runtime operator (not library-go) that deploys and manages upstream SPIFFE/SPIRE components on OpenShift 4.18+ so workloads get dynamic, rotatable identities (JWT-SVID / X.509-SVID). GA since v1.0.0; published to `stable-v1` channel via `redhat-operators` CatalogSource.

**Key Principle**: The operator does not embed upstream code — it manages upstream resources as static YAML manifests (bindata) applied imperatively, deploying upstream container images via `RELATED_IMAGE_*` env vars.

## Core Components

| Controller | Purpose | Key Resources |
|---|---|---|
| **ZTWIM** | Status aggregator | Watches all operand CRs + OperatorCondition, syncs Upgradeable to OLM |
| **SpireServer** | SPIRE server lifecycle | StatefulSet, ConfigMaps, Routes, webhooks, federation, SPIFFE CRs |
| **SpireAgent** | SPIRE agent lifecycle | DaemonSet, custom SCC, ConfigMap, ClusterRole |
| **SpiffeCSIDriver** | CSI driver lifecycle | DaemonSet, CSIDriver, privileged SCC RoleBinding |
| **SpireOIDCDiscoveryProvider** | OIDC discovery | Deployment, Route, ClusterSPIFFEID, ConfigMap |

**Quick Start**: `oc get zerotrustworkloadidentitymanagers cluster -o yaml` | `oc get spireservers,spireagents,spiffecsidrivers,spireoidcdiscoveryproviders`

## Critical Patterns

**1. Never hand-edit generated files** — `zz_generated.deepcopy.go`, `config/crd/bases/*.yaml`, `pkg/operator/assets/bindata.go`. Use `make generate`, `make manifests`, `make update-bindata`. Run `make verify` before pushing.

**2. All five ZTWIM-owned CRDs are cluster-scoped singletons named `cluster`** — enforced by CEL XValidation. The three upstream `spire.spiffe.io` CRDs (ClusterSPIFFEID, ClusterFederatedTrustDomain, ClusterStaticEntry) are NOT singletons — see [`ai-docs/domain/upstream-spiffe-crds.md`](ai-docs/domain/upstream-spiffe-crds.md). Controller names use the full prefix: `zero-trust-workload-identity-manager-<component>-controller` (constants in `pkg/controller/utils/constants.go`).

**3. Operand controllers watch the parent ZTWIM CR** — all four operand controllers watch `ZeroTrustWorkloadIdentityManager` with `ZTWIMSpecChangedPredicate`, and managed resources with component-specific label predicates (`ControllerManagedResourcesForComponent`). The ZTWIM controller does NOT create operand CRs — it only aggregates status.

**4. Vendor is tracked** — after dependency changes, always `make vendor` and commit the vendor directory. The build uses `-mod=vendor`.

## Key Build Commands

| Command | Purpose |
|---|---|
| `make build` | Full build (manifests + generate + fmt + vet + binary) |
| `make test` | Unit tests with envtest |
| `make verify` | vet + fmt + golangci-lint |
| `make manifests generate update-bindata` | Regenerate all generated files |

## Documentation Structure

```text
ai-docs/
├── domain/ # CRD type docs (ZTWIM, SpireServer, SpireAgent, etc.)
│ └── upstream-spiffe-crds.md
├── architecture/ # Repo layout, controller table, reconciliation flow
│ └── components.md
├── decisions/ # Component ADRs (controller-runtime choice, bindata)
│ ├── adr-0001-*.md
│ └── adr-template.md
├── exec-plans/
│ └── README.md # Pointer to Platform guidance
├── references/
│ ├── ecosystem.md # Links to Platform
│ └── enhancements.md # Enhancement proposals & upstream refs
├── ZTWIM_DEVELOPMENT.md # Build, workflow, common tasks, env vars
└── ZTWIM_TESTING.md # Unit (FakeCustomCtrlClient) + E2E (Ginkgo)
```

**AI Agent Path**: [`ai-docs/README.md`](ai-docs/README.md) → domain/ → architecture/ → decisions/ → ZTWIM_DEVELOPMENT.md

**Platform Patterns**: [Operator](https://github.com/openshift/enhancements/tree/master/ai-docs) | [Testing](https://github.com/openshift/enhancements/tree/master/ai-docs) | [Security](https://github.com/openshift/enhancements/tree/master/ai-docs)

## Upstream Operands

| Upstream | Integration |
|---|---|
| [spire](https://github.com/spiffe/spire) | Server (StatefulSet), agent (DaemonSet), OIDC (Deployment) images |
| [spire-controller-manager](https://github.com/spiffe/spire-controller-manager) | Go module dep for API types; sidecar with SPIRE server |
| [spiffe-csi](https://github.com/spiffe/spiffe-csi) | CSI driver DaemonSet image |

**Release**: Managed via [zero-trust-workload-identity-manager-release](https://github.com/openshift/zero-trust-workload-identity-manager-release) (Konflux, dual-branch model: `release-*` for images, `main` for FBC catalogs).

## External References

- [SPIFFE Specification](https://github.com/spiffe/spiffe) | [SPIRE Docs](https://spiffe.io/docs/latest/spire-about/) | [OpenShift Docs](https://docs.openshift.com/)

---

**Platform Documentation**: openshift/enhancements/ai-docs/
49 changes: 49 additions & 0 deletions ai-docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# ZTWIM Agent Documentation

Retrieval-first documentation for AI agents and contributors working on the Zero Trust Workload Identity Manager operator.

> **Start here**: Read [`../AGENTS.md`](../AGENTS.md) for critical patterns and build commands before generating code.

## Agent Path

Follow this order when working on a task:

1. **`domain/`** — CRD types, validation rules, field relationships
2. **`architecture/components.md`** — controller patterns, reconcile flow, shared utilities
3. **`decisions/`** — architectural decisions (controller-runtime, bindata)
4. **`ZTWIM_DEVELOPMENT.md`** — build workflow, bootstrap, common tasks
5. **`ZTWIM_TESTING.md`** — unit and E2E test patterns (when writing tests)
Comment on lines +9 to +15

@coderabbitai coderabbitai Bot Jul 31, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use the required documentation order.

The Agent Path places decisions/ before ZTWIM_DEVELOPMENT.md. Move decisions/ after ZTWIM_DEVELOPMENT.md so agents read the required development workflow before generating code.

Proposed order 
 1. **`domain/`** — CRD types, validation rules, field relationships
 2. **`architecture/components.md`** — controller patterns, reconcile flow, shared utilities
-3. **`decisions/`** — architectural decisions (controller-runtime, bindata)
-4. **`ZTWIM_DEVELOPMENT.md`** — build workflow, bootstrap, common tasks
-5. **`ZTWIM_TESTING.md`** — unit and E2E test patterns (when writing tests)
+3. **`ZTWIM_DEVELOPMENT.md`** — build workflow, bootstrap, common tasks
+4. **`decisions/`** — architectural decisions (controller-runtime, bindata)
+5. **`ZTWIM_TESTING.md`** — unit and E2E test patterns (when writing tests)

As per coding guidelines, **/*: Before generating code, read relevant documentation in ai-docs/ in this order: domain/, architecture/components.md, then ZTWIM_DEVELOPMENT.md.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Follow this order when working on a task:
1. **`domain/`** — CRD types, validation rules, field relationships
2. **`architecture/components.md`** — controller patterns, reconcile flow, shared utilities
3. **`decisions/`** — architectural decisions (controller-runtime, bindata)
4. **`ZTWIM_DEVELOPMENT.md`** — build workflow, bootstrap, common tasks
5. **`ZTWIM_TESTING.md`** — unit and E2E test patterns (when writing tests)
Follow this order when working on a task:
1. **`domain/`** — CRD types, validation rules, field relationships
2. **`architecture/components.md`** — controller patterns, reconcile flow, shared utilities
3. **`ZTWIM_DEVELOPMENT.md`** — build workflow, bootstrap, common tasks
4. **`decisions/`** — architectural decisions (controller-runtime, bindata)
5. **`ZTWIM_TESTING.md`** — unit and E2E test patterns (when writing tests)
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ai-docs/README.md` around lines 9 - 15, Reorder the documentation reading
order in the README.md file to place ZTWIM_DEVELOPMENT.md before decisions/. The
correct sequence should be: domain/, architecture/components.md,
ZTWIM_DEVELOPMENT.md (build workflow and bootstrap), then decisions/
(architectural decisions), and finally ZTWIM_TESTING.md. This ensures agents
read the required development workflow before consulting architectural decisions
when generating code.

Source: Coding guidelines


## Documentation Map

| Document | Purpose |
|----------|---------|
| [domain/zero-trust-workload-identity-manager.md](domain/zero-trust-workload-identity-manager.md) | Top-level singleton CR — trust domain, status aggregation |
| [domain/spire-server.md](domain/spire-server.md) | SPIRE Server CR — CA, persistence, federation, JWT issuer |
| [domain/spire-agent.md](domain/spire-agent.md) | SPIRE Agent CR — node/workload attestation, socket path |
| [domain/spiffe-csi-driver.md](domain/spiffe-csi-driver.md) | CSI Driver CR — Workload API socket delivery to pods |
| [domain/spire-oidc-discovery-provider.md](domain/spire-oidc-discovery-provider.md) | OIDC Discovery Provider CR — JWT-SVID validation for external systems |
| [domain/shared-types.md](domain/shared-types.md) | CommonConfig, conditions, singleton/immutability patterns |
| [domain/upstream-spiffe-crds.md](domain/upstream-spiffe-crds.md) | Upstream `spire.spiffe.io` CRDs and ZTWIM vs controller-manager ownership |
| [architecture/components.md](architecture/components.md) | Repository layout, controllers, reconcile flow, anti-patterns |
| [decisions/adr-0001-controller-runtime-over-library-go.md](decisions/adr-0001-controller-runtime-over-library-go.md) | Why controller-runtime instead of library-go |
| [decisions/adr-0002-bindata-for-operand-manifests.md](decisions/adr-0002-bindata-for-operand-manifests.md) | Why go-bindata for static operand manifests |
| [ZTWIM_DEVELOPMENT.md](ZTWIM_DEVELOPMENT.md) | Build, bootstrap, adding operands/bindata/CRD fields |
| [ZTWIM_TESTING.md](ZTWIM_TESTING.md) | Unit (FakeCustomCtrlClient) and E2E (Ginkgo) patterns |
| [references/ecosystem.md](references/ecosystem.md) | Links to Platform operator/testing/security docs |
| [references/enhancements.md](references/enhancements.md) | OpenShift enhancement proposals and upstream refs |
| [exec-plans/README.md](exec-plans/README.md) | Multi-step feature execution plans |

## Cross-Field Consistency

These fields must agree across CRs — see linked domain docs for details:

| Field | CRs |
|-------|-----|
| Socket path | [SpireAgent](domain/spire-agent.md) ↔ [SpiffeCSIDriver](domain/spiffe-csi-driver.md) |
| JWT issuer | [SpireServer](domain/spire-server.md) ↔ [SpireOIDCDiscoveryProvider](domain/spire-oidc-discovery-provider.md) |
| CSI plugin name | [SpiffeCSIDriver](domain/spiffe-csi-driver.md) ↔ [SpireOIDCDiscoveryProvider](domain/spire-oidc-discovery-provider.md) |

## Platform Documentation

Generic OpenShift operator patterns live in [openshift/enhancements/ai-docs/](https://github.com/openshift/enhancements/tree/master/ai-docs). ZTWIM-specific patterns stay in this directory.
Loading