将 LetsEncrypt.org 的证书用在 AKS 群集的应用程序网关上Use certificates with LetsEncrypt.org on Application Gateway for AKS clusters

此部分配置 AKS,以便利用 LetsEncrypt.org 并自动获取域的 TLS/SSL 证书。This section configures your AKS to leverage LetsEncrypt.org and automatically obtain a TLS/SSL certificate for your domain. 该证书将安装在应用程序网关上,后者会针对 AKS 群集执行 SSL/TLS 终止操作。The certificate will be installed on Application Gateway, which will perform SSL/TLS termination for your AKS cluster. 此处介绍的设置使用 cert-manager Kubernetes 加载项,该加载项可自动创建并管理证书。The setup described here uses the cert-manager Kubernetes add-on, which automates the creation and management of certificates.

请按以下步骤在现有的 AKS 群集上安装 cert-managerFollow the steps below to install cert-manager on your existing AKS cluster.

  1. Helm ChartHelm Chart

    请运行以下脚本来安装 cert-manager Helm Chart。Run the following script to install the cert-manager helm chart. 这会:This will:

    • 在 AKS 上创建新的 cert-manager 命名空间create a new cert-manager namespace on your AKS
    • 创建以下 CRD:证书、质询、ClusterIssuer、颁发者、顺序create the following CRDs: Certificate, Challenge, ClusterIssuer, Issuer, Order
    • 安装 cert-manager Chart(来自 docs.cert-manager.ioinstall cert-manager chart (from docs.cert-manager.io)
    #!/bin/bash
    
    # Install the CustomResourceDefinition resources separately
    kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.8/deploy/manifests/00-crds.yaml
    
    # Create the namespace for cert-manager
    kubectl create namespace cert-manager
    
    # Label the cert-manager namespace to disable resource validation
    kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true
    
    # Add the Jetstack Helm repository
    helm repo add jetstack https://charts.jetstack.io
    
    # Update your local Helm chart repository cache
    helm repo update
    
    # Install the cert-manager Helm chart
    helm install \
      --name cert-manager \
      --namespace cert-manager \
      --version v0.8.0 \
      jetstack/cert-manager
    
  2. ClusterIssuer 资源ClusterIssuer Resource

    请创建 ClusterIssuer 资源。Create a ClusterIssuer resource. 它是 cert-manager 所需的,用于表示 Lets Encrypt 证书颁发机构(将从其中获取签名的证书)。It is required by cert-manager to represent the Lets Encrypt certificate authority where the signed certificates will be obtained.

    cert-manager 会使用不带命名空间的 ClusterIssuer 资源颁发可以通过多个命名空间使用的证书。By using the non-namespaced ClusterIssuer resource, cert-manager will issue certificates that can be consumed from multiple namespaces. Let’s Encrypt 使用 ACME 协议来验证你是否控制给定的域名,以及向你颁发证书。Let’s Encrypt uses the ACME protocol to verify that you control a given domain name and to issue you a certificate. 此处提供有关如何配置 ClusterIssuer 属性的更多详细信息。More details on configuring ClusterIssuer properties here. ClusterIssuer 会指示 cert-manager 使用 Lets Encrypt 过渡环境来颁发证书,该过渡环境用于测试(不存在于浏览器/客户端信任存储中的根证书)。ClusterIssuer will instruct cert-manager to issue certificates using the Lets Encrypt staging environment used for testing (the root certificate not present in browser/client trust stores).

    在下面的 YAML 中,默认的质询类型为 http01The default challenge type in the YAML below is http01. 其他质询记录在 letsencrypt.org - 验证方式Other challenges are documented on letsencrypt.org - Challenge Types

    重要

    在下面的 YAML 中更新 <YOUR.EMAIL@ADDRESS>Update <YOUR.EMAIL@ADDRESS> in the YAML below

    #!/bin/bash
    kubectl apply -f - <<EOF
    apiVersion: certmanager.k8s.io/v1alpha1
    kind: ClusterIssuer
    metadata:
    name: letsencrypt-staging
    spec:
    acme:
        # You must replace this email address with your own.
        # Let's Encrypt will use this to contact you about expiring
        # certificates, and issues related to your account.
        email: <YOUR.EMAIL@ADDRESS>
        # ACME server URL for Let’s Encrypt’s staging environment.
        # The staging environment will not issue trusted certificates but is
        # used to ensure that the verification process is working properly
        # before moving to production
        server: https://acme-staging-v02.api.letsencrypt.org/directory
        privateKeySecretRef:
        # Secret resource used to store the account's private key.
        name: example-issuer-account-key
        # Enable the HTTP-01 challenge provider
        # you prove ownership of a domain by ensuring that a particular
        # file is present at the domain
        http01: {}
    EOF
    
  3. 部署应用Deploy App

    请创建一项入口资源,以便使用应用程序网关和 Lets Encrypt 证书来公开 guestbook 应用程序。Create an Ingress resource to Expose the guestbook application using the Application Gateway with the Lets Encrypt Certificate.

    确保应用程序网关有一个带 DNS 名称的公共前端 IP 配置(可以使用默认的 azure.com 域,也可以先预配 Azure DNS Zone 服务,然后分配你自己的自定义域)。Ensure you Application Gateway has a public Frontend IP configuration with a DNS name (either using the default azure.com domain, or provision a Azure DNS Zone service, and assign your own custom domain). 注意注释 certmanager.k8s.io/cluster-issuer: letsencrypt-staging,它告知 cert-manager 处理标记的入口资源。Note the annotation certmanager.k8s.io/cluster-issuer: letsencrypt-staging, which tells cert-manager to process the tagged Ingress resource.

    重要

    请将下面的 YAML 中的 <PLACEHOLDERS.COM> 更新为你自己的域(或应用程序网关的域,例如“kh-aks-ingress.chinanorth.chinacloudapp.cn”)Update <PLACEHOLDERS.COM> in the YAML below with your own domain (or the Application Gateway one, for example 'kh-aks-ingress.chinanorth.chinacloudapp.cn')

    kubectl apply -f - <<EOF
    apiVersion: extensions/v1beta1
    kind: Ingress
    metadata:
    name: guestbook-letsencrypt-staging
    annotations:
        kubernetes.io/ingress.class: azure/application-gateway
        certmanager.k8s.io/cluster-issuer: letsencrypt-staging
    spec:
    tls:
    - hosts:
        - <PLACEHOLDERS.COM>
        secretName: guestbook-secret-name
    rules:
    - host: <PLACEHOLDERS.COM>
        http:
        paths:
        - backend:
            serviceName: frontend
            servicePort: 80
    EOF
    

    几秒钟后,可以使用自动颁发的暂存 Lets Encrypt 证书通过应用程序网关 HTTPS URL 访问 guestbook 服务。After a few seconds, you can access the guestbook service through the Application Gateway HTTPS url using the automatically issued staging Lets Encrypt certificate. 浏览器可能会警告你:证书颁发机构无效。Your browser may warn you of an invalid cert authority. 暂存证书由 CN=Fake LE Intermediate X1 颁发。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.

  4. 生产证书Production Certificate

    成功设置暂存证书以后,即可切换到生产 ACME 服务器:Once your staging certificate is setup successfully you can switch to a production ACME server:

    1. 将入口资源上的暂存注释替换为:certmanager.k8s.io/cluster-issuer: letsencrypt-prodReplace the staging annotation on your Ingress resource with: certmanager.k8s.io/cluster-issuer: letsencrypt-prod
    2. 将上面的 ClusterIssuer YAML 中的 ACME 服务器替换为 https://acme-v02.api.letsencrypt.org/directory,以便删除在上一步创建的现有暂存 ClusterIssuer 并创建一个新的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
  5. 证书过期和续订Certificate Expiration and Renewal

    Lets Encrypt 证书过期之前,cert-manager 会自动更新 Kubernetes 机密存储中的证书。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.