Document CRD categories set by crossplane

[gberche-orange]

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 kubernetes/kubernetes#140043

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)