[Web Bug] - Composite Resource Definitions documentation are missing categories

Open Beginner friendly

#1,121 opened on Jun 26, 2026 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 2/5
Estimated time: 1-3 hours
Newbie friendliness: 72/100

Issue type: Documentation
Clarity: Mostly clear
Activity status: Quiet
Tech stack: hugo, kubernetes
Domain: documentation

Research direction

Start with the Composite Resource Definitions page at docs.crossplane.io/v2.3/composition/composite-resource-definitions/ and compare it with the categories definitions in the linked apiextensions.crossplane.io_compositeresourcedefinitions.yaml schema. Document category support for claims and XRs, and add guidance on category naming so users can provide a good kubectl experience.

Written by the indexing model from the issue text.

Description

As a XRD author,
in order to help management of the claims and xr custom resources
I need to specify categories in XRD for claims and XRs

However, categories support in XRD are not documented, and only appear in the XRD openapi schema

URL: https://docs.crossplane.io/v2.3/composition/composite-resource-definitions/

https://github.com/crossplane/crossplane/blob/56aace77e6771894afa157a3339dbe8d6d15401a/cluster/crds/apiextensions.crossplane.io_compositeresourcedefinitions.yaml#L66-L81

              claimNames:
                description: |-
                  ClaimNames specifies the names of an optional composite resource claim.
                  ...
                properties:
                  categories:
                    description: |-
                      categories is a list of grouped resources this custom resource belongs to (e.g. 'all').
                      This is published in API discovery documents, and used by clients to support invocations like
                      `kubectl get all`.

Likewise, guidance to crossplane users on use of naming of categories would be useful to provide a good user experience. See related feedback upstream at https://github.com/kubernetes/website/issues/56279

Dominant language: SCSS
Stars: 60
Forks: 163
Avg merge: 15h 20m
Merged PRs (30d): 9

Contributor guide

No contributing guide indexed for this repository

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Similar issues

Update DEPENDENCIES.md for the TypeScript implementation Open

Difficulty 2/5 1-3 hours Newbie friendliness 78/100

agilepathway/label-checker#640 · Opened Sep 22, 2026
[Bounty proposal] docs(cli): Sorani (ckb) agent quickstart ($25 proposed) Open

Difficulty 2/5 1-3 hours Newbie friendliness 75/100

BasedHardware/omi#15662 · 1 comment · Opened Sep 22, 2026
Document that a SQLite trail allows only one writer Open

documentation help wanted

Difficulty 2/5 1-3 hours Newbie friendliness 90/100

rajfirke/provena#202 · Opened Sep 22, 2026
Docs are out of date: README structure tree, "Make It Yours" pointer, CONTRIBUTING test notes Open

documentation good first issue

Difficulty 2/5 1-3 hours Newbie friendliness 88/100

amponce/archive-movie-browser#167 · Opened Sep 22, 2026
Gateway 3.16 Linux install: GPG key URL 404s (public_keys has no "316" entry, falls back to legacy key) Open

user-reported

Difficulty 2/5 1-3 hours Newbie friendliness 85/100

Kong/developer.konghq.com#7316 · Opened Sep 22, 2026