You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Configure ingress with Azure Kubernetes Service (AKS) cluster
3
-
description: Install and configure an NGINX ingress controller in an Azure Kubernetes Service (AKS) cluster.
3
+
description: Learn how to install and configure an NGINX ingress controller that uses Let's Encrypt for automatic SSL certificate generation in an Azure Kubernetes Service (AKS) cluster.
4
4
services: container-service
5
5
author: iainfoulds
6
6
manager: jeconnoc
7
7
8
8
ms.service: container-service
9
9
ms.topic: article
10
-
ms.date: 06/25/2018
10
+
ms.date: 07/17/2018
11
11
ms.author: iainfou
12
12
ms.custom: mvc
13
13
---
14
14
15
-
# HTTPS Ingress on Azure Kubernetes Service (AKS)
15
+
# Deploy an HTTPS ingress controller on Azure Kubernetes Service (AKS)
16
16
17
17
An ingress controller is a piece of software that provides reverse proxy, configurable traffic routing, and TLS termination for Kubernetes services. Kubernetes ingress resources are used to configure the ingress rules and routes for individual Kubernetes services. Using an ingress controller and ingress rules, a single external address can be used to route traffic to multiple services in a Kubernetes cluster.
18
18
19
-
This document walks through a sample deployment of the [NGINX ingress controller][nginx-ingress] in an Azure Kubernetes Service (AKS) cluster. Additionally, the [cert-manager][cert-manager] project is used to automatically generate and configure [Let's Encrypt][lets-encrypt] certificates. Finally, several applications are run in the AKS cluster, each of which is accessible over a single address.
19
+
This article shows you how to deploy the [NGINX ingress controller][nginx-ingress] in an Azure Kubernetes Service (AKS) cluster. The [cert-manager][cert-manager] project is used to automatically generate and configure [Let's Encrypt][lets-encrypt] certificates. Finally, several applications are run in the AKS cluster, each of which is accessible over a single address.
20
+
21
+
## Before you begin
22
+
23
+
This article uses Helm to install the NGINX ingress controller, cert-manager, and a sample web app. You need to have Helm initialized within your AKS cluster and using a service account for Tiller. For more information on configuring and using Helm, see [Install applications with Helm in Azure Kubernetes Service (AKS)][use-helm].
24
+
25
+
This article also requires that you are running the Azure CLI version 2.0.41 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install].
20
26
21
27
## Install an ingress controller
22
28
23
-
Use Helm to install the NGINX ingress controller. See the NGINX ingress controller [documentation][nginx-ingress] for detailed deployment information.
29
+
Use Helm to install the NGINX ingress controller. For detailed deployment information, see the [NGINX ingress controller documentation][nginx-ingress].
24
30
25
-
This example installs the controller in the `kube-system` namespace, this can be modified to a namespace of your choice. If your AKS cluster is not RBAC enabled, add `--set rbac.create=false` to the command. For more information, see the [nginx-ingress chart][nginx-ingress].
31
+
The following example installs the controller in the `kube-system` namespace. You can specify a different namespace for your own environment. If your AKS cluster is not RBAC enabled, add `--set rbac.create=false` to the command.
During the installation, an Azure public IP address is created for the ingress controller. To get the public IP address, use the kubectl get service command. It may take some time for the IP address to be assigned to the service.
37
+
During the installation, an Azure public IP address is created for the ingress controller. To get the public IP address, use the `kubectl get service` command. It takes a few minutes for the IP address to be assigned to the service.
32
38
33
-
```console
39
+
```
34
40
$ kubectl get service -l app=nginx-ingress --namespace kube-system
Because no ingress rules have been created, if you browse to the public IP address, you are routed to the NGINX ingress controllers default 404 page.
47
+
No ingress rules have been created yet. If you browse to the public IP address, the NGINX ingress controller's default 404 page is displayed, as shown in the following example:
Because HTTPS certificates are used, you need to configure an FQDN name for the ingress controllers IP address. For this example, an Azure FQDN is created with the Azure CLI. Update the script with the IP address of the ingress controller and the name that you would like to use in the FQDN.
53
+
For the HTTPS certificates to work correctly, configure an FQDN for the ingress controller IP address. Update the following script with the IP address of your ingress controller and a unique name that you would like to use for the FQDN:
48
54
49
-
```bash
55
+
```console
50
56
#!/bin/bash
51
57
52
-
# Public IP address
58
+
# Public IP address of your ingress controller
53
59
IP="51.145.155.210"
54
60
55
61
# Name to associate with public IP address
@@ -58,59 +64,70 @@ DNSNAME="demo-aks-ingress"
58
64
# Get the resource-id of the public ip
59
65
PUBLICIPID=$(az network public-ip list --query "[?ipAddress!=null]|[?contains(ipAddress, '$IP')].[id]" --output tsv)
60
66
61
-
# Update public ip address with dns name
67
+
# Update public ip address with DNS name
62
68
az network public-ip update --ids $PUBLICIPID --dns-name $DNSNAME
63
69
```
64
70
65
-
The ingress controller should now be accessible through the FQDN.
71
+
The ingress controller is now accessible through the FQDN.
66
72
67
73
## Install cert-manager
68
74
69
-
The NGINX ingress controller supports TLS termination. While there are several ways to retrieve and configure certificates for HTTPS, this document demonstrates using [cert-manager][cert-manager], which provides automatic [Lets Encrypt][lets-encrypt] certificate generation and management functionality.
75
+
The NGINX ingress controller supports TLS termination. There are several ways to retrieve and configure certificates for HTTPS. This article demonstrates using [cert-manager][cert-manager], which provides automatic [Lets Encrypt][lets-encrypt] certificate generation and management functionality.
70
76
71
-
To install the cert-manager controller, use the following Helm install command.
77
+
> [!NOTE]
78
+
> This article uses the `staging` environment for Let's Encrypt. In production deployments, use `letsencrypt-prod` and `https://acme-v02.api.letsencrypt.org/directory` in the resource definitions and when installing the Helm chart.
For more information on cert-manager configuration, see the [cert-manager project][cert-manager].
88
97
89
-
## Create CA cluster issuer
98
+
## Create a CA cluster issuer
90
99
91
-
Before certificates can be issued, cert-manager requires an [Issuer][cert-manager-issuer] or [ClusterIssuer][cert-manager-cluster-issuer] resource. The resources are identical in functionality however `Issuer` works in a single namespace where`ClusterIssuer` works across all namespaces. For more information, see the [cert-manager issuer][cert-manager-issuer] documentation.
100
+
Before certificates can be issued, cert-manager requires an [Issuer][cert-manager-issuer] or [ClusterIssuer][cert-manager-cluster-issuer] resource. These Kubernetes resources are identical in functionality, however `Issuer` works in a single namespace, and`ClusterIssuer` works across all namespaces. For more information, see the [cert-manager issuer][cert-manager-issuer] documentation.
92
101
93
-
Create a cluster issuerusing the following manifest. Update the email address with a valid address from your organization.
102
+
Create a cluster issuer, such as `cluster-issuer.yaml`, using the following example manifest. Update the email address with a valid address from your organization:
To create the issuer, use the `kubectl create -f cluster-issuer.yaml` command.
119
+
120
+
```
121
+
$ kubectl create -f cluster-issuer.yaml
122
+
123
+
clusterissuer.certmanager.k8s.io/letsencrypt-prod created
124
+
```
125
+
126
+
## Create a certificate object
110
127
111
-
Next, a certificate resource must be created. The certificate resource defines the desired X.509 certificate. For more information, see, [cert-manager certificates][cert-manager-certificates].
128
+
Next, a certificate resource must be created. The certificate resource defines the desired X.509 certificate. For more information, see [cert-manager certificates][cert-manager-certificates].
112
129
113
-
Create the certificate resourcewith the following manifest.
130
+
Create the certificate resource, such as `certificates.yaml`, with the following example manifest. Update the *dnsNames* and *domains* to the DNS name you created in a previous step.
114
131
115
132
```yaml
116
133
apiVersion: certmanager.k8s.io/v1alpha1
@@ -128,43 +145,47 @@ spec:
128
145
domains:
129
146
- demo-aks-ingress.eastus.cloudapp.azure.com
130
147
issuerRef:
131
-
name: letsencrypt-prod
148
+
name: letsencrypt-staging
132
149
kind: ClusterIssuer
133
150
```
134
151
135
-
## Run application
152
+
To create the certificate resource, use the `kubectl create -f certificates.yaml` command.
153
+
154
+
```
155
+
$ kubectl create -f certificates.yaml
156
+
157
+
certificate.certmanager.k8s.io/tls-secret created
158
+
```
136
159
137
-
At this point, an ingress controller and a certificate management solution have been configured. Now run a few applications in your AKS cluster.
160
+
## Run demo applications
138
161
139
-
For this example, Helm is used to run multiple instances of a simple hello world application.
162
+
An ingress controller and a certificate management solution have been configured. Now let's run two demo applications in your AKS cluster. In this example, Helm is used to deploy two instances of a simple 'Hello world' application.
140
163
141
-
Before running the application, add the Azure samples Helm repository on your development system.
164
+
Before you can install the sample Helm charts, add the Azure samples repository to your Helm environment as follows:
Run the AKS hello world chart with the following command:
170
+
Create the first demo application from a Helm chart with the following command:
148
171
149
-
```bash
172
+
```console
150
173
helm install azure-samples/aks-helloworld
151
174
```
152
175
153
-
Now install a second instance of the hello world application.
154
-
155
-
For the second instance, specify a new title so that the two applications are visually distinct. You also need to specify a unique service name. These configurations can be seen in the following command.
176
+
Now install a second instance of the demo application. For the second instance, you specify a new title so that the two applications are visually distinct. You also specify a unique service name:
Both applications are now running on your Kubernetes cluster, however have been configured with a service of type `ClusterIP`. As such, the applications are not accessible from the internet. In order to make them available, create a Kubernetes ingress resource. The ingress resource configures the rules that route traffic to one of the two applications.
184
+
Both applications are now running on your Kubernetes cluster, however they're configured with a service of type `ClusterIP`. As such, the applications aren't accessible from the internet. To make them publicly available, create a Kubernetes ingress resource. The ingress resource configures the rules that route traffic to one of the two applications.
164
185
165
-
Create a file name `hello-world-ingress.yaml`and copy in the following YAML.
186
+
In the following example, traffic to the address `https://demo-aks-ingress.eastus.cloudapp.azure.com/` is routed to the service named `aks-helloworld`. Traffic to the address `https://demo-aks-ingress.eastus.cloudapp.azure.com/hello-world-two` is routed to the `ingress-demo` service. Update the *hosts*and *host* to the DNS name you created in a previous step.
166
187
167
-
Take note that the traffic to the address `https://demo-aks-ingress.eastus.cloudapp.azure.com/` is routed to the service named `aks-helloworld`. Traffic to the address `https://demo-aks-ingress.eastus.cloudapp.azure.com/hello-world-two` is routed to the `ingress-demo` service.
188
+
Create a file named `hello-world-ingress.yaml` and copy in the following example YAML:
Create the ingress resource with the `kubectl apply` command.
218
+
Create the ingress resource using the `kubectl create -f hello-world-ingress.yaml` command.
198
219
199
-
```console
200
-
kubectl apply -f hello-world-ingress.yaml
220
+
```
221
+
$ kubectl create -f hello-world-ingress.yaml
222
+
223
+
ingress.extensions/hello-world-ingress created
201
224
```
202
225
203
226
## Test the ingress configuration
204
227
205
-
Browse to the FQDN of your Kubernetes ingress controller, you should see the hello world application.
228
+
Open a web browser to the FQDN of your Kubernetes ingress controller, such as *https://demo-aks-ingress.eastus.cloudapp.azure.com*.
206
229
207
-
230
+
As these examples use `letsencrypt-staging`, the issued SSL certificate is not trusted by the browser. Accept the warning prompt to continue to your application. The certificate information shows this *Fake LE Intermediate X1* certificate is issued by Let's Encrypt. This fake certificate indicates `cert-manager` processed the request correctly and received a certificate from the provider:
208
231
209
-
Now browse to the FQDN of the ingress controller with the `/hello-world-two` path, you should see the hello world application with the custom title.
234
+
When you change Let's Encrypt to use `prod` rather than `staging`, a trusted certificate issued by Let's Encrypt is used, as shown in the following example:
Also notice that the connection is encrypted and that a certificate issued by Let's Encrypt is used.
240
+
241
+
242
+
Now add the */hello-world-two* path to the FQDN, such as *https://demo-aks-ingress.eastus.cloudapp.azure.com/hello-world-two*. The second demo application with the custom title is shown:
0 commit comments