AutoGineer
Generated banner for Open Knowledge Format for Crossplane v2
Generated logo for Open Knowledge Format for Crossplane v2

Open Knowledge Format for Crossplane v2

LLM wiki kit

First committed by jkroepke

Published in jkroepke/okf-crossplane-v2. Publisher page

37 GitHub stars

What it is

LLM-wiki in OKF (Open Knowledge Format) for Crossplane v2
— the description by jkroepke

AutoGineer overview, from the brain’s own files

The okf-crossplane-v2 repository provides a versioned, source-backed knowledge catalog designed to help AI agents and developers navigate the Crossplane v2 ecosystem. It aggregates information from Go API types, CRDs, package metadata, and documentation into a structured format. By utilizing the Open Knowledge Format (OKF), it enables agents to perform precise lookups on providers, composition functions, and API definitions. The project includes a dedicated MCP server that allows agents to query live repository data, such as CRD definitions, versioning, and examples, ensuring that the information retrieved is grounded in specific, versioned source code.

How it works

Memory model: LLM wiki

AutoGineer overview, from the brain’s own files

The system organizes technical knowledge into a catalog of Markdown files stored in the catalog folder. These files contain OKF metadata and provenance links. An MCP server, which can be self-hosted or used via a public endpoint, ingests this catalog into a DuckDB instance. Agents interact with this data through specific tools that resolve provider versions, search CRDs, and retrieve documentation or examples. The system relies on specialized researcher agents defined in the .agents folder to maintain and validate the knowledge base, ensuring that facts are linked to stable source code and documentation.

Folders
FolderRoleFiles
.codexagent-config25
.githubagent-config2
skillsagent-instructions1
.agentsfolder37
.codex-pluginfolder1
.okffolder2
.pifolder27
.pluginfolder1
catalogfolder120
mcpfolder12

Requirements

Apps: Docker

API keys (by name): GITHUB_TOKEN

Works with: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Amp, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. Download the brain as a ZIP and unzip it where you keep your notes or project: https://mp-staging.autogineer.com/agent-brains/jkroepke/okf-crossplane-v2/download

  2. Point Claude Code at .codex-plugin/plugin.json: it does not read that file on its own.

  3. cd okf-crossplane-v2 && claude

  4. AutoGineer scanned these files at commit df24ac2.

  5. Add crossplane-v2-okf to .mcp.json:

    {
  "mcpServers": {
    "crossplane-v2-okf": {
      "type": "http",
      "url": "https://crossplane.mcp.jkroepke.de/mcp"
    }
  }
}

  6. Or add it with the Claude Code CLI:

    claude mcp add --transport http crossplane-v2-okf https://crossplane.mcp.jkroepke.de/mcp

  7. Your data is sent to crossplane.mcp.jkroepke.de.

  8. First committed by jkroepke. Published in jkroepke/okf-crossplane-v2. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

  • Querying CRD definitions for specific Crossplane providers
  • Retrieving versioned examples for composition functions
  • Resolving stable provider versions and their associated documentation
  • Integrating Crossplane knowledge into AI agent workflows via MCP
“Find the latest version of the AWS provider and list its CRDs.”
The agent uses the get_versions and provider_crd_search tools to return the canonical repository name and a list of available CRDs for the specified provider.
“Show me the definition for the S3Bucket CRD in the latest AWS provider.”
The agent retrieves the YAML definition of the requested CRD using the provider_crd_get_definition tool, ensuring the output is token-efficient.

Documentation by jkroepke

Image: CI Image: GitHub license Image: GitHub Repo stars Image: BundleDex

Open Knowledge Format for Crossplane v2

This repository provides a structured knowledge catalog for the Crossplane v2 ecosystem using Open Knowledge Format v0.2.

The goal is to make Crossplane concepts, APIs, providers, composition functions, documentation, and practical examples easier to discover and understand. The catalog is designed for both humans and knowledge-aware tools.

Installation

WARNING
The public MCP server is a temporary early-access service for early adopters. Its availability is not guaranteed, and it may change or be removed without notice. It is intended to bridge the current tooling gap until the OKF ecosystem provides practical, end-user-friendly solutions that run locally. For reliable or production use, self-host the included container.

Install the companion skill and hosted OKF-aware MCP server together as a plugin for every detected supported agent:

npx plugins add jkroepke/okf-crossplane-v2

Pass --target codex to install only in Codex. Restart the selected agents after installation.

Alternatively, install the hosted OKF-aware MCP server globally:

npx add-mcp \
  https://crossplane.mcp.jkroepke.de/mcp \
  --name crossplane-v2-okf \
  --global

