github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/configuration/ingress-resources/custom-annotations.md (about)

     1  # Custom Annotations
     2  
     3  Custom annotations enable you to quickly extend the Ingress resource to support many advanced features of NGINX, such as rate limiting, caching, etc.
     4  
     5  ## What are Custom Annotations
     6  
     7  NGINX Ingress Controller supports a number of annotations for the Ingress resource that fine tune NGINX configuration (for example, connection timeouts) or enable additional features (for example, JWT validation). The complete list of annotations is available [here](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations).
     8  
     9  The annotations are provided only for the most common features and use cases, meaning that not every NGINX feature or a customization option is available through the annotations. Additionally, even if an annotation is available, it might not give you the satisfactory level of control of a particular NGINX feature. 
    10  
    11  Custom annotations allow you to add an annotation for an NGINX feature that is not available as a regular annotation. In contrast with regular annotations, to add a custom annotation, you don't need to modify the Ingress Controller source code -- just modify the template. Additionally, with a custom annotation, you get full control of how the feature is implemented in NGINX configuration.
    12  
    13  ## Usage
    14  
    15  The Ingress Controller generates NGINX configuration for Ingress resources by executing a configuration template. See [NGINX template](https://github.com/nginxinc/kubernetes-ingress/blob/v1.12.5/internal/configs/version1/nginx.ingress.tmpl) or [NGINX Plus template](https://github.com/nginxinc/kubernetes-ingress/blob/v1.12.5/internal/configs/version1/nginx-plus.ingress.tmpl). 
    16  
    17  To support custom annotations, the template has access to the information about the Ingress resource - its *name*, *namespace* and *annotations*. It is possible to check if a particular annotation present in the Ingress resource and conditionally insert NGINX configuration directives at multiple NGINX contexts - `http`, `server`, `location` or `upstream`. Additionally, you can get the value that is set to the annotation. 
    18  
    19  Consider the following excerpt from the template, which was extended to support two custom annotations:
    20  
    21  ```
    22  # This is the configuration for {{$.Ingress.Name}}/{{$.Ingress.Namespace}}
    23  
    24  {{if index $.Ingress.Annotations "custom.nginx.org/feature-a"}}
    25  # Insert config for feature A if the annotation is set
    26  {{end}}
    27  
    28  {{with $value := index $.Ingress.Annotations "custom.nginx.org/feature-b"}}
    29  # Insert config for feature B if the annotation is set
    30  # Print the value assigned to the annotation: {{$value}}
    31  {{end}}
    32  ```
    33  
    34  Consider the following Ingress resource and note how we set two annotations:
    35  ```yaml
    36  apiVersion: networking.k8s.io/v1beta1
    37  kind: Ingress
    38  metadata:
    39    name: example-ingress
    40    namespace: production
    41    annotations:
    42      custom.nginx.org/feature-a: "on"
    43      custom.nginx.org/feature-b: "512"
    44  spec:
    45    rules:
    46    - host: example.com
    47      . . .
    48  ```
    49  
    50  Assuming that the Ingress Controller is using that customized template, it will generate a config for the Ingress resource that will include the following part, generated by our template excerpt:
    51  ```
    52  # This is the configuration for cafe-ingress/default
    53  
    54  # Insert config for feature A if the annotation is set
    55  
    56  
    57  
    58  # Insert config for feature B if the annotation is set
    59  # Print the value assigned to the annotation: 512
    60  ```
    61  
    62  **Notes**: 
    63  * You can customize the template to insert you custom annotations via [custom templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates).
    64  * The Ingress Controller uses go templates to generate NGINX config. You can read more information about go templates [here](https://golang.org/pkg/text/template/).
    65  
    66  See the examples in the next section that use custom annotations to configure NGINX features.
    67  
    68  ### Custom Annotations with Mergeable Ingress Resources
    69  
    70  A Mergeable Ingress resource consists of multiple Ingress resources - one master and one or several minions. Read more about Mergeable Ingress resources [here](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration).
    71  
    72  If you'd like to use custom annotations with Mergeable Ingress resources, please keep the following in mind:
    73  * Custom annotations can be used in the Master and in Minions. For Minions, you can access them in the template only when processing locations.
    74  
    75      If you access `$.Ingress` anywhere in the Ingress template, you will get the master Ingress resource. To access a Minion Ingress resource, use `$location.MinionIngress`. However, it is only available when processing locations:
    76      ```
    77  	{{range $location := $server.Locations}}
    78  	location {{$location.Path}} {
    79          {{with $location.MinionIngress}}
    80  	    # location for minion {{$location.MinionIngress.Namespace}}/{{$location.MinionIngress.Name}}
    81  	    {{end}}
    82          . . .
    83      } {{end}}
    84      ```
    85      **Note**: `$location.MinionIngress` is a pointer. When a regular Ingress resource is processed in the template, the value of the pointer is `nil`. Thus, it is important that you check that `$location.MinionIngress` is not `nil` as in the example above using the `with` action.  
    86  
    87  * Minions do not inherent custom annotations of the master.
    88  
    89  ### Helper Functions
    90  
    91  Helper functions can be used in the Ingress template to parse the values of custom annotations.
    92  
    93  ```eval_rst
    94  .. list-table::
    95     :header-rows: 1
    96  
    97     * - Function
    98       - Input Arguments
    99       - Return Arguments
   100       - Description
   101     * - ``split``
   102       - ``s, sep string``
   103       - ``[]string``
   104       - Splits the string ``s`` into a slice of strings separated by the ``sep``. 
   105     * - ``trim``
   106       - ``s string``
   107       - ``string``
   108       - Trims the trailing and leading whitespace from the string ``s``.
   109  ```
   110  
   111  Consider the following custom annotation `custom.nginx.org/allowed-ips`, which expects a comma-separated list of IP addresses:
   112  ```
   113  annotations:
   114    custom.nginx.org/allowed-ips: "192.168.1.3, 10.0.0.13"
   115  ```
   116  
   117   The helper functions can parse the value of the `custom.nginx.org/allowed-ips` annotation, so that in the template you can use each IP address separately. Consider the following template excerpt:
   118  
   119  ```
   120  {{range $ip := split (index $.Ingress.Annotations "custom.nginx.org/allowed-ips") ","}}
   121      allow {{trim $ip}};
   122  {{end}}
   123  deny all;
   124  ```
   125  
   126  The template excerpt will generate the following configuration:
   127  ```
   128  allow 192.168.1.3;
   129  allow 10.0.0.13;
   130  deny all;
   131  ```
   132  
   133  ## Example
   134  
   135  See the [custom annotations example](https://github.com/nginxinc/kubernetes-ingress/blob/v1.12.5/examples/custom-annotations).