Skip to content

Commit 1a556ce

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request kubernetes-sigs#3201 from zioproto/azure-tutorials
Improve Azure tutorials
2 parents 8c2d545 + 617a32a commit 1a556ce

File tree

2 files changed

+149
-70
lines changed

2 files changed

+149
-70
lines changed

‎docs/tutorials/azure-private-dns.md‎

Lines changed: 105 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -3,61 +3,20 @@
33
This tutorial describes how to set up ExternalDNS for managing records in Azure Private DNS.
44

55
It comprises of the following steps:
6-
1) Install NGINX Ingress Controller
7-
2) Provision Azure Private DNS
8-
3) Configure service principal for managing the zone
9-
4) Deploy ExternalDNS
10-
11-
Everything will be deployed on Kubernetes.
6+
1) Provision Azure Private DNS
7+
2) Configure service principal for managing the zone
8+
3) Deploy ExternalDNS
9+
4) Expose an NGINX service with a LoadBalancer and annotate it with the desired DNS name
10+
5) Install NGINX Ingress Controller (Optional)
11+
6) Expose an nginx service with an ingress (Optional)
12+
7) Verify the DNS records
13+
14+
Everything will be deployed on Kubernetes.
1215
Therefore, please see the subsequent prerequisites.
1316

1417
## Prerequisites
1518
- Azure Kubernetes Service is deployed and ready
16-
- [Azure CLI 2.0](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and `kubectl` installed on the box to execute the subsequent steps
17-
18-
## Install NGINX Ingress Controller
19-
20-
Helm is used to deploy the ingress controller.
21-
22-
We employ the popular chart [ingress-nginx](https://github.com/kubernetes/ingress-nginx/tree/main/charts/ingress-nginx).
23-
24-
```
25-
$ helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
26-
$ helm repo update
27-
$ helm install [RELEASE_NAME] ingress-nginx/ingress-nginx
28-
--set controller.publishService.enabled=true
29-
```
30-
31-
The parameter `controller.publishService.enabled` needs to be set to `true.`
32-
33-
It will make the ingress controller update the endpoint records of ingress-resources to contain the external-ip of the loadbalancer serving the ingress-controller.
34-
This is crucial as ExternalDNS reads those endpoints records when creating DNS-Records from ingress-resources.
35-
In the subsequent parameter we will make use of this. If you don't want to work with ingress-resources in your later use, you can leave the parameter out.
36-
37-
Verify the correct propagation of the loadbalancer's ip by listing the ingresses.
38-
39-
```
40-
$ kubectl get ingress
41-
```
42-
43-
The address column should contain the ip for each ingress. ExternalDNS will pick up exactly this piece of information.
44-
45-
```
46-
NAME HOSTS ADDRESS PORTS AGE
47-
nginx1 sample1.aks.com 52.167.195.110 80 6d22h
48-
nginx2 sample2.aks.com 52.167.195.110 80 6d21h
49-
```
50-
51-
If you do not want to deploy the ingress controller with Helm, ensure to pass the following cmdline-flags to it through the mechanism of your choice:
52-
53-
```
54-
flags:
55-
--publish-service=<namespace of ingress-controller >/<svcname of ingress-controller>
56-
--update-status=true (default-value)
57-
58-
example:
59-
./nginx-ingress-controller --publish-service=default/nginx-ingress-controller
60-
```
19+
- [Azure CLI 2.0](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and `kubectl` installed on the box to execute the subsequent steps
6120

6221
## Provision Azure Private DNS
6322

@@ -72,7 +31,7 @@ $ az group create -n externaldns -l westeurope
7231

7332
Substitute a more suitable location for the resource group if desired.
7433

75-
As a prerequisite for Azure Private DNS to resolve records is to define links with VNETs.
34+
As a prerequisite for Azure Private DNS to resolve records is to define links with VNETs.
7635
Thus, first create a VNET.
7736

7837
```
@@ -101,11 +60,11 @@ $ az network private-dns link vnet create -g externaldns -n mylink \
10160
```
10261

10362
## Configure service principal for managing the zone
104-
ExternalDNS needs permissions to make changes in Azure Private DNS.
63+
ExternalDNS needs permissions to make changes in Azure Private DNS.
10564
These permissions are roles assigned to the service principal used by ExternalDNS.
10665

10766
A service principal with a minimum access level of `Private DNS Zone Contributor` to the Private DNS zone(s) and `Reader` to the resource group containing the Azure Private DNS zone(s) is necessary.
108-
More powerful role-assignments like `Owner` or assignments on subscription-level work too.
67+
More powerful role-assignments like `Owner` or assignments on subscription-level work too.
10968

11069
Start off by **creating the service principal** without role-assignments.
11170
```
@@ -119,8 +78,7 @@ $ az ad sp create-for-rbac --skip-assignment -n http://externaldns-sp
11978
```
12079
> Note: Alternatively, you can issue `az account show --query "tenantId"` to retrieve the id of your AAD Tenant too.
12180
122-
123-
Next, assign the roles to the service principal.
81+
Next, assign the roles to the service principal.
12482
But first **retrieve the ID's** of the objects to assign roles on.
12583

12684
```
@@ -134,17 +92,17 @@ $ az network private-dns zone show --name example.com -g externaldns --query id
13492
Now, **create role assignments**.
13593
```
13694
# 1. as a reader to the resource group
137-
$ az role assignment create --role "Reader" --assignee <appId GUID> --scope <resource group resource id>
95+
$ az role assignment create --role "Reader" --assignee <appId GUID> --scope <resource group resource id>
13896
13997
# 2. as a contributor to DNS Zone itself
140-
$ az role assignment create --role "Private DNS Zone Contributor" --assignee <appId GUID> --scope <dns zone resource id>
98+
$ az role assignment create --role "Private DNS Zone Contributor" --assignee <appId GUID> --scope <dns zone resource id>
14199
```
142100

143101
## Deploy ExternalDNS
144-
Configure `kubectl` to be able to communicate and authenticate with your cluster.
102+
Configure `kubectl` to be able to communicate and authenticate with your cluster.
145103
This is per default done through the file `~/.kube/config`.
146104

147-
For general background information on this see [kubernetes-docs](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/).
105+
For general background information on this see [kubernetes-docs](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/).
148106
Azure-CLI features functionality for automatically maintaining this file for AKS-Clusters. See [Azure-Docs](https://docs.microsoft.com/de-de/cli/azure/aks?view=azure-cli-latest#az-aks-get-credentials).
149107

150108
Follow the steps for [azure-dns provider](./azure.md#creating-configuration-file) to create a configuration file.
@@ -338,11 +296,12 @@ Create the deployment for ExternalDNS:
338296
$ kubectl create -f externaldns.yaml
339297
```
340298

341-
## Deploying sample service
299+
## Create an nginx deployment
342300

343-
Create a service file called 'nginx.yaml' with the following contents:
301+
This step creates a demo workload in your cluster. Apply the following manifest to create a deployment that we are going to expose later in this tutorial in multiple ways:
344302

345303
```yaml
304+
---
346305
apiVersion: apps/v1
347306
kind: Deployment
348307
metadata:
@@ -357,15 +316,92 @@ spec:
357316
app: nginx
358317
spec:
359318
containers:
360-
- image: nginx
361-
name: nginx
362-
ports:
363-
- containerPort: 80
319+
- image: nginx
320+
name: nginx
321+
ports:
322+
- containerPort: 80
323+
```
324+
325+
## Expose the nginx deployment with a load balancer
326+
327+
Apply the following manifest to create a service of type `LoadBalancer`. This will create a public load balancer in Azure that will forward traffic to the nginx pods.
328+
329+
```yaml
364330
---
365331
apiVersion: v1
366332
kind: Service
333+
annotations:
334+
service.beta.kubernetes.io/azure-load-balancer-internal: "true"
335+
external-dns.alpha.kubernetes.io/hostname: server.example.com
336+
external-dns.alpha.kubernetes.io/internal-hostname: server-clusterip.example.com
367337
metadata:
368338
name: nginx-svc
339+
spec:
340+
ports:
341+
- port: 80
342+
protocol: TCP
343+
targetPort: 80
344+
selector:
345+
app: nginx
346+
type: LoadBalancer
347+
```
348+
349+
In the service we used multiple annptations. The annotation `service.beta.kubernetes.io/azure-load-balancer-internal` is used to create an internal load balancer. The annotation `external-dns.alpha.kubernetes.io/hostname` is used to create a DNS record for the load balancer that will point to the internal IP address in the VNET allocated by the internal load balancer. The annotation `external-dns.alpha.kubernetes.io/internal-hostname` is used to create a private DNS record for the load balancer that will point to the cluster IP.
350+
351+
## Install NGINX Ingress Controller (Optional)
352+
353+
Helm is used to deploy the ingress controller.
354+
355+
We employ the popular chart [ingress-nginx](https://github.com/kubernetes/ingress-nginx/tree/main/charts/ingress-nginx).
356+
357+
```
358+
$ helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
359+
$ helm repo update
360+
$ helm install [RELEASE_NAME] ingress-nginx/ingress-nginx
361+
--set controller.publishService.enabled=true
362+
```
363+
364+
The parameter `controller.publishService.enabled` needs to be set to `true.`
365+
366+
It will make the ingress controller update the endpoint records of ingress-resources to contain the external-ip of the loadbalancer serving the ingress-controller.
367+
This is crucial as ExternalDNS reads those endpoints records when creating DNS-Records from ingress-resources.
368+
In the subsequent parameter we will make use of this. If you don't want to work with ingress-resources in your later use, you can leave the parameter out.
369+
370+
Verify the correct propagation of the loadbalancer's ip by listing the ingresses.
371+
372+
```
373+
$ kubectl get ingress
374+
```
375+
376+
The address column should contain the ip for each ingress. ExternalDNS will pick up exactly this piece of information.
377+
378+
```
379+
NAME HOSTS ADDRESS PORTS AGE
380+
nginx1 sample1.aks.com 52.167.195.110 80 6d22h
381+
nginx2 sample2.aks.com 52.167.195.110 80 6d21h
382+
```
383+
384+
If you do not want to deploy the ingress controller with Helm, ensure to pass the following cmdline-flags to it through the mechanism of your choice:
385+
386+
```
387+
flags:
388+
--publish-service=<namespace of ingress-controller >/<svcname of ingress-controller>
389+
--update-status=true (default-value)
390+
391+
example:
392+
./nginx-ingress-controller --publish-service=default/nginx-ingress-controller
393+
```
394+
395+
## Expose the nginx deployment with the ingress (Optional)
396+
397+
Apply the following manifest to create an ingress resource that will expose the nginx deployment. The ingress resource backend points to a `ClusterIP` service that is needed to select the pods that will receive the traffic.
398+
399+
```yaml
400+
---
401+
apiVersion: v1
402+
kind: Service
403+
metadata:
404+
name: nginx-svc-clusterip
369405
spec:
370406
ports:
371407
- port: 80
@@ -374,7 +410,7 @@ spec:
374410
selector:
375411
app: nginx
376412
type: ClusterIP
377-
413+
378414
---
379415
apiVersion: networking.k8s.io/v1
380416
kind: Ingress
@@ -389,7 +425,7 @@ spec:
389425
paths:
390426
- backend:
391427
service:
392-
name: nginx-svc
428+
name: nginx-svc-clusterip
393429
port:
394430
number: 80
395431
pathType: Prefix
@@ -403,7 +439,7 @@ Create the deployment, service and ingress object:
403439
$ kubectl create -f nginx.yaml
404440
```
405441

406-
Since your external IP would have already been assigned to the nginx-ingress service, the DNS records pointing to the IP of the nginx-ingress service should be created within a minute.
442+
Since your external IP would have already been assigned to the nginx-ingress service, the DNS records pointing to the IP of the nginx-ingress service should be created within a minute.
407443

408444
## Verify created records
409445

‎docs/tutorials/azure.md‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -518,7 +518,7 @@ Create the deployment for ExternalDNS:
518518
$ kubectl create --namespace "default" --filename externaldns.yaml
519519
```
520520

521-
## Deploying an Nginx Service
521+
## Ingress Option: Expose an nginx service with an ingress
522522

523523
Create a file called `nginx.yaml` with the following contents:
524524

@@ -586,6 +586,49 @@ $ kubectl create --namespace "default" --filename nginx.yaml
586586

587587
Since your external IP would have already been assigned to the nginx-ingress service, the DNS records pointing to the IP of the nginx-ingress service should be created within a minute.
588588

589+
## Azure Load Balancer option: Expose an nginx service with a load balancer
590+
591+
Create a file called `nginx.yaml` with the following contents:
592+
593+
```yaml
594+
---
595+
apiVersion: apps/v1
596+
kind: Deployment
597+
metadata:
598+
name: nginx
599+
spec:
600+
selector:
601+
matchLabels:
602+
app: nginx
603+
template:
604+
metadata:
605+
labels:
606+
app: nginx
607+
spec:
608+
containers:
609+
- image: nginx
610+
name: nginx
611+
ports:
612+
- containerPort: 80
613+
---
614+
apiVersion: v1
615+
kind: Service
616+
annotations:
617+
external-dns.alpha.kubernetes.io/hostname: server.example.com
618+
metadata:
619+
name: nginx-svc
620+
spec:
621+
ports:
622+
- port: 80
623+
protocol: TCP
624+
targetPort: 80
625+
selector:
626+
app: nginx
627+
type: LoadBalancer
628+
```
629+
630+
The annotation `external-dns.alpha.kubernetes.io/hostname` is used to specify the DNS name that should be created for the service. The annotation value is a comma separated list of host names.
631+
589632
## Verifying Azure DNS records
590633

591634
Run the following command to view the A records for your Azure DNS zone:

0 commit comments

Comments
 (0)