The /status subresource is used to split the user-provided specification of a CR instance from the controller-provided status. The main motivation for this is privilege separation:
• The user usually should not write status fields.
• The controller should not write specification fields.
The RBAC mechanism for access control does not allow rules at that level of detail. Those rules are always per resource. The /status subresource solves this by providing two endpoints that are resources on their own. Each can be controlled with RBAC rules independently. This is often called a spec-status split.
Resource Semantics:
When dealing with resources that have a
/statussubresource, there are specific rules regarding changes to the status.These rules apply both to the main resource endpoint and the
/statussubresource endpoint.
Main Resource Endpoint:
During resource creation (i.e., when a new resource is being added), any changes to the status on the main HTTP endpoint are ignored. The status is simply dropped during creation.
Similarly, updates to the status on the main resource endpoint are also ignored.
/status Subresource Endpoint:
The
/statussubresource endpoint only considers changes to the status of the payload. Any other modifications are ignored.It’s important to note that creating a new resource directly on the
/statusendpoint is not possible.
Metadata and Generation:
If something outside of metadata (such as labels or annotations) and outside of status changes (e.g., changes in the spec), the main resource endpoint will increase the
metadata.generationvalue.This increase in
metadata.generationcan serve as a trigger for a controller, indicating that the user’s desired state has changed.
Spec and Status in Update Requests:
- Typically, both the spec and status are sent in update requests. However, technically, you could leave out the respective other part in a request payload.
/status Endpoint Behavior:
- The
/statusendpoint will ignore everything outside of the status field, including metadata changes.
- The
In summary, these rules ensure that changes to the status are handled consistently across resource creation, updates, and subresource endpoints.
For better understanding let us take an example:
Baking Cookies (Creating Resources):
When you want to bake cookies (create a new resource), you start with a basic cookie dough (the main resource).
Now, imagine there’s a special cookie decoration (the
/statussubresource) that you can add later.But during the initial cookie-making process, you don’t worry about the decoration. You just focus on getting the basic cookie shape right.
Decorating the Cookies (Updating Resources):
Once your cookies are baked (resource created), you can decorate them.
The special decoration (the
/statussubresource) is where you add sprinkles, chocolate chips, or frosting.But here’s the catch: You can only change the decoration part. The rest of the cookie (the dough) stays the same.
If you try to change the dough (like making it bigger or changing the recipe), the decoration part doesn’t care. It only pays attention to its own design.
The Cookie Jar (Metadata and Generation):
Imagine you have a cookie jar (the main resource endpoint). It keeps track of all your cookies.
Whenever you make a significant change (like using a new recipe), the cookie jar knows. It increases its “generation” number.
But the decoration part (the
/statussubresource) doesn’t care about the cookie jar’s labels or anything else outside itself.
Summary:
Creating cookies (resources) doesn’t involve the decoration part.
Updating cookies (resources) means playing with the decoration.
The cookie jar (main resource endpoint) keeps track of changes.
The decoration part (the
/statussubresource) only cares about its own design.
Remember, in the world of resources, it’s all about creating, decorating, and keeping track!