ConfigMap#

ConfigMap resources allow you to configure the behavior of Angie. For example, you can set the number of worker processes or configure the access log format.

Using ConfigMap#

Our installation instructions with manifests deploy an empty ConfigMap, while the default installation manifests specify it in the ANIC command-line arguments. However, if you configured the manifests to use ConfigMap, be sure to specify the ConfigMap resource to use via the command-line arguments for ANIC.
Create a ConfigMap file named angie-config.yaml and set values that make sense for your environment:
```
kind: ConfigMap
apiVersion: v1
metadata:
  name: angie-config
  namespace: angie-ingress
data:
  proxy-connect-timeout: 10s
  proxy-read-timeout: 10s
  client-max-body-size: 2m
```
See the section Summary of ConfigMap Keys for information about available ConfigMap keys (such as proxy-connect-timeout in this example).
Create a new (or update an existing) ConfigMap resource:
```
kubectl apply -f angie-config.yaml
```
The configuration for Angie will be updated.

ConfigMap and Ingress Annotations#

Annotations allow you to configure advanced features of Angie and change its behavior.

ConfigMap is applied globally, meaning it affects every Ingress resource. In contrast, annotations are always applied only to their respective Ingress resource. Annotations allow you to override some ConfigMap keys. For example, the angie.software/proxy-connect-timeout annotation overrides the configuration key proxy-connect-timeout.

Overriding ConfigMap for a Specific Ingress Resource Using Annotations#

You can apply different ConfigMap configurations to Ingress resources depending on the namespace specified in the configuration. The annotation angie.software/configmap allows you to specify a specific ConfigMap for configuring the Ingress resource. The specified ConfigMap will take precedence over the global one. If both the global and specified ConfigMaps are the same, the specified one will be applied.

To apply a specific ConfigMap to an Ingress resource:

Create a ConfigMap specifying the desired namespace.

For example:

kind: ConfigMap
apiVersion: v1
metadata:
  name: echoserver-new-config
  namespace: echoserver-new
data:
  server-snippets: |
    location /echoserver-new-snippet {
          return 302 /echo-test-2;
    }

Specify the annotation angie.software/configmap in the Ingress resource to which you want to apply this ConfigMap.

For example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    angie.software/configmap: "echoserver-new/echoserver-new-config"
  name: echoserver-new
  namespace: echoserver-new
spec:
  ingressClassName: angie
  rules:
  - host: test-new.example.com
    http:
      paths:
      - backend:
          service:
            name: echoserver-new
            port:
              number: 8077
        pathType: ImplementationSpecific

In this example, the annotation angie.software/configmap points to the use of the configuration from the ConfigMap echoserver-new-config. This means that the directives described in server-snippets from this ConfigMap will be applied to the requests handled by this Ingress.

See also the documentation on advanced configuration using annotations.

ConfigMap and VirtualServer, VirtualServerRoute Resources#

ConfigMap affects all VirtualServer and VirtualServerRoute resources. However, the fields of these resources allow overriding some ConfigMap keys. For example, the connect-timeout field of the upstream server takes precedence over the ConfigMap key proxy-connect-timeout.

See the documentation on VirtualServer and VirtualServerRoute Resources.

Summary of ConfigMap Keys#

Note

For all parameters of type boolean, the valid value pairs are true/false, t/f, on/off, and 1/0. Case does not matter.

ANIC (not related to Angie configuration)#

ConfigMap Key	Description	Default	Example
`external-status-address`	Specifies the address that will be displayed in the status of Ingress resources. Requires the command-line argument `-report-status`. Takes precedence over the argument `-external-service`.	N/A	Ingress Status Reporting

General Configuration#

ConfigMap Key	Description	Default
`proxy-connect-timeout`	Sets the value for the directives proxy_connect_timeout and grpc_connect_timeout.	`60s`
`proxy-read-timeout`	Sets the value for the directives proxy_read_timeout and grpc_read_timeout.	`60s`
`proxy-send-timeout`	Sets the value for the directives proxy_send_timeout and grpc_send_timeout.	`60s`
`client-max-body-size`	Sets the value for the directive client_max_body_size.	`1m`
`proxy-buffering`	Enables or disables response buffering from the proxied server.	`True`
`proxy-buffers`	Sets the value for the directive proxy_buffers.	Depends on the platform.
`proxy-buffer-size`	Sets the value for the directives proxy_buffer_size and grpc_buffer_size.	Depends on the platform.
`proxy-max-temp-file-size`	Sets the value for the directive proxy_max_temp_file_size.	`1024m`
`set-real-ip-from`	Sets the value for the directive set_real_ip_from.	N/A
`real-ip-header`	Sets the value for the directive real_ip_header.	`X-Real-IP`
`real-ip-recursive`	Enables or disables the directive real_ip_recursive.	`False`
`default-server-return`	Configures the directive return on the default server, which handles client requests if none of the Ingress or VirtualServer resource backends match. The default value configures Angie to return a 404 error page. You can configure a fixed response or a redirect. For example, the value `default-server-return: 302 https://mysite.ru` will redirect the client to `https://mysite.ru`.	`404`
`server-tokens`	Enables or disables the directive server_tokens.	`True`
`worker-processes`	Sets the value for the directive worker_processes.	`auto`
`worker-rlimit-nofile`	Sets the value for the directive worker_rlimit_nofile.	N/A
`worker-connections`	Sets the value for the directive worker_connections.	`1024`
`worker-cpu-affinity`	Sets the value for the directive worker_cpu_affinity.	N/A
`worker-shutdown-timeout`	Sets the value for the directive worker_shutdown_timeout.	N/A
`server-names-hash-bucket-size`	Sets the value for the directive server_names_hash_bucket_size.	`256`
`server-names-hash-max-size`	Sets the value for the directive server_names_hash_max_size.	`1024`
`map-hash-bucket-size`	Sets the value for the directive map_hash_bucket_size.	`256`
`map-hash-max-size`	Sets the value for the directive map_hash_max_size.	`2048`
`resolver-addresses`	Sets the value for the addresses resolver.	N/A
`resolver-ipv6`	Enables IPv6 resolution in the resolver.	`True`
`resolver-timeout`	Sets the value for resolver_timeout for name resolution.	`30s`
`keepalive-timeout`	Sets the value for the directive keepalive_timeout.	`65s`
`keepalive-requests`	Sets the value for the directive keepalive_requests.	`100`
`variables-hash-bucket-size`	Sets the value for the directive variables_hash_bucket_size.	`256`
`variables-hash-max-size`	Sets the value for the directive variables-hash-max-size.	`1024`

