-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Add document of Kubebuilder Annotation - Syntax of annotation - Symbols allowed in annotation
- Loading branch information
FAN ZHANG
committed
Feb 11, 2019
1 parent
a36c521
commit 8ea0e79
Showing
1 changed file
with
73 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,73 @@ | ||
# Kubebuilder Annotation | ||
|
||
If you have been using Kubebuilder, you must have seen comments such as `// +kubebuilder:rbac: ....` , `// +kubebuilder:resource:...` in scaffolder Go files. These special comments are used by kubebuilder tools (controller-tools) to generate CRD, RBAC, webhook manifests. In kubebuilder, these special comments are `Kubebuilder Annotation`, a.k.a `annotation`. It is designed for this kind of use case: To use kubebuilder tools, all you have to do is focus on writing your code, and put instructions with parameters as annotations along with your code, so that everything will be handled based on these annotations instructions by kubebuilder. This document illustrates the syntax of these annotations. | ||
|
||
## Kubebuilder Annotation Syntax | ||
|
||
Kubebuilder Annotation has a series of tokens separated by colons into groups from left to right. Each **Token** is a string identifier in an annotation instance. It has meaning by its position in token slice, in the form of | ||
**+[header]:[module]:[submodule]:[key-value elements]** | ||
Go Annotation starts with `+` (e.g. `// +kubebuilder`) to differentiate from regular go comments. | ||
|
||
## Token types | ||
|
||
- **header** is the identifier of a group of annotations. It helps user know which project provides this annotation. For example, in Kubernetes project, headers like `kubebuilder`, `k8s`, `genclient`, etc. are all project identifiers. A header is required for all annotations, since you may use multiple annotations from different projects in the same codebase. | ||
|
||
- **module** is the identifier of functional module in an annotation. An annotation may have a group of modules, each of which performs a particular function. | ||
|
||
- **submodule** (optional) In some cases, the module has a big functional scope, split into fine-grained sub modules, which provide the flexibility of extending module functionality. For example: **module:submodule1:submodule2:submodule3** submodule can be multiple following one by one. | ||
|
||
## Levels of symbols | ||
|
||
Delimiter symbols are distinguished to work in different levels from top-down for splitting values string in tokens, which provides readability and efficiency. | ||
|
||
- **Colon** | ||
|
||
Colon `:` is the 1st level delimiter (to annotation) only for separate tokens. Tokens on different sides of the colon should refer to different token types. | ||
|
||
- **Comma** | ||
|
||
Comma `,` is the 2nd level delimiter (to annotation) for splitting key-value pairs in **key-value elements** which is normally the last token in annotation. e.g. `+kubebuilder:printcolumn:name=<name>,type=<type>,description=<desc>,JSONPath:<.spec.Name>,priority=<int32>,format=<format>` It works within token which is the 2nd level of annotation, so it is called "2nd level delimiter" | ||
|
||
- **Equal sign** | ||
|
||
Equal sign `=` is the 3rd level delimiter (to annotation) for identifying key and value. Since the `key=value` parts are splitted from single token (2nd level), its inner delimiter `=` works for next level (3rd level) | ||
|
||
- **Semicolon sign** | ||
|
||
Semicolon sign `;` is the 4th level delimiter, which works on the `value` part (4th level) of `key=value`(3rd level) for splitting individual values. e.g. `key1=value1;value2;value3` | ||
|
||
- **Pipe sign or Vertical bar** | ||
|
||
Pipe sign `|` is the 5th level delimiter, which works inside the single `value` part (4th level) indicating key and value in case of the single value has nested key-value structure. e.g. `outerkey=innerkey1|innervalue1` | ||
|
||
### Examples | ||
|
||
#### Webhook annotation examples | ||
|
||
**[header]** is `kubebuilder`, | ||
**[module]** is `webhook`, | ||
**[submodule]** is `admission` or `serveroption` | ||
|
||
```golang | ||
// +kubebuilder:webhook:admission:groups=apps,resources=deployments,verbs=CREATE;UPDATE,name=bar-webhook,path=/bar,type=mutating,failure-policy=Fail | ||
|
||
// +kubebuilder:webhook:serveroption:port=7890,cert-dir=/tmp/test-cert,service=test-system|webhook-service,selector=app|webhook-server,secret=test-system|webhook-secret,mutating-webhook-config-name=test-mutating-webhook-cfg,validating-webhook-config-name=test-validating-webhook-cfg | ||
``` | ||
|
||
**Notes:** | ||
|
||
1. Separate two `submodule` (categories) under `webhook`: 1) `admission`and 2) `serveroption`, handling webhookTags and serverTags separately. | ||
2. For each submodule, all key-values should put in the same comment line. | ||
3. using `|` for splitting key-value of `lables` | ||
|
||
#### RBAC Annotation examples | ||
|
||
**[header]** is `kubebuilder` | ||
**[module]** is `rbac` | ||
No submodule at this moment, support annotations like : `// +rbac`, `// +kubebuilder:rbac` | ||
|
||
```golang | ||
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;delete | ||
|
||
// +rbac:groups=apps,resources=deployments,verbs=get;list;watch;delete | ||
``` |