Skip to content

Latest commit

 

History

History
479 lines (286 loc) · 9.47 KB

README.md

File metadata and controls

479 lines (286 loc) · 9.47 KB
Raw

AKS Ingress with Contour, Cert-Manager and Let's Encrypt

This lab is designed to help you securely expose your Kubernetes services over HTTPS and deploy multiple applications using path-based and host-based routing. This can be useful if you have multiple applications running on your cluster and want to ensure that each one is accessible via its own unique and HTTPS secured URL. This lab uses:

  • AKS Cluster: Azure Kubernetes Service to deploy and manage cloud native applications in Azure
  • Contour: An ingress controller for Kubernetes that works by deploying the Envoy proxy as a reverse proxy and load balancer
  • Let's Encrypt: A Certificate Authority (CA) to get a certificate for your domain
  • cert-manager: A Certificate Controller to provision and manage TLS certifications from Let's Encrypt or any other issuer

Goals of the Lab

  • Enable Contour and Let's Encrypt for secure ingress to an AKS cluster
  • Deploy an application with path-based routing
  • Deploy a second application with path-based routing
  • Deploy an application with host-based routing
  • Deploy a second application with host-based routing

Prerequisites

  • A public GitHub account
  • An Azure subscription
  • A domain name and DNS server
    • Instructions for using Azure DNS are included

Create a Codespace

  • Fork this repo
  • Create a Codespace from the forked repo (not this repo)
    • Use the Codespace terminal to work through the lab

Getting Started

  • Set AKS Name

    # edit this value (optional)
export LAB_AKS_NAME=lab-aks

  • Set Location and Resource Group names

    export LAB_LOCATION=eastus
export LAB_AKS_RG=${LAB_AKS_NAME}-rg
export LAB_AKS_NODE_RG=${LAB_AKS_NAME}-node-rg

  • Set DNS Information

    # edit this value
export LAB_DNS_ZONE=aks-demo.com

# if you have an Azure DNS zone, edit this value
export LAB_DNS_RG=tld

    export LAB_DNS_HOST=lab
export LAB_FQDN=$LAB_DNS_HOST.$LAB_DNS_ZONE

  • Check environment variables

    env | grep ^LAB_

  • Update the ingress manifest files

    # replace the FQDN in the manifest files
find deploy -type f -exec sed -i "s|lab.aks-demo.com|$LAB_FQDN|g" {} \;

  • View ingress manifest changes

    git diff

Deploy a basic AKS Cluster

  • Login to Azure using a device code

    az login --use-device-code

  • Create a Resource Group

    az group create -n $LAB_AKS_RG -l $LAB_LOCATION

  • Create an AKS Cluster

    • This command will create SSH key files in $HOME/.ssh
    • Copy your id_rsa and id_rsa.pub to $HOME/.ssh if you want to use existing SSH keys
    az aks create \
-g $LAB_AKS_RG \
-n $LAB_AKS_NAME \
--node-resource-group $LAB_AKS_NODE_RG \
--generate-ssh-keys \
--enable-managed-identity \
--node-count 1

  • Login to the AKS Cluster

    az aks get-credentials -g $LAB_AKS_RG -n $LAB_AKS_NAME

  • Wait for the pods to start

    • Press ctl-c once all pods are running
    kubectl get pods --all-namespaces --watch

Setup Contour and Cert-Manager

  • Apply the Contour Kustomization

    kubectl apply -k deploy/contour

# wait for pods to start / complete
kubectl get pods -n projectcontour --watch

  • Apply the Cert-Manager Kustomization

    kubectl apply -k deploy/cert-manager

# wait for pods to start
kubectl wait pod --all -n cert-manager --for=condition=ready --timeout 60s

# check via the CLI
kubectl cert-manager check api

  • Edit the lets-encrypt manifest

    • Use a valid email address
    code deploy/lets-encrypt/lets-encrypt.yaml

  • Apply the lets-encrypt Kustomization

    kubectl apply -k deploy/lets-encrypt

# check secrets
kubectl get secrets -n cert-manager

