github.com/nginxinc/kubernetes-ingress@v1.12.5/examples/custom-templates/README.md (about)

     1  # Custom Templates
     2  
     3  The Ingress controller allows you to customize your templates through a [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#snippets-and-custom-templates) via the following keys:
     4  * `main-template` - Sets the main NGINX configuration template.
     5  * `ingress-template` - Sets the Ingress NGINX configuration template for an Ingress resource.
     6  * `virtualserver-template` - Sets the NGINX configuration template for an VirtualServer resource.
     7  
     8  ## Example
     9  ```yaml
    10  kind: ConfigMap
    11  apiVersion: v1
    12  metadata:
    13    name: nginx-config
    14    namespace: nginx-ingress
    15  data:
    16    main-template: |
    17      worker_processes  {{.WorkerProcesses}};
    18      ...
    19          include /etc/nginx/conf.d/*.conf;
    20      }
    21    ingress-template: |
    22      {{range $upstream := .Upstreams}}
    23      upstream {{$upstream.Name}} {
    24        {{if $upstream.LBMethod }}{{$upstream.LBMethod}};{{end}}
    25      ...
    26      }{{end}}
    27    virtualserver-template: |
    28      {{ range $u := .Upstreams }}
    29      upstream {{ $u.Name }} {
    30        {{ if ne $u.UpstreamZoneSize "0" }}zone {{ $u.Name }} {{ $u.UpstreamZoneSize }};{{ end }}
    31      ...
    32      }
    33      {{ end }}
    34  ```
    35  
    36  **Notes:**
    37  * The templates are truncated for the clarity of the example.
    38  * The templates for NGINX (the main `nginx.tmpl` and the Ingress `nginx.ingress.tmpl`) and NGINX Plus (the main `nginx-plus.tmpl` and the Ingress `nginx-plus.ingress.tmpl`) are located at [internal/configs/version1](../../internal/configs/version1/). The VirtualServer templates for NGINX (`nginx.virtualserver.tmpl`) and NGINX Plus (`nginx-plus.virtualserver.tmpl`) are located at [internal/configs/version2](../../internal/configs/version2/).
    39  
    40  ## Troubleshooting
    41  * If a custom template contained within the ConfigMap is invalid on startup, the Ingress controller will fail to start, the error will be reported in the Ingress controller logs.
    42  
    43      An example of an error from the logs:
    44      ```
    45      Error updating NGINX main template: template: nginxTemplate:98: unexpected EOF
    46      ```
    47  
    48  * If a custom template contained within the ConfigMap is invalid on update, the Ingress controller will not update the NGINX configuration, the error will be reported in the Ingress controller logs and an event with the error will be associated with the ConfigMap.
    49  
    50      An example of an error from the logs:
    51      ```
    52      Error when updating config from ConfigMap: Invalid nginx configuration detected, not reloading
    53      ```
    54  
    55    An example of an event with an error (you can view events associated with the ConfigMap by running `kubectl describe -n nginx-ingress configmap nginx-config`):
    56  
    57      ```
    58      Events:
    59        Type     Reason            Age                From                      Message
    60        ----     ------            ----               ----                      -------
    61        Normal   Updated           12s (x2 over 25s)  nginx-ingress-controller  Configuration from nginx-ingress/nginx-config was updated
    62        Warning  UpdatedWithError  10s                nginx-ingress-controller  Configuration from nginx-ingress/nginx-config was updated, but not applied: Error when parsing the main template: template: nginxTemplate:98: unexpected EOF
    63        Warning  UpdatedWithError  8s                 nginx-ingress-controller  Configuration from nginx-ingress/nginx-config was updated, but not applied: Error when writing main Config
    64      ```