Understanding the Role of customresourcedefinitions/status in Kubernetes CRDs

Kubernetes has become the foundation of modern cloud infrastructure, giving teams a powerful way to orchestrate containers and manage workloads at scale. At its core, Kubernetes is an extensible system, and one of the key ways it achieves this flexibility is through Custom Resource Definitions (CRDs).

CRDs allow developers and platform engineers to define their own resource types that behave just like built-in Kubernetes resources. This means you can create and manage custom objects such as policies, pipelines, or application-specific configurations directly within the Kubernetes API. The foundation of Operators, GitOps platforms, and internal automation systems.

Thanks for reading! Subscribe for free to receive new posts and support my work.

While managing CRDs, I stumbled upon a permission error involving customresourcedefinitions/status. It happened during a recent Flux upgrade from version 2.6.4 to 2.7.0 and turned out to be a great learning moment.

User "AWS_SSO_Admin_Role" cannot update resource "customresourcedefinitions/status" in API group "apiextensions.k8s.io"

This permission often appears in discussions around Kubernetes RBAC, and it tends to confuse even seasoned engineers. So let’s dive deep to better understand this permission.

Generated by ChatGPT

What is customresourcedefinitions/status?

Every Kubernetes resource, whether it’s a Pod, Deployment, or CRD, has spec and status:

• spec: The spec defines the desired state of the resource (what you want Kubernetes to make happen to the resource).
• status: The status reflects the actual state of the resource (what Kubernetes or controllers observe the state of the resource).

For example, when you deploy a Pod, its spec describes what containers should run, and its status shows whether those containers are running, waiting, or failed.

Similarly, CRDs also have a status subresource that holds information about their current condition, version, and readiness. The /status subresource exists as a dedicated API endpoint that allows updates specifically to the status field of a CRD, without touching its specification.

The permission customresourcedefinitions/status refers to a user or service account’s ability to interact with this subresource. It essentially controls who can read, update, or patch the status of CRDs within a cluster.

Why does customresourcedefinitions/status permission exist?

The reason for separating the status from the main resource spec comes down to security and control.

In a typical Kubernetes setup, the spec is usually managed by administrators or CI/CD pipelines. The status, however, is managed by controllers or operators that continuously reconcile the desired state with the actual state of the system.

If both were handled together, it could open doors to unwanted or unsafe modifications. Imagine a controller trying to update a CRD’s observed state but accidentally modifying its schema or definition in the process. The /status subresource prevents that by giving Kubernetes a safe, scoped way to update just the status field.

To prevent accidental or unauthorised changes, Kubernetes exposes these through separate API subresources:

spec: /apis/apiextensions.k8s.io/v1/customresourcedefinitions/<crd-name>
status: /apis/apiextensions.k8s.io/v1/customresourcedefinitions/<crd-name>/status

So, when the CRD’s .status field is patched or updated, the operation targets the status subresource rather than the main CRD object.

Example: A typical CRD structure

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.com
spec:
  group: example.com
  names:
    kind: MyResource
    plural: myresources
  versions:
    - name: v1
      served: true
      storage: true
status:
  conditions:
    - type: Established
      status: "True"
    - type: NamesAccepted
      status: "True"

In the aforementioned example, the .status section reflects Kubernetes’ internal tracking of whether the CRD is established, served, and ready for use.

Therefore, the customresourcedefinitions/status permission allows specific roles such as controllers, admission webhooks, or automated processes to report back on CRD readiness and operational conditions without the risk of altering the CRD specification itself.

When is the customresourcedefinitions/status permission required?

The customresourcedefinitions/status permission is often required in situations where a controller, operator or automated migration job interacts directly with CRDs. This permission enables updates to the CRD’s status during the management or reconciliation of resources.

Following are some common scenarios where the customresourcedefinitions/status permission comes into play:

• Custom Controller Development: When a custom Kubernetes controller or operator is developed to create or manage CRDs, it often needs to update the status field to reflect the resource’s health, version, or reconciliation progress. Without the customresourcedefinitions/status permission, the controller cannot update CRD statuses and may encounter Forbidden errors, as discussed in the introduction.
• Automated Upgrades or Migrations: When upgrading tools or frameworks that define CRDs such as Flux, Istio or Argo CD, background processes frequently patch CRD statuses to maintain compatibility or indicate the completion of migrations. Lack of this permission can disrupt these operations and cause upgrade failures.
• Monitoring and Observability: Some monitoring solutions rely on status updates from CRDs to track whether APIs, controllers or custom workloads are healthy. Without this permission, status updates won’t propagate, leading to outdated or inaccurate monitoring data.
• Admission Controllers and Validation Webhooks: In more advanced setups, validating or mutating webhooks may also interact with CRD statuses as part of enforcing policies or performing validation checks. These processes need explicit access to /status endpoints.

Granting the customresourcedefinitions/status Permission

Access to the CRD status subresource can be granted to a user or service account by including the permission in a ClusterRole or Role definition as shown below:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: crd-status
rules:
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions/status"]
    verbs: ["get", "update", "patch"]

Next, associate the role with the relevant service account or user using a ClusterRoleBinding or RoleBinding:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: crd-status
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: crd-status
subjects:
  - kind: ServiceAccount
    name: my-controller
    namespace: default

This configuration ensures that the service account my-controller can modify CRD statuses within the default namespace without granting broader permissions on the CRD definitions themselves.

Conclusion

The customresourcedefinitions/status permission may seem like a minor detail, but it plays a crucial role in Kubernetes security and operational reliability. It ensures a clear separation between the declarative configuration defined in the spec and the observed runtime state recorded in the status.

This separation allows Kubernetes to maintain consistency, prevent unauthorized changes to CRD specifications, and enable controllers to safely update system conditions. It also ensures that only trusted controllers can modify runtime states, keeping automation predictable and secure.

When a forbidden error appears for this permission, it is not a failure but rather Kubernetes enforcing the principle of least privilege. Ensuring that automation components and controllers have the appropriate status access keeps the cluster functioning smoothly, securely, and as intended.

If you find my work valuable and would like to support it, you are welcome to sponsor me.

Happy Learning!!