Setup DNS

  • Get the Load Balancer public IP

    export LAB_IP=$(kubectl get svc -n projectcontour envoy -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

# check the env vars
env | grep ^LAB_

  • If using Azure DNS

    • Create a DNS A Record
    az network dns record-set a add-record \
-g "$LAB_DNS_RG" \
-z "$LAB_DNS_ZONE" \
-n "$LAB_DNS_HOST" \
-a "$LAB_IP" \
--ttl 10 -o table

  • Check DNS

    # if this doesn't resolve, the rest of the lab will fail
ping $LAB_DNS_HOST.$LAB_DNS_ZONE

Deploy an application using path-based routing

  • Heartbeat is a simple application that allows you to retrieve a known set of data from a known endpoint

  • Deploy the application kustomization

    kubectl apply -k deploy/heartbeat

# wait for the heartbeat pod to start
kubectl get pods -n heartbeat --watch

  • Check the ingress controllers

    kubectl get ingress -A

  • Check the endpoint

    • Result should be 301

      http http://$LAB_FQDN/heartbeat/17

  • Check the https endpoint

    • You may need to retry due to the acme handshake, this can take up to a minute

    • Result should be 200

      • 0123456789ABCDEF0
      http https://$LAB_FQDN/heartbeat/17

Deploy a second application using path-based routing

  • The ingress uses path-based routing to route to /benchmark/17

  • Deploy the application kustomization

    kubectl apply -k deploy/benchmark

# wait for the benchmark pod to start
kubectl get pods -n benchmark --watch

  • Check the ingress controllers

    kubectl get ingress -A

  • Check the endpoints

    # Result should be 301
http http://$LAB_FQDN/benchmark/17

# Result should be 200
http https://$LAB_FQDN/benchmark/17

Deploy an application using host-based routing

  • Deploy Redis for the apps

    kubectl apply -k deploy/redis

  • If using Azure DNS

    • Create the DNS entry

    • dogs.lab.your.zone

      az network dns record-set a add-record \
-g "$LAB_DNS_RG" \
-z "$LAB_DNS_ZONE" \
-n "dogs.$LAB_DNS_HOST" \
-a "$LAB_IP" \
--ttl 10 -o table

  • Deploy the dogs-cats app

    kubectl apply -k deploy/dogs-cats

# wait for pod to start
kubectl get pods -n dogs-cats --watch

  • Check the ingress controllers

    kubectl get ingress -A

  • Check endpoints

    # should return 301
http http://dogs.$LAB_FQDN/

# should return 200
http https://dogs.$LAB_FQDN/

Deploy a second application using host-based routing

  • If using Azure DNS

    • Create the DNS entry

    • tabs.lab.your.zone

      az network dns record-set a add-record \
-g "$LAB_DNS_RG" \
-z "$LAB_DNS_ZONE" \
-n "tabs.$LAB_DNS_HOST" \
-a "$LAB_IP" \
--ttl 10 -o table

  • Deploy the tabs-spaces app

    kubectl apply -k deploy/tabs-spaces

# wait for pod to start
kubectl get pods -n tabs-spaces --watch

  • Check the ingress controllers

    kubectl get ingress -A

  • Check endpoints

    # should return 301
http http://tabs.$LAB_FQDN/

# should return 200
http https://tabs.$LAB_FQDN/

Cleanup

  • Delete the Kubernetes context

    kubectl config delete-context $LAB_AKS_NAME

  • If using Azure DNS

    • Delete the A record(s)
    az network dns record-set a remove-record \
-g "$LAB_DNS_RG" \
-z "$LAB_DNS_ZONE" \
-n "$LAB_DNS_HOST" \
-a "$LAB_IP" -o table

az network dns record-set a remove-record \
-g "$LAB_DNS_RG" \
-z "$LAB_DNS_ZONE" \
-n "dogs.$LAB_DNS_HOST" \
-a "$LAB_IP" -o table

az network dns record-set a remove-record \
-g "$LAB_DNS_RG" \
-z "$LAB_DNS_ZONE" \
-n "tabs.$LAB_DNS_HOST" \
-a "$LAB_IP" -o table

  • Delete the Resource Group

    az group delete -y --no-wait -g $LAB_AKS_RG

How to get help

For help and questions about using this lab, please use the GitHub Discussion tab.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.