Then install the companion skill so the agent prefers this bundle over generic documentation providers for Crossplane v2 questions:

npx skills add jkroepke/okf-crossplane-v2 \
  --skill crossplane-v2-okf \
  --global

Both standalone installers detect supported agents and ask where the integration should be installed. Restart the selected agent after installation.

The public MCP health endpoint is available at https://crossplane.mcp.jkroepke.de/healthz.

Self-hosting the MCP server

The included container fetches this repository, ingests catalog/ into a DuckDB catalog, and serves the okf-mcp tools over Streamable HTTP.

docker compose up --build --detach

To authenticate the server's GitHub requests, export GITHUB_TOKEN before starting the container. The token is optional.

The local MCP endpoint is http://127.0.0.1:8000/mcp. Put it behind a TLS reverse proxy for crossplane.mcp.jkroepke.de.

The catalog is refreshed at container startup. If fetching or ingestion fails and a previous catalog exists in the volume, the server continues with that last successful catalog.

The MCP tools are read-only, but the public endpoint has no application-level authentication. Apply request limits and access controls at the reverse proxy when required.

Crossplane package tools

The server adds these tools backed by OSS GitHub repositories:

  • get_versions(name) resolves an OSS provider or function repository and returns its canonical repository name, versions.latest, a compact list of recent stable versions, and tag counts. Pass the returned provider name to the CRD tools.

  • provider_crd_search(provider_name, provider_version, crd_search_term) searches CRDs in one explicit provider package version. The search term supports case-insensitive shell-style wildcards.

  • provider_crd_get_definition(provider_name, provider_version, crd_name, path?) returns the complete CRD definition as token-efficient YAML. Use a dotted path such as .spec or .spec.versions[0] to return only a subtree.

  • provider_crd_get_examples(provider_name, provider_version, crd_name) returns GitHub repository paths for generated and handwritten examples. Without an API version, it selects the latest served CRD API version, for example examples-generated/namespaced/ec2/v1beta2/route.yaml.

  • provider_crd_get_terraform_docs(provider_name, provider_version, crd_name) returns the Terraform provider repository, version, and documentation path. It reads the Crossplane provider Makefile and the generated controller mapping instead of inferring the Terraform resource name.

crd_name accepts a Kind, group/Kind, group/version/Kind, or a YAML fragment containing apiVersion and kind.

Use an OSS GitHub repository name such as crossplane-contrib/provider-upjet-aws or crossplane-contrib/function-go-templating. A small set of historical package aliases is mapped to their known OSS source repositories; unmapped upbound/... names are rejected rather than guessed.

The CRD tools require an explicit provider version. The value latest is also supported and selects the highest stable semantic-version Git tag. Self-hosted deployments need outbound HTTPS access to GITHUB_API_URL and GITHUB_RAW_URL.

Successful remote fetches are cached in memory. Git tag listings use the configurable short FETCH_CACHE_TTL_SECONDS (default: 300 seconds); CRDs, definitions, examples, and Terraform metadata resolved at immutable Git tags are cached for 30 days. FETCH_CACHE_MAX_ENTRIES (default: 512) bounds memory use.

Why this repository exists

Crossplane knowledge is distributed across many repositories and kinds of sources:

  • Go API types and runtime implementations

  • CustomResourceDefinitions and OpenAPI schemas

  • package metadata

  • tests and executable examples

  • official Crossplane documentation

  • community implementations and real-world composition examples

Upjet-based providers add another layer. Their Crossplane managed resources are generated from Terraform provider resources, while the Terraform documentation often contains more details about the underlying cloud APIs and configuration fields.

This repository connects these sources in one versioned catalog without replacing the original documentation.

Knowledge structure

Knowledge is stored as small Markdown documents under catalog/. Each document represents an independently useful concept and includes OKF metadata, provenance in sources, keyed claim footnotes, and relationships to related concepts.

Repository validation pins okf-ingest 0.11.0, which adds OKF v0.2 core support, including generated.at freshness fallback and preservation of the new frontmatter families (upstream support commit).

If the task is to build a Crossplane v2 Composition, start with the Composition developer route. It routes agents through separate API/provider, pipeline/security, and testing/packaging concepts without pretending that provider-specific schemas or credentials are universal.

The catalog is intended to be:

  • Source-backed: important statements link to source code, schemas, tests, examples, or official documentation.

  • Version-aware: sources are tied to specific repository revisions.

  • Navigable: overview documents connect related concepts without requiring readers to know the source repository layout.

  • Incremental: providers, functions, services, documentation areas, and example repositories can be added in focused batches.

