Skip to content

Commit 9e07d57

Browse files
akshaysnguptaakshaysngupta
authored
docs: reorganize docs (#295)
1 parent 41693e3 commit 9e07d57

File tree

12 files changed

+340
-325
lines changed

12 files changed

+340
-325
lines changed

‎README.md

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,31 @@
22
[![Build Status](https://travis-ci.org/Azure/application-gateway-kubernetes-ingress.svg?branch=master)](https://travis-ci.org/Azure/application-gateway-kubernetes-ingress)
33
[![Go Report Card](https://goreportcard.com/badge/Azure/application-gateway-kubernetes-ingress)](https://goreportcard.com/report/Azure/application-gateway-kubernetes-ingress)
44

5-
The Application Gateway Ingress Controller allows the [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) to be used as the ingress for an [Azure Kubernetes Service](https://azure.microsoft.com/en-us/services/kubernetes-service/) aka AKS cluster. As shown in the figure below, the ingress controller runs as a pod within the AKS cluster. It consumes [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) and converts them to an Azure Application Gateway configuration which allows the gateway to load-balance traffic to Kubernetes pods.
5+
The Application Gateway Ingress Controller allows [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) to be used as the ingress for an [Azure Kubernetes Service](https://azure.microsoft.com/en-us/services/kubernetes-service/) aka AKS cluster.
6+
7+
As shown in the figure below, the ingress controller runs as a pod within the AKS cluster. It consumes [Kubernetes `Ingress` Resources](http://kubernetes.io/docs/user-guide/ingress/) and converts them to an Azure Application Gateway configuration which allows the gateway to load-balance traffic to Kubernetes pods.
68

79
![Azure Application Gateway + AKS](docs/images/architecture.png)
810

9-
## Setup
10-
* **Greenfield Deployment**: If you are starting from scratch, refer to these [installation](docs/install-new.md) instructions which outlines steps to deploy an AKS cluster with Application Gateway and install application gateway ingress controller on the AKS cluster.
11-
* **Brownfield Deployment**: If you have an existing AKS cluster and Application Gateway, refer to these [installation](docs/install-existing.md) instructions to install application gateway ingress controller on the AKS cluster.
11+
## General
12+
### Setup
13+
* [**Greenfield Deployment**](docs/install-new.md): Refer to these installation instructions if you are starting from scratch. It outline steps to deploy an AKS cluster with Application Gateway and install application gateway ingress controller on the AKS cluster.
14+
* [**Brownfield Deployment**](docs/install-existing.md): Refer to these installation instructions if you have an existing AKS cluster and Application Gateway. It outlines steps to install application gateway ingress controller on the AKS cluster.
15+
16+
### Usage
17+
[**Tutorials**](docs/tutorial.md): Refer to these to understand how you can expose an AKS service over HTTP or HTTPS, to the internet, using an Azure Application Gateway.
18+
19+
[**Features**](docs/features.md): This document maintains a list of available features.
20+
21+
[**Annotations**](docs/annotations.md): The Kubernetes Ingress specification does not allow all features of Application Gateway to be exposed through the ingress resource. Therefore we have introduced application gateway ingress controller specific annotations to expose application gateway features through an ingress resource. Please refer to these to understand the various annotations supported by the ingress controller, and the corresponding features that can be turned on in the application gateway for a given annotation.
22+
23+
[**How-To**](docs/how-to.md): This document maintains a collection of complex scenarios.
1224

13-
## Usage
14-
Refer to the [tutorials](docs/tutorial.md) to understand how you can expose an AKS service over HTTP or HTTPS, to the internet, using an Azure Application Gateway.
25+
### Troubleshooting
26+
For troubleshooting, please refer to this [guide](docs/troubleshooting.md).
1527

16-
## Annotations
17-
The Kubernetes Ingress specification does not allow all features of Application Gateway to be exposed through the ingress resource. Therefore we have introduced application gateway ingress controller specific annotations to expose application gateway features through an ingress resource. Please refer to the [annotations](docs/annotations.md) to understand the various annotations supported by the ingress controller, and the corresponding features that can be turned on in the application gateway for a given annotation.
28+
### Frequently asked questions
29+
For FAQ, please refer to this [guide](docs/faq.md).
1830

1931
## Reporting Issues
2032
The best way to report an issue is to create a Github Issue for the project. Please include the following information when creating the issue:

‎docs/examples/aadpodidentity/aadpodidbinding.yaml

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎docs/examples/aadpodidentity/aadpodidentity.yaml

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/faq.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Frequrently Asked Questions: [WIP]
2+
3+
* [What is an Ingress Controller?](#what-is-an-ingress-controller?)
4+
* [Can single ingress controller instance manage multiple Application Gateway?](#can-single-ingress-controller-instance-manage-multiple-application-gateway?)
5+
6+
## What is an Ingress Controller?
7+
Kubernetes allows creation of `deployment` and `service` resource to expose a group of pods internally in the cluster. To expose the same service externally, an [`Ingress`](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource is defined which provides load balancing, SSL termination and name-based virtual hosting.
8+
To satify this `Ingress` resource, an Ingress Controller is required which listens for any changes to `Ingress` resources and configures the load balancer policies.
9+
10+
The Application Gateway Ingress Controller allows [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) to be used as the ingress for an [Azure Kubernetes Service](https://azure.microsoft.com/en-us/services/kubernetes-service/) aka AKS cluster.
11+
12+
13+
## Can single ingress controller instance manage multiple Application Gateway?
14+
Currently, One instance of Ingress Controller can only be associated to one Application Gateway.

‎docs/features.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Features
2+
3+
* [Backend Health Probes](features/probes.md)
4+
* [Cookie Based Affinity](features/cookie-affinity.md)

‎docs/features/cookie-affinity.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Enable Cookie based Affinity
2+
As outlined in the [Azure Application Gateway Documentation](https://docs.microsoft.com/en-us/azure/application-gateway/application-gateway-components#http-settings), Application Gateway supports cookie based affinity enabling which it can direct subsequent traffic from a user session to the same server for processing.
3+
4+
### Example
5+
```yaml
6+
apiVersion: extensions/v1beta1
7+
kind: Ingress
8+
metadata:
9+
name: guestbook
10+
annotations:
11+
kubernetes.io/ingress.class: azure/application-gateway
12+
appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
13+
spec:
14+
rules:
15+
- http:
16+
paths:
17+
- backend:
18+
serviceName: frontend
19+
servicePort: 80
20+
```

‎docs/features/probes.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
## Adding Health Probes to your service
2+
By default, Ingress controller will provision an HTTP GET probe for the exposed pods.
3+
The probe properties can be customized by adding a [Readiness or Liveness Probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/) to your `deployment`/`pod` spec.
4+
5+
### With `readinessProbe` or `livenessProbe`
6+
```yaml
7+
apiVersion: extensions/v1beta1
8+
kind: Deployment
9+
metadata:
10+
name: aspnetapp
11+
spec:
12+
replicas: 3
13+
template:
14+
metadata:
15+
labels:
16+
service: site
17+
spec:
18+
containers:
19+
- name: aspnetapp
20+
image: mcr.microsoft.com/dotnet/core/samples:aspnetapp
21+
imagePullPolicy: IfNotPresent
22+
ports:
23+
- containerPort: 80
24+
readinessProbe:
25+
httpGet:
26+
path: /
27+
port: 80
28+
periodSeconds: 3
29+
timeoutSeconds: 1
30+
```
31+
32+
Kubernetes API Reference:
33+
* [Container Probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes)
34+
* [HttpGet Action](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#httpgetaction-v1-core)
35+
36+
*Note:*
37+
1) `readinessProbe` and `livenessProbe` are supported when configured with `httpGet`.
38+
2) Probing on a port other than the one exposed on the pod is currently not supported.
39+
3) `HttpHeaders`, `InitialDelaySeconds`, `SuccessThreshold` are not supported.
40+
41+
### Without `readinessProbe` or `livenessProbe`
42+
If the above probes are not provided, then Ingress Controller make an assumption that the service is reachable on `Path` specified for `backend-path-prefix` annotation or the `path` specified in the `ingress` definition for the service.
43+
44+
### Default Values for Health Probe
45+
For any property that can not be inferred by the readiness/liveness probe, Default values are set.
46+
47+
| Application Gateway Probe Property | Default Value |
48+
|-|-|
49+
| `Path` | / |
50+
| `Host` | localhost |
51+
| `Protocol` | HTTP |
52+
| `Timeout` | 30 |
53+
| `Interval` | 30 |
54+
| `UnhealthyThreshold` | 3 |

‎docs/how-to.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# How-Tos
2+
3+
* [How to integrate with `lets encrypt` for automatic certificate issuance and rotation ?](how-tos/lets-encrypt.md)
4+
* [How to expose a WebSocket server ?](how-tos/websockets.md)

‎docs/how-tos/lets-encrypt.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
## Certificate issuance with LetsEncrypt.org
2+
3+
This section configures your AKS to leverage [LetsEncrypt.org](https://letsencrypt.org/) and automatically obtain a
4+
TLS/SSL certificate for your domain. The certificate will be installed on Application Gateway, which will perform
5+
SSL/TLS termination for your AKS cluster. The setup described here uses the
6+
[cert-manager](https://github.com/jetstack/cert-manager) Kubernetes add-on, which automates the creation and management of
7+
certificates.
8+
9+
Follow the steps below to install [cert-manager](https://docs.cert-manager.io) on your existing AKS cluster.
10+
11+
##### 1. Helm Chart
12+
13+
Run the following script to install the `cert-manager` helm chart. This will:
14+
- create a new `cert-manager` namespace on your AKS
15+
- create the following CRDs: Certificate, Challenge, ClusterIssuer, Issuer, Order
16+
- install cert-manager chart (from [docs.cert-manager.io)](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#steps)
17+
18+
19+
```bash
20+
#!/bin/bash
21+
22+
# Install the CustomResourceDefinition resources separately
23+
kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.8/deploy/manifests/00-crds.yaml
24+
25+
# Create the namespace for cert-manager
26+
kubectl create namespace cert-manager
27+
28+
# Label the cert-manager namespace to disable resource validation
29+
kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true
30+
31+
# Add the Jetstack Helm repository
32+
helm repo add jetstack https://charts.jetstack.io
33+
34+
# Update your local Helm chart repository cache
35+
helm repo update
36+
37+
# Install the cert-manager Helm chart
38+
helm install \
39+
--name cert-manager \
40+
--namespace cert-manager \
41+
--version v0.8.0 \
42+
jetstack/cert-manager
43+
```
44+
45+
##### 2. ClusterIssuer Resource
46+
47+
Create a `ClusterIssuer` resource. It is required by `cert-manager` to represent the `Lets Encrypt` certificate
48+
authority where the signed certificates will be obtained.
49+
50+
By using the non-namespaced `ClusterIssuer` resource, cert-manager will issue certificates that can be consumed from
51+
multiple namespaces. `Let’s Encrypt` uses the ACME protocol to verify that you control a given domain name and to issue
52+
you a certificate. More details on configuring `ClusterIssuer` properties
53+
[here](https://docs.cert-manager.io/en/latest/tasks/issuers/index.html). `ClusterIssuer` will instruct `cert-manager`
54+
to issue certificates using the `Lets Encrypt` staging environment used for testing (the root certificate not present
55+
in browser/client trust stores).
56+
57+
The default challenge type in the YAML below is `http01`. Other challenges are documented on [letsencrypt.org - Challenge Types](https://letsencrypt.org/docs/challenge-types/)
58+
59+
**IMPORTANT:** Update `<YOUR.EMAIL@ADDRESS>` in the YAML below
60+
61+
```bash
62+
#!/bin/bash
63+
kubectl apply -f - <<EOF
64+
apiVersion: certmanager.k8s.io/v1alpha1
65+
kind: ClusterIssuer
66+
metadata:
67+
name: letsencrypt-staging
68+
spec:
69+
acme:
70+
# You must replace this email address with your own.
71+
# Let's Encrypt will use this to contact you about expiring
72+
# certificates, and issues related to your account.
73+
email: <YOUR.EMAIL@ADDRESS>
74+
# ACME server URL for Let’s Encrypt’s staging environment.
75+
# The staging environment will not issue trusted certificates but is
76+
# used to ensure that the verification process is working properly
77+
# before moving to production
78+
server: https://acme-staging-v02.api.letsencrypt.org/directory
79+
privateKeySecretRef:
80+
# Secret resource used to store the account's private key.
81+
name: example-issuer-account-key
82+
# Enable the HTTP-01 challenge provider
83+
# you prove ownership of a domain by ensuring that a particular
84+
# file is present at the domain
85+
http01: {}
86+
EOF
87+
```
88+
89+
##### 3. Deploy App
90+
91+
Create an Ingress resource to Expose the `guestbook` application using the Application Gateway with the Lets Encrypt Certificate.
92+
93+
Ensure you Application Gateway has a public Frontend IP configuration with a DNS name (either using the
94+
default `azure.com` domain, or provision a `Azure DNS Zone` service, and assign your own custom domain).
95+
Note the annotation `certmanager.k8s.io/cluster-issuer: letsencrypt-staging`, which tells cert-manager to process the
96+
tagged Ingress resource.
97+
98+
**IMPORTANT:** Update `<PLACEHOLDERS.COM>` in the YAML below with your own domain (or the Application Gateway one, for example
99+
'kh-aks-ingress.westeurope.cloudapp.azure.com')
100+
101+
```bash
102+
kubectl apply -f - <<EOF
103+
apiVersion: extensions/v1beta1
104+
kind: Ingress
105+
metadata:
106+
name: guestbook-letsencrypt-staging
107+
annotations:
108+
kubernetes.io/ingress.class: azure/application-gateway
109+
certmanager.k8s.io/cluster-issuer: letsencrypt-staging
110+
spec:
111+
tls:
112+
- hosts:
113+
- <PLACEHOLDERS.COM>
114+
secretName: guestbook-secret-name
115+
rules:
116+
- host: <PLACEHOLDERS.COM>
117+
http:
118+
paths:
119+
- backend:
120+
serviceName: frontend
121+
servicePort: 80
122+
EOF
123+
```
124+
125+
After a few seconds, you can access the `guestbook` service through the Application Gateway HTTPS url using the automatically issued **staging** `Lets Encrypt` certificate.
126+
Your browser may warn you of an invalid cert authority. The staging certificate is issued by `CN=Fake LE Intermediate X1`. This is an indication that the system worked as expected and you are ready for your production certificate.
127+
128+
129+
##### 4. Production Certificate
130+
Once your staging certificate is setup successfully you can switch to a production ACME server:
131+
1. Replace the staging annotation on your Ingress resource with: `certmanager.k8s.io/cluster-issuer: letsencrypt-prod`
132+
2. Delete the existing staging `ClusterIssuer` you created in the previous step and create a new one by replacing the ACME server from the ClusterIssuer YAML above with `https://acme-v02.api.letsencrypt.org/directory`
133+
134+
##### 5. Certificate Expiration and Renewal
135+
Before the `Lets Encrypt` certificate expires, `cert-manager` will automatically update the certificate in the Kubernetes secret store. At that point, Application Gateway Ingress Controller will apply the updated secret referenced in the ingress resources it is using to configure the Application Gateway.

‎docs/how-tos/websockets.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
## Expose a WebSocket server
2+
3+
As outlined in the Application Gateway v2 documentation - it [provides native support for the WebSocket and HTTP/2 protocols](https://docs.microsoft.com/en-us/azure/application-gateway/overview#websocket-and-http2-traffic). Please note, that for both Application Gateway and the Kubernetes Ingress - there is no user-configurable setting to selectively enable or disable WebSocket support.
4+
5+
The Kubernetes deployment YAML below shows the minimum configuration used to deploy a WebSocket server, which is the same as deploying a regular web server:
6+
```yaml
7+
apiVersion: apps/v1
8+
kind: Deployment
9+
metadata:
10+
name: websocket-server
11+
spec:
12+
selector:
13+
matchLabels:
14+
app: ws-app
15+
replicas: 2
16+
template:
17+
metadata:
18+
labels:
19+
app: ws-app
20+
spec:
21+
containers:
22+
- name: websocket-app
23+
imagePullPolicy: Always
24+
image: your-container-repo.azurecr.io/websockets-app
25+
ports:
26+
- containerPort: 8888
27+
imagePullSecrets:
28+
- name: azure-container-registry-credentials
29+
30+
---
31+
32+
apiVersion: v1
33+
kind: Service
34+
metadata:
35+
name: websocket-app-service
36+
spec:
37+
selector:
38+
app: ws-app
39+
ports:
40+
- protocol: TCP
41+
port: 80
42+
targetPort: 8888
43+
44+
---
45+
46+
apiVersion: extensions/v1beta1
47+
kind: Ingress
48+
metadata:
49+
name: websocket-repeater
50+
annotations:
51+
kubernetes.io/ingress.class: azure/application-gateway
52+
spec:
53+
rules:
54+
- host: ws.contoso.com
55+
http:
56+
paths:
57+
- backend:
58+
serviceName: websocket-app-service
59+
servicePort: 80
60+
```
61+
62+
Given that all the prerequisites are fulfilled, and you have an App Gateway controlled by a K8s Ingress in your AKS, the deployment above would result in a WebSockets server exposed on port 80 of your App Gateway's public IP and the `ws.contoso.com` domain.
63+
64+
The following cURL command would test the WebSocket server deployment:
65+
```sh
66+
curl -i -N -H "Connection: Upgrade" \
67+
-H "Upgrade: websocket" \
68+
-H "Origin: http://localhost" \
69+
-H "Host: ws.contoso.com" \
70+
-H "Sec-Websocket-Version: 13" \
71+
-H "Sec-WebSocket-Key: 123" \
72+
http://1.2.3.4:80/ws
73+
```
74+
75+
##### WebSocket Health Probes
76+
77+
If your deployment does not explicitly define health probes, App Gateway would attempt an HTTP GET on your WebSocket server endpoint.
78+
Depending on the server implementation ([here is one we love](https://github.com/gorilla/websocket/blob/master/examples/chat/main.go)) WebSocket specific headers may be required (`Sec-Websocket-Version` for instance).
79+
Since App Gateway does not add WebSocket headers, the App Gateway's health probe response from your WebSocket server will most likely be `400 Bad Request`.
80+
As a result App Gateway will mark your pods as unhealthy, which will eventually result in a `502 Bad Gateway` for the consumers of the WebSocket server.
81+
To avoid this you may need to add an HTTP GET handler for a health check to your server (`/health` for instance, which returns `200 OK`).

0 commit comments

Comments
 (0)