sigs.k8s.io/kubebuilder/v3@v3.14.0/docs/kubebuilder_annotation.md (about)

     1  # Kubebuilder Annotation
     2  
     3  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.
     4  
     5  ## Kubebuilder Annotation Syntax
     6  
     7  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
     8  **+[header]:[module]:[submodule]:[key-value elements]**
     9  Go Annotation starts with `+` (e.g. `// +kubebuilder`) to differentiate from regular go comments.
    10  
    11  ## Token types
    12  
    13  - **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.
    14  
    15  - **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.
    16  
    17  - **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.
    18  
    19  ## Levels of symbols
    20  
    21  Delimiter symbols are distinguished to work in different levels from top-down for splitting values string in tokens, which provides readability and efficiency.
    22  
    23  - **Colon**
    24  
    25    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.
    26  
    27  - **Comma**
    28  
    29    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"
    30  
    31  - **Equal sign**
    32  
    33    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)
    34  
    35  - **Semicolon sign**
    36  
    37    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`
    38  
    39  - **Pipe sign or Vertical bar**
    40  
    41    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`
    42  
    43  ### Examples
    44  
    45  #### Webhook annotation examples
    46  
    47  **[header]** is `kubebuilder`,
    48  **[module]** is `webhook`,
    49  **[submodule]** is `admission` or `serveroption`
    50  
    51  ```golang
    52  // +kubebuilder:webhook:admission:groups=apps,resources=deployments,verbs=CREATE;UPDATE,name=bar-webhook,path=/bar,type=mutating,failure-policy=Fail
    53  
    54  // +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
    55  ```
    56  
    57  **Notes:**
    58  
    59  1. Separate two `submodule` (categories) under `webhook`: 1) `admission`and 2) `serveroption`, handling webhookTags and serverTags separately.
    60  2. For each submodule, all key-values should put in the same comment line.
    61  3. using `|` for splitting key-value of `lables`
    62  
    63  #### RBAC Annotation examples
    64  
    65  **[header]** is `kubebuilder`
    66  **[module]** is `rbac`
    67  No submodule at this moment, support annotations like : `// +rbac`, `// +kubebuilder:rbac`
    68  
    69  ```golang
    70  // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;delete
    71  
    72  // +rbac:groups=apps,resources=deployments,verbs=get;list;watch;delete
    73  ```