Permalink
Browse files

Merge pull request #465 from droot/book/status-subresource-docs

book: added docs for status subresource
  • Loading branch information...
k8s-ci-robot committed Oct 30, 2018
2 parents 29907a2 + a14e053 commit f9b2fd87528938b1debdf306f91dd2cba2187e75
Showing with 126 additions and 0 deletions.
  1. +1 −0 docs/book/SUMMARY.md
  2. +125 −0 docs/book/basics/status_subresource.md
@@ -17,6 +17,7 @@
* Resources
* [What is a Resource](basics/what_is_a_resource.md)
* [Resource Example](basics/simple_resource.md)
* [Status Subresource](basics/status_subresource.md)
* Controllers
* [What is a Controller](basics/what_is_a_controller.md)
* [Controller Example](basics/simple_controller.md)
@@ -0,0 +1,125 @@
# Status Subresource
By convention, the Kubernetes API makes a distinction between the specification
of the desired state of an object (a nested object field called "spec") and the
status of the object at the current time (a nested object field called "status").
The specification is a complete description of the desired state, including
configuration settings provided by the user, default values expanded by the
system, and properties initialized or otherwise changed after creation by other
ecosystem components (e.g., schedulers, auto-scalers), and is persisted in Etcd
with the API object. The status summarizes the current state of the object in
the system, and is usually persisted with the object by an automated processes
but may be generated on the fly. At some cost and perhaps some temporary
degradation in behavior, the status could be reconstructed by observation if it
were lost.
The PUT and POST verbs on objects MUST ignore the "status" values, to avoid
accidentally overwriting the status in read-modify-write scenarios. A /status
subresource MUST be provided to enable system components to update statuses of
resources they manage.
You can read more about the API convention in [Kubernetes API Convention
doc](https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status).
{% panel style="info", title="Status subresource support in Kubernetes" %}
Subresource support for CRD is enabled by default in 1.10+ releases
, so ensure that you are running kubernetes with the minimum version. You can
use `kubectl version` command to check the Kubernetes version.
{% endpanel %}
{% method %}
## Enabling Status subresource in CRD definition
First step is to enable status subresource in the CRD definition. This can be
achieved by adding a comment `// +kubebuilder:subresource:status` just above the
Go type definition as shown in example below.
{% sample lang="go" %}
```Go
// MySQL is the Schema for the mysqls API
// +k8s:openapi-gen=true
// +kubebuilder:subresource:status
type MySQL struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec MySQLSpec `json:"spec,omitempty"`
Status MySQLStatus `json:"status,omitempty"`
}
```
CRD generation tool will use the `+kubebuilder:subresource:status` annotation to
enable status subresource in the CRD definition. So, if you run, `make manifests`,
it will regenerate the CRD manifests under `config/crds/<kind_types.yaml`. Here
is an example manifests with status subresource enabled. Note the `subresources`
section with an empty `status` field.
```yaml
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
creationTimestamp: null
labels:
controller-tools.k8s.io: "1.0"
name: mysqls.myapps.examples.org
spec:
group: myapps.examples.org
names:
kind: MySQL
plural: mysqls
scope: Namespaced
subresources:
status: {}
validation:
openAPIV3Schema:
properties:
apiVersion:
type: string
kind:
type: string
metadata:
type: object
spec:
type: object
status:
type: object
version: v1
status:
acceptedNames:
kind: ""
plural: ""
conditions: []
storedVersions: []
```
Ensure you have updated the CRD definition in your cluster by running `kubectl
apply -f config/crds`
{% endmethod %}
{% method %}
## Getting and Updating status in Reconciler code
In order to get the status subresource, you don't have do anything new. The
`Get` client method returns the entire object which contains the status field.
For updating the status subresource, compute the new status value and update it
in the object and then issue `client.Status().Update(context.Background(), &obj)` to update the
status.
{% sample lang="go" %}
```go
instance := &myappsv1.MySQL{}
err := r.Get(context.TODO(), request.NamespacedName, instance)
if err != nil {
// handle err
}
// updating the status
instance.Status.SomeField = "new-value"
err = r.Status().Update(context.Background(), instance)
if err != nil {
return reconcile.Result{}, err
}
```
{% endmethod %}

0 comments on commit f9b2fd8

Please sign in to comment.