License

This project is licensed under the Apache License 2.0.

catalog/core/usages-and-clusterusages.md

type: concept title: Usage and ClusterUsage deletion protection description: Beta Core APIs that block deletion of used resources and model deletion ordering across supported Kubernetes scopes. resource: https://docs.crossplane.io/v2.3/managed-resources/usages/ tags: [crossplane, core, usage, deletion-protection, beta] generated: { by: "process:okf-v0.2-migration", at: "2026-08-20T06:45:13Z" } sources:

Overview

Usage and ClusterUsage describe a relationship in which a resource identified by spec.by uses the resource identified by spec.of. Crossplane blocks deletion of the of resource while the relationship exists. This supports accidental-deletion protection and deletion ordering: a dependent can be deleted before the resource it needs.[^official-purposes-and-terminology]

The APIs do not schedule creation or wait for the of resource to become ready. Their ordering guarantee is limited to deletion protection. This differs from function-sequencer creation gating, which filters unobserved desired successors. When sequencer also generates deletion relationships, those Usage objects must already exist because Composition Functions do not run during XR deletion.[^function-pipelines-do-not-run-during-xr-deletion]

Both APIs are Beta, served and stored as protection.crossplane.io/v1beta1. Usages are enabled by default and can be disabled with --enable-usages=false.[^beta-maturity-and-feature-flag][^usage-crd-scope-and-served-version][^clusterusage-crd-scope-and-served-version]

Schema

FieldPurpose
spec.ofRequired identity of the protected or used resource.
spec.byOptional identity of the using or dependent resource.
spec.reasonOptional human-readable reason for protection when no dependent resource is needed.
spec.replayDeletionReplays a previously blocked deletion after the Usage is removed. Defaults to false.

At least one of spec.by or spec.reason is required. Each present of or by endpoint uses either resourceRef or resourceSelector; a reference takes precedence if both are supplied. Selector resolution persists the chosen name into the reference and does not continuously retarget the Usage.[^usage-endpoint-types-and-validation][^one-time-selector-resolution]

Behavior

After resolving the endpoints, the controller:

  1. adds crossplane.io/in-use: "true" to the of resource;

  2. adds the by resource as an owner of the Usage when present;

  3. reports the Usage as available and periodically rechecks it.[^reconciled-label-ownership-and-availability]

A fail-closed validating webhook intercepts deletion of labelled resources. It finds matching Usages, records the attempted propagation policy, and denies deletion with HTTP 409 Conflict while at least one Usage remains.[^deletion-webhook-configuration][^deletion-denial-behavior]

When a Usage is deleted, Crossplane removes the in-use label only after the last protecting Usage is gone. With replayDeletion: true, it retries an earlier blocked deletion using the recorded propagation policy.[^cleanup-and-deletion-replay] Official guidance recommends replay for composed-resource deletion ordering because it avoids waiting for a later deletion retry.[^replay-guidance]

Scope model

Usage is namespaced. ClusterUsage is cluster-scoped.[^usage-crd-scope-and-served-version][^clusterusage-crd-scope-and-served-version]

by endpointof endpointModel and boundary
NamespacedSame namespaceA Usage in that namespace is the normal model.
NamespacedDifferent namespaceUsage supports an explicit namespace only on of; by must be present and remains in the Usage namespace.[^namespaced-and-cross-namespace-relationships]
Cluster-scopedCluster-scopedClusterUsage is the documented model.[^clusterusage-guidance]
NamespacedCluster-scopedThe Usage type can express this shape, but released v2.3.3 deletion lookup is silently ineffective; do not rely on it.[^open-cross-scope-enhancement-report-7123][^released-namespace-sensitive-finder]
Cluster-scopedNamespacedAPI comments permit the shape, but docs and E2E tests do not establish it as supported; issue #7123 tracks the gap.[^usage-endpoint-types-and-validation][^open-cross-scope-enhancement-report-7123]

ClusterUsage endpoints have no namespace field. Its finder index always uses an empty namespace, so it matches cluster-scoped deletion requests rather than namespaced objects.[^clusterusage-endpoint-schema][^released-namespace-sensitive-finder]

Composition relationships

In a Composition, selectors may use matchControllerRef to constrain both endpoints to resources controlled by the same composite resource. When a Composition produces multiple resources of the same kind, labels can disambiguate the selected endpoint.[^composition-selector-guidance]

This concept is distinct from provider-defined ProviderConfigUsage tracking described in References and ProviderConfig. Usage and ClusterUsage are generic Core deletion-protection APIs for arbitrary Kubernetes resources.

