Document CRD categories set by crossplane
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 58/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- kubernetes
- Domain
- documentation
Research direction
Start with the Crossplane documentation API section and the category examples and kubectl commands in this issue. Trace which categories are generated for Crossplane resources and determine where the documentation should live. Done means users can discover the generated categories, distinguish them from unrelated categories, and understand whether category changes are breaking changes.
Written by the indexing model from the issue text.
Description
What's Missing?
As a crossplane user, it is hard to discover all categories that I can use in kubectl get <category> to interact with crossplane resources.
A web search site:https://docs.crossplane.io categories only returns the rendred XRD openapi schema at https://docs.crossplane.io/latest/api/
See also why it is currently hard for users to discover crd categories and consequently documentation would be useful https://github.com/kubernetes/website/issues/56279
As a workaround, users can try to reverse engineer the naming scheme that crossplane is using in categories assigned,
here is a sample command to show all categories in a cluster
kubectl get crds -o json | jq -r '
# Extract all CRDs
.items[]
# Get the categories array from each CRD spec
| .spec.names.categories[]?
# Remove duplicates and sort alphabetically
' | sort -u | jq -R . | jq -s .
Here is the output on my cluster
["authzed",
"azuread",
"cert-manager",
"cert-manager-acme",
"claim",
"composite",
"crossplane",
"external-secrets",
"external-secrets-generators",
"gateway-api",
"gcp",
"gitlab",
"harbor",
"helm",
"http",
"keycloak",
"kpack",
"kubernetes",
"kyverno",
"managed",
"pkg",
"pkgrev",
"prometheus-operator",
"provider",
"providerconfig",
"store",
"strimzi",
"terraform"
]
The crossplane categories not having a common prefix, it is hard to distinguish crossplane-related categories from other categories
here is a sample command to show all categories with nested related crds, which help filtering categories based on the related crd api groups (crossplane.io, and upbound.io)
kubectl get crds -o json | jq '
# Create an array of category-CRD pairs
[
.items[] |
# For each CRD, get its name and categories
.spec.names.categories[]? as $category |
{
category: $category,
crd: .metadata.name
}
]
# Group by category
| group_by(.category)
# Transform into desired format
| map({
category: .[0].category,
crds: map(.crd) | sort
})
# Sort by category name
| sort_by(.category)
'
Reverse engineering the category naming scheme, crossplane-core seems to assign categories named against the crossplane object model:
| Crossplane concept | category | Assigned CRDs |
|---|---|---|
| managed resource | managed |
all managed resources crds |
| claim | claim + claim categories defined in xrd |
all claim crds |
| composite | composite + composite categories defined in xrd |
... |
| pkg | pkg |
... |
| pkgrev | pkgrev |
... |
| provider | provider |
... |
| provider-config | provider-config |
... |
| provider-family | (e.g. gcp) |
crd on the given provider familly |
crossplane |
all crds generated by crossplane + all core crossplane crds (ex xrd) |
Since users may leverage categories to automate their interactions with crossplane, it is important that the generated categories be documented and that changes be considered a breaking change (e.g. implying semver bump for crossplane)
- Dominant language
- SCSS
- Stars
- 60
- Forks
- 163
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 2
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- No contributing guide
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.
More from crossplane/docs
-
docs: fix 'allows to use' grammar in Composition compositeTypeRef notePossibly taken @mrchatam claimed this 21 days ago. Open
Difficulty 1/5 Under an hour Newbie friendliness 95/100
crossplane/docs#1154 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
crossplane/docs#1153 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
crossplane/docs#1139 ·
-
[Web Bug] - Managed Resource Activation PoliciesPossibly taken @boxcee-interview claimed this 76 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
crossplane/docs#1126 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
crossplane/docs#1121 ·
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
CopilotKit/OpenDots#55 ·
Maintainers usually reply within 1 day
-
Security SecurityBundle
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
symfony/symfony-docs#23173 ·
Maintainers usually reply within 3 days
-
OSCI'26
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
GauravKarakoti/SecureFlow#1215 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
containers/bubblewrap#813 · 1 reaction ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
szTheory/exifcleaner#383 ·
Maintainers usually reply within 1 day