github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/configuration/ingress-resources/advanced-configuration-with-snippets.md (about)

     1  # Advanced Configuration with Snippets
     2  
     3  Snippets allow you to insert raw NGINX config into different contexts of the NGINX configurations that the Ingress Controller generates. These should be used as a last-resort solution in cases where annotations and ConfigMap entries cannot help. Snippets are intended for advanced NGINX users who need more control over the generated NGINX configuration.
     4  
     5  Snippets are also available through the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource). Annotations take precedence over the ConfigMap.
     6  
     7  ## Using Snippets
     8  
     9  The example below shows how to use snippets to customize the NGINX configuration template using annotations.
    10  ```yaml
    11  apiVersion: networking.k8s.io/v1beta1
    12  kind: Ingress
    13  metadata:
    14    name: cafe-ingress-with-snippets
    15    annotations:
    16      nginx.org/server-snippets: |
    17        location / {
    18            return 302 /coffee;
    19        }
    20      nginx.org/location-snippets: |
    21        add_header my-test-header test-value;
    22  spec:
    23    rules:
    24    - host: cafe.example.com
    25      http:
    26        paths:
    27        - path: /tea
    28          backend:
    29            serviceName: tea-svc
    30            servicePort: 80
    31        - path: /coffee
    32          backend:
    33            serviceName: coffee-svc
    34            servicePort: 80
    35  ```
    36  
    37  Generated NGINX configuration:
    38  ```nginx
    39  server {
    40      listen 80;
    41  
    42  
    43      location / {
    44          return 302 /coffee;
    45      }
    46  
    47  
    48      location /coffee {
    49          proxy_http_version 1.1;
    50  
    51  
    52          add_header my-test-header test-value;
    53          ...
    54          proxy_pass http://default-cafe-ingress-with-snippets-cafe.example.com-coffee-svc-80;
    55      }
    56  
    57      location /tea {
    58          proxy_http_version 1.1;
    59          
    60          add_header my-test-header test-value;
    61          ...
    62          proxy_pass http://default-cafe-ingress-with-snippets-cafe.example.com-tea-svc-80;
    63      }
    64  }
    65  ```
    66  **Note**: The generated configs are truncated for the clarity of the example.
    67  
    68  ## Summary of Snippets
    69  
    70  See the [snippets annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#snippets-and-custom-templates) documentation for more information.
    71  However, because of the disadvantages described below, snippets are disabled by default. To use snippets, set the [`enable-snippets`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-enable-snippets) command-line argument.
    72  
    73  ## Disadvantages of Using Snippets
    74  
    75  Snippets have the following disadvantages:
    76  
    77  * *Complexity*. To use snippets, you will need to:
    78    * Understand NGINX configuration primitives and implement a correct NGINX configuration.
    79    * Understand how the IC generates NGINX configuration so that a snippet doesn't interfere with the other features in the configuration.
    80  * *Decreased robustness*. An incorrect snippet makes the NGINX config invalid, which causes reload failures. This will prevent any new configuration updates, including updates for the other Ingress resources, until the snippet is fixed.
    81  * *Security implications*. Snippets give access to NGINX configuration primitives and those primitives are not validated by the Ingress Controller. For example, a snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Ingress resources.
    82  
    83  > **Note**: If the NGINX config includes an invalid snippet, NGINX will continue to operate with the latest valid configuration.
    84  
    85  ## Troubleshooting
    86  
    87  If a snippet includes an invalid NGINX configuration, the Ingress Controller will fail to reload NGINX. The error will be reported in the Ingress Controller logs and an event with the error will be associated with the Ingress resource:
    88  
    89  An example of an error from the logs:
    90  ```
    91  [emerg] 31#31: unknown directive "badd_header" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54
    92  Event(v1.ObjectReference{Kind:"Ingress", Namespace:"default", Name:"cafe-ingress-with-snippets", UID:"f9656dc9-63a6-41dd-a499-525b0e0309bb", APIVersion:"extensions/v1beta1", ResourceVersion:"2322030", FieldPath:""}): type: 'Warning' reason: 'AddedOrUpdatedWithError' Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: ""
    93  stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n"
    94  finished with error: exit status 1
    95  ```
    96  
    97  An example of an event with an error (you can view events associated with the Ingress by running `kubectl describe -n nginx-ingress ingress nginx-ingress`):
    98  ```
    99  Events:
   100  Type     Reason                   Age                From                      Message
   101  ----     ------                   ----               ----                      -------
   102  Normal   AddedOrUpdated           52m (x3 over 61m)  nginx-ingress-controller  Configuration for default/cafe-ingress-with-snippets was added or updated
   103  finished with error: exit status 1
   104  Warning  AddedOrUpdatedWithError  54s (x2 over 89s)  nginx-ingress-controller  Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: ""
   105  stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n"
   106  finished with error: exit status 1
   107  ```
   108  
   109  Additionally, to help troubleshoot snippets, a number of Prometheus metrics show the stats about failed reloads – `controller_nginx_last_reload_status` and `controller_nginx_reload_errors_total`.