Logging#

ConfigMap Key	Description	Default
`error-log-level`	Sets the global error log level for Angie.	`notice`
`access-log-off`	Disables the access log.	`False`
`default-server-access-log-off`	Disables the access log for the default server. If the access log is disabled globally (`access-log-off: "True"`), the access log for the default server is always disabled.	`False`
`log-format`	Sets a customizable log format for HTTP and HTTPS traffic. For convenience, you can define the log format over multiple lines (lines are separated by the `\n` character). In this case, ANIC will replace each `\n` character with a space. All `'` characters must be escaped.
`log-format-escaping`	Sets the escape characters for log format variables. Supported values: `json` (JSON escaping), `default` (default escaping), `none` (disables escaping).	`default`
`stream-log-format`	Sets a customizable log format for TCP, UDP, and TLS stream traffic. For convenience, you can define the log format over multiple lines (lines are separated by the `\n` character). In this case, ANIC will replace each `\n` character with a space. All `'` characters must be escaped.
`stream-log-format-escaping`	Sets the escape characters for stream log format variables. Supported values: `json` (JSON escaping), `default` (default escaping), `none` (disables escaping).	`default`

Manipulating URIs and Request Headers#

ConfigMap Key	Description	Default	Example
`proxy-hide-headers`	Sets the value for one or more directives proxy_hide_header.	N/A	`"angie.software/proxy-hide-headers": "header-a,header-b"`
`proxy-pass-headers`	Sets the value for one or more directives proxy_pass_header.	N/A	`"angie.software/proxy-pass-headers": "header-a,header-b"`

Authentication, SSL, TLS#

ConfigMap Key	Description	Default
`redirect-to-https`	Sets a 301 redirect rule based on the value of the `http_x_forwarded_proto` header in the server block, requiring that incoming traffic be over HTTPS. Useful when terminating SSL at the load balancer in front of ANIC.	`False`
`ssl-redirect`	Sets an unconditional 301 redirect rule for all incoming HTTP traffic, requiring that incoming traffic be over HTTPS.	`True`
`hsts`	Enables HTTP Strict Transport Security (HSTS) mode: the HSTS header is added to responses from proxied servers. The `preload` directive will be included in the header.	`False`
`hsts-max-age`	Sets the value for the `max-age` directive of the HSTS header.	`2592000` (1 month)
`hsts-include-subdomains`	Adds the `includeSubDomains` directive to the HSTS header.	`False`
`hsts-behind-proxy`	Enables HSTS based on the value of the `http_x_forwarded_proto` request header. Should only be used if TLS termination is configured at the load balancer (proxy server) in front of ANIC. Note To manage the redirect from HTTP to HTTPS, configure the annotation `angie.software/redirect-to-https`.	`False`
`ssl-protocols`	Sets the value for the directive ssl_protocols.	`TLSv1 TLSv1.1 TLSv1.2`
`ssl-prefer-server-ciphers`	Enables or disables the directive ssl_prefer_server_ciphers.	`On`
`ssl-ciphers`	Sets the value for the directive ssl_ciphers.	`HIGH:!aNULL:!MD5`
`ssl-dhparam-file`	Sets the contents of the `dhparam` file. The controller will create the file and set the value for the directive ssl_dhparam with the path to the file.	N/A

Listeners#

ConfigMap Key	Description	Default	Example
`http2`	Enables HTTP/2 on servers with SSL enabled.	`False`
`proxy-protocol`	Enables the proxy protocol for incoming connections.	`False`

Backend Services (Upstreams)#

ConfigMap Key	Description	Default
`lb-method`	Sets the load balancing method. To use the round-robin method, specify `"round_robin"`.	`"random two least_conn"`
`max-fails`	Sets the value for the max_fails parameter of the `server` directive.	`1`
`upstream-zone-size`	Sets the size of the zone of shared memory for upstreams.
`fail-timeout`	Sets the value for the fail_timeout parameter of the `server` directive.	`10s`
`keepalive`	Sets the value for the directive keepalive. Note: if the value is greater than 0, the generated configuration will include `proxy_set_header Connection "";`.	`0`

Snippets and Custom Templates#

ConfigMap Key	Description	Default
`main-snippets`	Sets a custom snippet in the main context.	N/A
`http-snippets`	Sets a custom snippet in the HTTP context.	N/A
`location-snippets`	Sets a custom snippet in the location context.	N/A
`server-snippets`	Sets a custom snippet in the server context.	N/A
`stream-snippets`	Sets a custom snippet in the stream context.	N/A
`main-template`	Sets the main configuration template for Angie.	By default, the template is read from a file in the container.
`ingress-template`	Sets the configuration template for Angie for the Ingress resource.	By default, the template is read from a file in the container.
`virtualserver-template`	Sets the configuration template for Angie for the VirtualServer resource.	By default, the template is read from a file in the container.