Extended Configuration with Annotations#
This section explains how to enable advanced functionality in ANIC using annotations.
The Ingress resource can utilize basic features of Angie, such as host-based or path-based routing and TLS termination. Advanced features, such as request URI rewriting or inserting additional response headers, can be enabled using annotations.
In addition to advanced features, annotations are necessary for configuring Angie's behavior, such as setting connection timeout values.
Configuration is also available through ConfigMap resources: annotations take precedence.
Using Annotations#
This example uses annotations to configure the Ingress resource:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-with-annotations
annotations:
``angie.software/proxy-connect-timeout: "30s"
``angie.software/proxy-read-timeout: "20s"
``angie.software/client-max-body-size: "4m"
``angie.software/server-snippets: |
location / {
return 302 /coffee;
}
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
Validation#
ANIC checks the annotations of Ingress resources. If the Ingress is invalid, ANIC will reject it: the Ingress will continue to exist in the cluster, but ANIC will ignore it.
You can check whether ANIC successfully applied the configuration for the Ingress resource. For the Ingress example cafe-ingress-with-annotations, you can run the following command:
$ kubectl describe ing cafe-ingress-with-annotations
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 3s angie-ingress-controller Configuration for default/cafe-ingress-with-annotations was added or updated
The events section includes a Normal event with the reason AddedOrUpdated, which informs us that the configuration was successfully applied.
If you create an invalid Ingress, ANIC will reject it and generate a Rejected event. For example, if you create the Ingress cafe-ingress-with-annotations with the annotation angie.software/redirect-to-https set to yes please instead of true, you will get:
$ kubectl describe ing cafe-ingress-with-annotations
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning Rejected 13s angie-ingress-controller annotations.``angie.software/redirect-to-https: Invalid value: "yes please": must be a boolean
Note that the events section includes a Warning event with the reason Rejected.
Note
If you make an existing Ingress invalid, ANIC will reject it and remove the corresponding configuration from ANIC.
Summary of Annotations#
The table below lists the available annotations.
General Configuration#
Annotation |
ConfigMap Key |
Description |
Default Value |
Example |
|---|---|---|---|---|
|
|
Sets the value for the proxy_connect_timeout and grpc_connect_timeout directives. |
|
|
|
|
Sets the value for the proxy_read_timeout and grpc_read_timeout directives. |
|
|
|
|
Sets the value for the proxy_send_timeout and grpc_send_timeout directives. |
|
|
|
|
Sets the value for the client_max_body_size directive. |
|
|
|
|
Enables or disables response buffering from the proxied server. |
|
|
|
|
Sets the value for the proxy_buffers directive. |
Depends on platform. |
|
|
|
Sets the value for the proxy_buffer_size and grpc_buffer_size directives. |
Depends on platform. |
|
|
|
Sets the value for the proxy_max_temp_file_size directive. |
|
|
|
|
Enables or disables the server_tokens directive. Additionally, with Angie, a string value can be specified, including an empty string, which disables the "Server" field output. |
|
|
|
None |
Enables regular expression modifiers for the Ingress path parameter. This corresponds to the Angie location directive. One of the following values can be specified: "case_sensitive", "case_insensitive", or "exact". The annotation applies to the Ingress resource and its paths. When using Master and Minion Ingresses (i.e., Mergeable Ingresses), this annotation can be specified for Minion types. The |
None |
|
|
None |
Allows specifying a specific ConfigMap for configuring the Ingress resource. The specified ConfigMap will take precedence over the global one. If the global and specified ConfigMaps match, the specified one will be applied. Example: |
|
Manipulating URI and Request Headers#
Annotation |
ConfigMap Key |
Description |
Default Value |
Example |
|---|---|---|---|---|
|
|
Sets the value for one or more proxy_hide_header directives. Example: |
None |
|
|
|
Sets the value for one or more proxy_pass_header directives. Example: |
None |
|
|
None |
Configures URI rewriting using the proxy_pass directive. |
None |
Authentication and SSL/TLS#
Annotation |
ConfigMap Key |
Description |
Default Value |
Example |
|---|---|---|---|---|
|
|
Sets a 301 redirect rule based on the value of the |
|
|
|
|
Sets a non-conditional 301 redirect rule for all incoming HTTP traffic, to force incoming traffic to go through HTTPS. |
|
|
|
|
Enables HTTP Strict Transport Security (HSTS) <https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/>: the HSTS header is added to responses from proxied servers. The directive |
|
|
|
|
Sets the value for the |
|
|
|
|
Adds the |
|
|
|
|
Enables HSTS based on the value of the Note To manage the redirect from HTTP to HTTPS, configure the annotation |
|
|
|
None |
Specifies a Secret resource with a list of users for HTTP Basic authentication. |
None |
|
|
None |
Specifies the realm. |
None |
Listeners#
Annotation |
ConfigMap Key |
Description |
Default Value |
Example |
|---|---|---|---|---|
|
None |
Configures the HTTP ports on which Angie will listen. |
|
|
|
None |
Configures the HTTPS ports on which Angie will listen. |
|
Backend Services (Upstreams)#
Annotation |
ConfigMap Key |
Description |
Default Value |
Example |
|---|---|---|---|---|
|
|
Sets the load balancing method. To use the round-robin method, specify |
|
|
|
None |
Enables HTTPS or gRPC over SSL when connecting to service endpoints. |
None |
|
|
None |
Enables gRPC for services. Note Requires HTTP/2 (see the |
None |
|
|
None |
Enables WebSocket for services. |
None |
|
|
|
Sets the value for the max_fails parameter of the |
|
|
|
None |
Sets the value for the max_conns parameter of the |
|
|
|
|
Sets the size of the shared memory zone for the upstream. For Angie, a special value of 0 disables shared memory zones. For Angie, shared memory zones are required and cannot be disabled. A special value of 0 will be ignored. |
|
|
|
|
Sets the value for the fail_timeout parameter of the |
|
|
|
None |
Configures session persistence. |
None |
|
|
None |
Configures session persistence. |
None |
|
|
|
Sets the value for the keepalive directive. Note that |
|
|
|
None |
Enables active health checks. |
|
|
|
None |
Configures active health checks as mandatory. |
|
|
|
None |
When active health checks are mandatory, creates a queue where incoming requests are temporarily stored while Angie checks the health of endpoints after configuration reload. |
|
|
|
None |
Sets the slow start period for the server for the upstream. By default, slow start is activated after the server becomes available or healthy. To enable slow start for newly assigned servers, configure mandatory active health checks. |
|
|
|
None |
Enables the use of the service cluster IP and port instead of the default behavior, which uses the pod IP and port. When this field is enabled, fields that configure Angie behavior related to multiple upstreams (such as |
|
Rate Limiting#
Annotation |
ConfigMap Key |
Description |
Default Value |
Example |
|---|---|---|---|---|
|
None |
Enables request rate limiting for this Ingress by creating a limit_req_zone and applying limit_req for each location. All servers/locations of a single Ingress use one zone. Must have a unit of r/s or r/m. |
None |
200r/s |
|
None |
The key to which the rate limit applies. Can contain text, variables, or their combination. Variables must be enclosed in ${}. |
${binary_remote_addr} |
${binary_remote_addr} |
|
None |
Configures the size of the created limit_req_zone. |
10m |
20m |
|
None |
Configures the delay parameter of the limit_req directive. |
0 |
100 |
|
None |
Configures the nodelay parameter of the limit_req directive. |
false |
true |
|
None |
Configures the burst parameter of the limit_req directive. |
None |
100 |
|
None |
Enables dry-run mode. In this mode, rate limiting is not applied, but the number of excess requests is counted as usual in the shared memory zone. |
false |
true |
|
None |
Sets the desired logging level for cases when the server refuses to process requests due to rate limits or delays in request processing. Allowed values: info, notice, warn, or error. |
error |
info |
|
None |
Sets the status code returned in response to rejected requests. Must be in the range 400..599. |
429 |
503 |
|
None |
Enables constant rate limiting by dividing the configured rate value by the number of Ingress pods currently serving traffic. This adjustment ensures consistent rate limiting even if the number of pods changes due to autoscaling. Note This will not work correctly if client requests are not evenly distributed across all Ingress pods (session affinity, long-lived TCP connections with multiple requests, etc.). In such cases, the best results will be achieved by using Angie’s zone synchronization feature. |
false |
true |
Snippets and Custom Templates#
Annotation |
ConfigMap Key |
Description |
Default Value |
Example |
|---|---|---|---|---|
|
|
Sets a custom snippet in the context of location. |
None |
|
|
|
Sets a custom snippet in the context of server. |
None |