Skip to content

Commit 4edfc1f

Browse files
drootdroot
authored
Merge pull request #397 from fanzhangio/gitbook
Add subresource annotation documents in gitbook
2 parents d024bc0 + 557f735 commit 4edfc1f

File tree

3 files changed

+107
-2
lines changed

3 files changed

+107
-2
lines changed

‎docs/book/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
* Development Workflow
2929
* [Defining Boilerplate License Headers](beyond_basics/boilerplate.md)
3030
* [Running Tests](beyond_basics/running_tests.md)
31+
* [Using Annotation](beyond_basics/annotations.md)
3132
* [Generating API Documentation](beyond_basics/generating_documentation.md)
3233
* [Updating Kubebuilder](beyond_basics/upgrading_kubebuilder.md)
3334
* [Dependency Management](beyond_basics/dependencies.md)

‎docs/book/basics/simple_resource.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,7 @@ used to configure code generators to run against this code. The code generators
5858
generate boilerplate functions and types to complete the Resource definition.
5959
To learn more on configuring code generation see the *Code Generation* chapter.
6060

61-
Note: The `// +kubebuilder:validation:Pattern=.+:.+` annotation declares Pattern validation
62-
requiring that the `Image` field match the regular expression `.+:.+`
61+
To learn more about how to use annotations in kubebuilder, refer to [Using Annotation](../beyond_basics/annotations.md)
6362
{% endpanel %}
6463

6564
{% method %}

‎docs/book/beyond_basics/annotations.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Annotation
2+
3+
The definition contains several comment annotations of the form `// +something`. These are used to configure code generators to run against this code. The code generators will generate boilerplate functions and types to complete the Resource definition.
4+
To learn more on configuring code generation see the *Code Generation* chapter.
5+
6+
## Validation
7+
8+
Format: `// +kubebuilder:validation:<key=value>`
9+
The validation annotation supports CRD validation ([OpenAPI v3 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject)).
10+
The last `key-value` part should be a sigle key-value pair. If you have multiple validation key-value pairs, should put them into separte annotation comments.
11+
Currently, supporting keys are `Maximum`, `Minimum`, `MaxLength`, `MinLength`, `MaxItems`, `MinItems`, `UniqueItems`, `Enum`, `Pattern`, `ExclusiveMaximum`,
12+
`ExclusiveMinimum`, `MultipleOf`, `Format`
13+
The `// +kubebuilder:validation:Pattern=.+:.+` annotation declares Pattern validation requiring that the `Image` field match the regular expression `.+:.+`
14+
15+
**Example:**
16+
17+
```go
18+
// ToySpec defines the desired state of Toy
19+
type ToySpec struct {
20+
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
21+
// Important: Run "make" to regenerate code after modifying this file
22+
23+
// +kubebuilder:validation:Maximum=100
24+
// +kubebuilder:validation:Minimum=1
25+
// +kubebuilder:validation:ExclusiveMinimum=true
26+
Power float32 `json:"power,omitempty"`
27+
Bricks int32 `json:"bricks,omitempty"`
28+
// +kubebuilder:validation:MaxLength=15
29+
// +kubebuilder:validation:MinLength=1
30+
Name string `json:"name,omitempty"`
31+
// +kubebuilder:validation:MaxItems=500
32+
// +kubebuilder:validation:MinItems=1
33+
// +kubebuilder:validation:UniqueItems=false
34+
Knights []string `json:"knights,omitempty"`
35+
Winner bool `json:"winner,omitempty"`
36+
// +kubebuilder:validation:Enum=Lion,Wolf,Dragon
37+
Alias string `json:"alias,omitempty"`
38+
// +kubebuilder:validation:Enum=1,2,3
39+
Rank int `json:"rank"`
40+
Comment []byte `json:"comment,omitempty"`
41+
42+
Template v1.PodTemplateSpec `json:"template"`
43+
Claim v1.PersistentVolumeClaim `json:"claim,omitempty"`
44+
45+
Replicas *int32 `json:"replicas"`
46+
}
47+
48+
```
49+
50+
51+
## Subresource
52+
53+
54+
### 1. Status
55+
56+
Format: `// +kubebuilder:subresource:status`,
57+
58+
59+
### 2. Scale
60+
61+
Format: `// +kubebuilder:subresource:scale:specpath=<jsonpath>,statuspath=<jsonpath>,selectorpath=<jsonpath>`
62+
63+
64+
Scale subresource annotation contains three fields: `specpath`, `statuspath` and `selectorpath`.
65+
1) `specpath` refers to `specReplicasPath` attribute of Scale object, and value `jsonpath` defines the JSONPath inside of a custom resource that corresponds to `Scale.Spec.Replicas`. This filed is required and not empty
66+
2) `statuspath` refers to `statusReplicasPath` attribute of Scale object. and the `jsonpath` value of it defines the JSONPath inside of a custom resource that corresponds to `Scale.Status.Replicas`. This filed is required and not empty
67+
3) `selectorpath`refers to `labelSelectorPath` attribute of Scale object, and the value `jsonpath` defines the JSONPath inside of a custom resource that corresponds to Scale.Status.Selector. This filed is optional, which can be omitted or with empty value
68+
69+
70+
**Example:**
71+
72+
```go
73+
74+
// ToySpec defines the desired state of Toy
75+
type ToySpec struct {
76+
77+
// Other Fields of ToySpec
78+
79+
Replicas *int32 `json:"replicas"` // Add this field in Toy Spec, so the jsonpath to this field is `.spec.replicas`
80+
}
81+
82+
83+
// ToyStatus defines the observed state of Toy
84+
type ToyStatus struct {
85+
86+
Replicas int32 `json:"replicas"` // Add this field in Toy Status, so the jsonpath to this field is `.status.replicas`
87+
}
88+
89+
90+
// Toy is the Schema for the toys API
91+
// +k8s:openapi-gen=true
92+
// +kubebuilder:subresource:status
93+
// +kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas
94+
type Toy struct {
95+
metav1.TypeMeta `json:",inline"`
96+
metav1.ObjectMeta `json:"metadata,omitempty"`
97+
98+
Spec ToySpec `json:"spec,omitempty"`
99+
Status ToyStatus `json:"status,omitempty"`
100+
}
101+
102+
```
103+
104+
In order to enable scale subresource in type definition file, you have to apply the scale subresource right before the kind struct definition, with correct jsonpath values according to the spec and status. And then make sure the jsonpaths are already defined in the Spec and Status struct. Finally, update the `<kind>_types_test.go` files according to the types Spec and Status changes.
105+
In the example of `Toy`, we can add `// +kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas` right a comment line before `Toy` struct definition. `.spec.replicas` referes the josnpath to Spec struct field (`ToySpec.Replicas`). And jsonpath `.status.healthyReplicas` refers to Status struct field (`ToyStatus.Replicas`). We don't have specific lableSelector deifined, so skip the `selectorpath` parts.

0 commit comments

Comments
 (0)