Limitations and project history

Research timestamp: 2026-07-16. Core evidence remains selected at v2.3.3; the function-sequencer cross-reference was researched on this date.

  • Issue #7123, opened by a human author on 2026-02-06 and still open at the research timestamp, reports the inability to reliably model dependencies between namespaced and cluster-scoped resources. It proposes expanding ClusterUsage, allowing selected cross-scope Usage relationships, or adding an explicit consent mechanism. These are proposals, not released behavior.

  • Issue #7249, opened by a human maintainer and still open at the research timestamp, reports that a namespaced Usage protecting a cluster-scoped of resource receives the in-use label but does not block deletion. The released v2.3.3 finder retains the reported namespace-key mismatch.[^released-namespace-sensitive-finder]

  • Issue #6336, opened by a human maintainer and still open at the research timestamp, tracks promotion of the protection.crossplane.io Usage APIs to GA. It is an enhancement and roadmap-tracking issue, not evidence that GA promotion is released or committed to a particular release; the selected v2.3.3 APIs remain Beta.[^beta-maturity-and-feature-flag][^usage-crd-scope-and-served-version][^clusterusage-crd-scope-and-served-version][^open-ga-promotion-tracker-6336]

  • function-sequencer issue #114, opened by human author @jkroepke on 2026-03-09, updated 2026-03-10, and still open at the 2026-07-16 research timestamp, reports a downstream manifestation in function-sequencer v0.5.0. A cluster-scoped Composition sequencing a namespaced resource produces a ClusterUsage that cannot encode the resource namespace and remains unready indefinitely.[^function-sequencer-report-114] This report illustrates the Core scope gap but does not independently establish Core behavior.

  • PR #6345 is human-authored historical context for introducing the v2 Usage APIs on the former v2 branch. Its discussion describes mixed-scope cases as intentionally unresolved rather than a supported contract.[^pr-6345-scope-discussion] Its merge commit is not an ancestor of the selected v2.3.3 commit, so current claims rely on the pinned v2.3.3 sources instead.[^diverged-pr-merge-and-v2-3-3-commits]

  • Bot-authored stale notices and other automation activity were excluded from project-history evidence.

The in-use label alone is therefore not proof that mixed-scope deletion protection works. For v2.3.3, use Usage for documented namespaced relationships and ClusterUsage when both endpoints are cluster-scoped.

Composition Functions that generate Usage resources need an additional scope guard. In function-sequencer v0.6.0, usageVersion: v2 chooses ClusterUsage when the predecessor (of) has no namespace. Do not enable deletion sequencing for a cluster-scoped predecessor to a namespaced successor: ClusterUsage has no namespace fields and Core cannot resolve that mixed-scope relationship. This is a function-specific authoring rule derived from the selected function implementation and the Core scope model, not a general claim that every function generates Usage resources.[^function-sequencer-v0-6-0-usage-generation]

[^official-purposes-and-terminology]: Official purposes and terminology [^beta-maturity-and-feature-flag]: Beta maturity and feature flag [^usage-crd-scope-and-served-version]: Usage CRD scope and served version [^clusterusage-crd-scope-and-served-version]: ClusterUsage CRD scope and served version [^usage-endpoint-types-and-validation]: Usage endpoint types and validation [^clusterusage-endpoint-schema]: ClusterUsage endpoint schema [^reconciled-label-ownership-and-availability]: Reconciled label, ownership, and availability [^deletion-webhook-configuration]: Deletion webhook configuration [^deletion-denial-behavior]: Deletion denial behavior [^cleanup-and-deletion-replay]: Cleanup and deletion replay [^replay-guidance]: Replay guidance [^namespaced-and-cross-namespace-relationships]: Namespaced and cross-namespace relationships [^clusterusage-guidance]: ClusterUsage guidance [^open-cross-scope-enhancement-report-7123]: Open cross-scope enhancement report #7123 [^released-namespace-sensitive-finder]: Released namespace-sensitive finder [^composition-selector-guidance]: Composition selector guidance [^one-time-selector-resolution]: One-time selector resolution [^pr-6345-scope-discussion]: PR #6345 scope discussion [^diverged-pr-merge-and-v2-3-3-commits]: Diverged PR merge and v2.3.3 commits [^function-sequencer-report-114]: function-sequencer report #114 [^open-ga-promotion-tracker-6336]: Open GA promotion tracker #6336 [^function-sequencer-v0-6-0-usage-generation]: function-sequencer v0.6.0 Usage generation [^function-pipelines-do-not-run-during-xr-deletion]: Function pipelines do not run during XR deletion

