Custom Annotations

[pleshakov]

Is your feature request related to a problem? Please describe.

We need an easy way to allow the user to use advanced features of NGINX in the Ingress Controller, especially for the case with a separate Ingress controller admin and multiple users.

Currently, to use NGINX features that are not currently supported with annotations/configmap keys, the user need to use snippets or a custom template. Consider the case when an Ingress Controller admin prepares a custom template with advanced features and multiple users who want to selectively enable those features. How do we allow that?

Describe the solution you'd like

Allow extending NGINX configuration with advanced features (ex., rate limiting) and have an easy way to enable/disable those features per an Ingress resource.

Describe alternatives you've considered

An alternative is to use snippets to insert NGINX config per Ingress, which means the user must deal with NGINX config directly. Or, extend the Ingress Controller to support new annotations. But that requires changing the code of the Ingress Controller.

Additional context
This feature proposes to address #352

Suggested Design

In the Ingress template we will allow direct access to annotations through the Annotations field, which will contain all annotations of a particular Ingress resource.

Let's assume that we have a single Ingress Controller shared by 2 teams - A and B. The Ingress Controller is managed by an admin who is not part of any of those team. The admin wants to add features to the NGINX template: the feature A will be used by the team A, the feature B will be used by the team B.

Let's see how we can accomplish that:

Consider the following excerpt from the NGINX template, which includes features A and B:

{{if index .Annotations "custom.nginx.org/feature-a"}}
# insert config for  feature A
{{end}}
{{if index .Annotations "custom.nginx.org/feature-b"}}
# insert config for  feature B
{{end}}

We place that excerpt in the configmap as a server-snippet:

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-config
  namespace: nginx-ingress
data:
  server-snippets: |
     {{if index .Annotations "custom.nginx.org/feature-a"}}
     # insert config for  feature A
     {{end}}
     {{if index .Annotations "custom.nginx.org/feature-b"}}
      # insert config for  feature B
     {{end}}

Now team A can use the feature A in their Ingress resource:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: team-A-Ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
    custom.nginx.org/feature-a: "true" # any not empty value would work
spec:
  rules:
  - host: teamA.example.com
    http:
      paths:
      - path: /tea
        backend:
          serviceName: tea-svc
          servicePort: 80

The generated config for team-A-Ingress will have the feature A, but not the feature B.

Team B can use the feature B in their Ingress resource:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: team-B-Ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
    custom.nginx.org/feature-b: "true" # any not empty value would work
spec:
  rules:
  - host: teamB.example.com
    http:
      paths:
      - path: /coffee
        backend:
          serviceName: coffee-svc
          servicePort: 80

The generated config for team-B-Ingress will have the feature B, but not the feature A.

[pleshakov]

thanks, the feature was merged #375

It is available in the edge version now. See https://github.com/nginxinc/kubernetes-ingress/#nginx-ingress-controller-releases
It will be available in 1.4.0 release

Feature doc -- https://github.com/nginxinc/kubernetes-ingress/blob/master/docs/custom-annotations.md
Feature example -- https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/custom-annotations