add documentation fo HTTP Basic authentication ingress annotations su…

…pport

docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md

@@ -87,6 +87,8 @@ The following Ingress annotations currently have limited or no validation:
 - `nginx.org/proxy-hide-headers`,
 - `nginx.org/proxy-pass-headers`,
 - `nginx.org/rewrites`,
+- `nginx.org/basic-auth-secret`,
+- `nginx.org/basic-auth-realm`,
 - `nginx.com/jwt-key`,
 - `nginx.com/jwt-realm`,
 - `nginx.com/jwt-token`,
@@ -148,6 +150,8 @@ The table below summarizes the available annotations.
 |``nginx.org/hsts-max-age`` | ``hsts-max-age`` | Sets the value of the ``max-age`` directive of the HSTS header. | ``2592000`` (1 month) |  |
 |``nginx.org/hsts-include-subdomains`` | ``hsts-include-subdomains`` | Adds the ``includeSubDomains`` directive to the HSTS header. | ``False`` |  |
 |``nginx.org/hsts-behind-proxy`` | ``hsts-behind-proxy`` | Enables HSTS based on the value of the ``http_x_forwarded_proto`` request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the ``nginx.org/redirect-to-https`` annotation. | ``False`` |  |
+|``nginx.org/basic-auth-secret`` | N/A | Specifies a Secret resource with a user list for HTTP Basic authentication. | N/A | |
+|``nginx.org/basic-auth-realm`` | N/A | Specifies a realm. | N/A | |
 |``nginx.com/jwt-key`` | N/A | Specifies a Secret resource with keys for validating JSON Web Tokens (JWTs). | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). |
 |``nginx.com/jwt-realm`` | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). |
 |``nginx.com/jwt-token`` | N/A | Specifies a variable that contains a JSON Web Token. | By default, a JWT is expected in the ``Authorization`` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). |

examples/basic-auth/README.md

@@ -0,0 +1,112 @@
+# Support for HTTP Basic Authentication
+
+NGINX supports authenticating requests with [ngx_http_auth_basic_module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html).
+
+The Ingress controller provides the following 4 annotations for configuring JWT validation:
+
+* Required: ```nginx.org/basic-auth-secret: "secret"``` -- specifies a Secret resource with a htpasswd user list. The htpasswd must be stored in the `htpasswd` data field. The type of the secret must be `nginx.org/htpasswd`.
+* Optional: ```nginx.org/basic-auth-realm: "realm"``` -- specifies a realm.
+
+```
+
+## Example 1: The Same Htpasswd for All Paths
+
+In the following example we enable HTTP Basic authentication for the cafe-ingress Ingress for all paths using the same htpasswd `cafe-htpasswd`:
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: cafe-ingress
+  annotations:
+    nginx.org/basic-auth-secret: "cafe-passwd"
+    nginx.org/basic-auth-realm: "Cafe App"
+spec:
+  tls:
+  - hosts:
+    - cafe.example.com
+    secretName: cafe-secret
+  rules:
+  - host: cafe.example.com
+    http:
+      paths:
+      - path: /tea
+        backend:
+          serviceName: tea-svc
+          servicePort: 80
+      - path: /coffee
+        backend:
+          serviceName: coffee-svc
+          servicePort: 80
+```
+* The keys must be deployed separately in the Secret `cafe-jwk`.
+* The realm is  `Cafe App`.
+
+## Example 2: a Separate Htpasswd Per Path
+
+In the following example we enable JWT validation for the [mergeable Ingresses](../mergeable-ingress-types) with a separate JWT key per path:
+
+* Master:
+  ```yaml
+  apiVersion: networking.k8s.io/v1
+  kind: Ingress
+  metadata:
+    name: cafe-ingress-master
+    annotations:
+      kubernetes.io/ingress.class: "nginx"
+      nginx.org/mergeable-ingress-type: "master"
+  spec:
+    tls:
+    - hosts:
+      - cafe.example.com
+      secretName: cafe-secret
+    rules:
+    - host: cafe.example.com
+  ```
+
+* Tea minion:
+  ```yaml
+  apiVersion: networking.k8s.io/v1
+  kind: Ingress
+  metadata:
+    name: cafe-ingress-tea-minion
+    annotations:
+      nginx.org/mergeable-ingress-type: "minion"
+      nginx.org/basic-auth-secret: "tea-passwd"
+      nginx.org/basic-auth-realm: "Tea"
+  spec:
+    rules:
+    - host: cafe.example.com
+      http:
+        paths:
+        - path: /tea
+          pathType: Prefix
+          backend:
+            service:
+              name: tea-svc
+              port:
+                number: 80
+  ```
+
+* Coffee minion:
+  ```yaml
+  apiVersion: networking.k8s.io/v1
+  kind: Ingress
+  metadata:
+    name: cafe-ingress-coffee-minion
+    annotations:
+      nginx.org/mergeable-ingress-type: "minion"
+      nginx.org/basic-auth-secret: "coffee-passwd"
+      nginx.org/basic-auth-realm: "Coffee"
+  spec:
+    rules:
+    - host: cafe.example.com
+      http:
+        paths:
+        - path: /coffee
+          pathType: Prefix
+          backend:
+            service:
+              name: coffee-svc
+              port:
+                number: 80
+  ```