242 files

Advantages

  • Provides version-aware knowledge by linking facts to specific repository revisions. evidence: README.md
  • Connects distributed sources like Go APIs, CRDs, and documentation into a single navigable catalog. evidence: README.md

Limitations

  • The public MCP server is provided as an early-access service and is not intended for production use without self-hosting. evidence: README.md
  • Requires explicit provider versions for CRD tools, as it does not guess or infer versions automatically. evidence: README.md

Security

Risk level: Low risk

This brain runs

Agent instructions that run or fetch something (26)

  • .agents/agents/okf-function-go-templating-researcher/AGENT.md: Write for Crossplane users who want to install and use `function-go-templating` in Compositions.
  • .agents/agents/okf-reviewer/AGENT.md: `mise run lint` succeeds after the final fixes and before the root or parent agent creates a commit.
  • .agents/agents/okf-reviewer/AGENT.md: Run `mise run lint` as the final validation command.
  • .agents/skills/okf-open-knowledge-format/SKILL.md: If the user agrees to install:
  • .agents/skills/okf-open-knowledge-format/SKILL.md: uv tool install okflint
  • .agents/skills/okf-open-knowledge-format/SKILL.md: pip install okflint
  • .agents/skills/okf-open-knowledge-format/SKILL.md: kcmd push --dry-run
  • .agents/skills/okf-updates/SKILL.md: Run this workflow only after the user explicitly invokes `$okf-updates`, `/skill:okf-updates`, or `/okf-updates`.
  • .agents/skills/okf-updates/SKILL.md: Run at most three direct researchers at once.
  • .agents/skills/okf-updates/SKILL.md: A requester reply that selects one or more candidate IDs from this explicitly invoked workflow is explicit permission to run the normal OKF update logic for those candidates.
  • .agents/skills/okf-updates/SKILL.md: Run deterministic validation, `okf-reviewer`, and `mise run lint`.
  • .agents/skills/okf/SKILL.md: Run this workflow only after the user explicitly invokes `$okf`, `/skill:okf`, or `/okf`.
  • .agents/skills/okf/SKILL.md: After all review fixes, run `mise run lint`.
  • .agents/skills/okf/SKILL.md: Commit every intended file only after reviewer approval and a successful lint run.
  • .agents/skills/okf/SKILL.md: Run the Core docs and Core code researchers together when a concept needs both user-facing guidance and exact served API shape.
  • .agents/skills/okf/SKILL.md: Run independent read-heavy research in parallel, with at most three direct agents.
  • .agents/skills/okf/SKILL.md: After all fixes, run `mise run lint` and fix every reported issue.
  • .agents/skills/okf/SKILL.md: The reviewer may return `APPROVED` only after the final lint run succeeds.
  • .agents/skills/okf/SKILL.md: Non-thinking coding models such as Qwen3-Coder-Next can run every project agent without incompatible reasoning controls.
  • .agents/skills/okf/SKILL.md: deterministic validation and `mise run lint` results
  • AGENTS.md: Run the normal workflow only when the user explicitly invokes `$okf`, `/skill:okf`, or `/okf`, or selects a feature candidate returned by an explicitly invoked `$okf-updates`, `/skill:okf-updates`, or `/okf-updates` workflow.
  • AGENTS.md: Run update discovery only when the user explicitly invokes `$okf-updates`, `/skill:okf-updates`, or `/okf-updates`.
  • AGENTS.md: Run deterministic validation and the `okf-reviewer` before committing the changes.
  • AGENTS.md: After the final review fixes, run `mise run lint` before creating any commit.
  • AGENTS.md: After reviewer approval and a successful lint run, commit every intended change.
  • AGENTS.md: Create commits with a Developer Certificate of Origin sign-off by default by using `git commit --signoff` (or `git commit -s`).

MCP servers (1)

  • .mcp.json (crossplane-v2-okf): https://crossplane.mcp.jkroepke.de/mcp · uses the network
  • Low risk: network-instructions (.agents/skills/okf-open-knowledge-format/SKILL.md:214)

Attribution and licence

First committed by
GitHub avatar of jkroepkejkroepke
Publisher
Jan-Otto Kröpke (Community)
Source
jkroepke/okf-crossplane-v2 · commit df24ac2
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
jkroepke

AutoGineer is not affiliated with or endorsed by jkroepke.

Download

The ZIP holds the files AutoGineer serves, with ATTRIBUTION.md and the licence. Download okf-crossplane-v2.zip