Kubernetes環境における証明書管理の自動化

NGINX | 2022年10月05日

有効なSSL/TLS証明書は、現代のアプリケーション環境に不可欠です。しかし、アプリケーションのデプロイ時には、証明書（cert）の更新管理が後回しになりがちです。証明書の有効期間は限られており、DigiCertの証明書では約13か月、Let’s Encryptの証明書では90日です。セキュアなアクセスを維持するには、有効期限が切れる前に証明書を更新または再発行する必要があります。多くの運用チームは相当な業務負荷を抱えているため、証明書の更新が見落とされることがあります。その結果、有効期限が迫ってから、あるいは最悪の場合は期限切れになってから、慌てて対応することになります。

このような状況は避けられます。適切に計画して準備することで、証明書管理を自動化し、効率化できます。ここでは、3つのテクノロジーを使用したKubernetes向けのソリューションを紹介します。

このブログでは、エンドポイントごとに固有の証明書を提供し、それらを自動的に更新することで、証明書管理を簡素化する方法を紹介します。

Kubernetes環境における証明書

技術的な詳細に入る前に、いくつかの用語を定義しておく必要があります。「TLS証明書」とは、IngressコントローラーでHTTPS接続を有効にするために必要な次の2つのコンポーネントを指します。

証明書
秘密鍵

証明書と秘密鍵はいずれもLet’s Encryptによって発行されます。TLS証明書の仕組みについて詳しくは、DigiCertの記事「TLS/SSL証明書の仕組み」をご覧ください。

Kubernetesでは、これら2つのコンポーネントはSecretとして保存されます。NGINX Ingress Controllerやcert-managerなどのKubernetesワークロードは、これらのSecretに対して書き込みと読み取りを行えます。また、Kubernetes環境へのアクセス権を持つユーザーも、これらのSecretを管理できます。

cert-managerの概要

The cert-managerプロジェクトは、KubernetesおよびOpenShiftで動作する証明書コントローラーです。Kubernetesにデプロイすると、Ingressコントローラーに必要な証明書を自動的に発行し、証明書が有効かつ最新の状態に保たれるようにします。また、証明書の有効期限を追跡し、設定された間隔で更新を試みます。多数のパブリックおよびプライベート発行者に対応していますが、ここではLet’s Encryptとの連携について説明します。

2種類のチャレンジタイプ

Let’s Encryptを使用すると、証明書の管理はすべて自動的に行われます。非常に便利である一方、課題もあります。対象の完全修飾ドメイン名（FQDN）を所有していることを、サービスはどのように確認するのでしょうか。

この問題は、特定のドメインのDNSレコードにアクセスできる人だけが応答可能な検証リクエストへの回答を求める「チャレンジ」によって解決します。チャレンジには、次の2つの形式があります。

HTTP-01：証明書を発行するFQDNのDNSレコードがあれば、このチャレンジに応答できます。たとえば、サーバーのIPアドレスがwww.xxx.yyy.zzzで、FQDNがcert.example.comの場合、チャレンジメカニズムはwww.xxx.yyy.zzzのサーバー上でトークンを公開し、Let’s Encryptサーバーはcert.example.com経由でそのトークンへのアクセスを試みます。アクセスに成功するとチャレンジに合格し、証明書が発行されます。HTTP-01ではDNSプロバイダーに直接アクセスする必要がないため、証明書を生成する最も簡単な方法です。このチャレンジは常にポート80（HTTP）で実行されます。HTTP-01チャレンジを使用する場合、cert-managerはIngressコントローラーを使用してチャレンジトークンを提供します。

DNS-01：このチャレンジでは、トークンを含むDNS TXTレコードを作成し、発行者がそのトークンを検証します。トークンが認識されると、そのドメインの所有権が証明され、ドメインのレコードに対して証明書を発行できるようになります。HTTP-01チャレンジとは異なり、DNS-01チャレンジでは、FQDNがサーバーのIPアドレスに名前解決される必要はなく、FQDN自体が存在している必要もありません。また、ポート80がブロックされている場合でもDNS-01を使用できます。この利便性と引き換えに、APIトークンを使用してcert-managerインストール環境からDNSインフラストラクチャにアクセスできるようにする必要があります。

Ingress Controller

An Ingress controllerは、クラスタ外部からのトラフィックを取り込み、内部のPod（1つ以上のコンテナで構成されるグループ）に負荷分散し、送信トラフィックを管理するKubernetes専用サービスです。また、Ingress controllerはKubernetes APIを通じて制御され、Podの追加、削除、障害発生に応じて負荷分散設定を監視し、更新します。

Ingressコントローラーの詳細については、以下のブログをご覧ください。

以下の例では、F5 NGINXが開発および保守するNGINX Ingress Controllerを使用します。

証明書管理の例

これらの例では、テストに使用できる正常に動作するKubernetes環境があり、その環境で外部IPアドレス（Kubernetes LoadBalancerオブジェクト）を割り当てられることを前提としています。また、HTTP-01チャレンジを使用する場合はポート80とポート443の両方で、DNS-01チャレンジを使用する場合はポート443のみでトラフィックを受信できることも前提としています。これらの例ではMac OS Xを使用していますが、LinuxまたはWSLでも利用できます。

また、Aレコードを変更できるDNSプロバイダーとFQDNも必要です。HTTP-01チャレンジを使用する場合は、Aレコードを追加できれば十分です（または、代わりに追加してもらうこともできます）。DNS-01チャレンジを使用する場合は、サポート対象のDNSプロバイダーまたはサポート対象のWebhookプロバイダーへのAPIアクセスが必要です。

NGINX Ingress Controllerのデプロイ

最も簡単な方法は、Helmを使用してデプロイすることです。このデプロイでは、Kubernetes IngressとNGINX Virtual Server CRDの両方を使用できます。

NGINXリポジトリを追加します。

$ helm repo add nginx-stable https://helm.nginx.com/stable  "nginx-stable" has been added to your repositories

リポジトリを更新します。

$ helm repo update  Hang tight while we grab the latest from your chart repositories...
  ...Successfully got an update from the "nginx-stable" chart repository
  Update Complete. ⎈Happy Helming!⎈

Ingress Controllerをデプロイします。

$ helm install nginx-kic nginx-stable/nginx-ingress \  --namespace nginx-ingress  --set controller.enableCustomResources=true \ 
  --create-namespace  --set controller.enableCertManager=true 
  NAME: nginx-kic
  LAST DEPLOYED: Thu Sep  1 15:58:15 2022
  NAMESPACE: nginx-ingress
  STATUS: deployed
  REVISION: 1
  TEST SUITE: None
  NOTES:
  The NGINX Ingress Controller has been installed.

デプロイを確認し、Ingress controllerのegressのIPアドレスを取得します。有効なIPアドレスがない場合は続行できません。

$ kubectl get deployments --namespace nginx-ingress  NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
  nginx-kic-nginx-ingress   1/1     1            1           23s
  $ kubectl get services --namespace nginx-ingress
  NAME                      TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)                      AGE
  nginx-kic-nginx-ingress   LoadBalancer   10.128.60.190   www.xxx.yyy.zzz   80:31526/TCP,443:32058/TCP   30s

DNS Aレコードを追加

ここでの手順は、ご利用のDNSプロバイダーによって異なります。このDNS名はLet’s Encryptサーバーから名前解決できる必要があるため、利用可能になるまでレコードの伝播を待つ必要がある場合があります。詳しくは、SiteGroundの記事「DNS伝播とは何か、なぜ時間がかかるのか？」をご覧ください。

選択したFQDNを名前解決できるようになったら、次の手順に進む準備は完了です。

$ host cert.example.com  cert.example.com has address www.xxx.yyy.zzz

cert-managerのデプロイ

次に、最新バージョンのcert-managerをデプロイします。今回も、デプロイにはHelmを使用します。

Helmリポジトリを追加します。

$ helm repo add jetstack https://charts.jetstack.io  "jetstack" has been added to your repositories

リポジトリを更新します。

$ helm repo update  Hang tight while we grab the latest from your chart repositories...
  ...Successfully got an update from the "nginx-stable" chart repository
  ...Successfully got an update from the "jetstack" chart repository
  Update Complete. ⎈Happy Helming!⎈

cert-managerをデプロイします。

$ helm install cert-manager jetstack/cert-manager \  --namespace cert-manager --create-namespace \
  --version v1.9.1  --set installCRDs=true 
  NAME: cert-manager
  LAST DEPLOYED: Thu Sep  1 16:01:52 2022 
  NAMESPACE: cert-manager
  STATUS: deployed
  REVISION: 1 
  TEST SUITE: None
  NOTES:
  cert-manager v1.9.1 has been deployed successfully!
  In order to begin issuing certificates, you will need to set up a ClusterIssuer
  or Issuer resource (for example, by creating a 'letsencrypt-staging' issuer).
  More information on the different types of issuers and how to configure them
  can be found in our documentation:
  https://cert-manager.io/docs/configuration/ For information on how to configure cert-manager to automatically provision
  Certificates for Ingress resources, take a look at the `ingress-shim`
  documentation:
  https://cert-manager.io/docs/usage/ingress/

デプロイを検証します。

$ kubectl get deployments --namespace cert-manager  NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
  cert-manager              1/1     1            1           4m30s
  cert-manager-cainjector   1/1     1            1           4m30s
  cert-manager-webhook      1/1     1            1           4m30s

NGINX Cafeのサンプルをデプロイ

バックエンドのDeploymentとServiceには、NGINX Cafeのサンプルを使用します。これは、NGINXが提供するドキュメントで一般的に使用されているサンプルです。ここではIngressをデプロイしません。

NGINX IngressのGitHubプロジェクトをクローンします。

$ git clone https://github.com/nginxinc/kubernetes-ingress.git  Cloning into 'kubernetes-ingress'...
  remote: Enumerating objects: 44979, done.
  remote: Counting objects: 100% (172/172), done.
  remote: Compressing objects: 100% (108/108), done.
  remote: Total 44979 (delta 87), reused 120 (delta 63), pack-reused 44807
  Receiving objects: 100% (44979/44979), 60.27 MiB | 27.33 MiB/s, done.
  Resolving deltas: 100% (26508/26508), done.

examplesディレクトリに移動します。このディレクトリには、Ingressコントローラーのさまざまな構成を示す複数の例が含まれています。ここでは、complete-exampleディレクトリにある例を使用します。

$ cd ./kubernetes-ingress/examples/ingress-resources/complete-example

NGINX Cafeのサンプルをデプロイします。

$ kubectl apply -f ./cafe.yaml
  deployment.apps/coffee created
  service/coffee-svc created
  deployment.apps/tea created
  service/tea-svc created

Validate the deployment and Services using the kubectl getコマンドを使用して、デプロイメントとServiceを検証します。PodがREADYと表示され、Serviceがrunningと表示されていることを確認してください。以下に、想定される出力例を示します。kubernetes Serviceは、NGINX Cafeの例と同じ名前空間（default）で実行されているシステムServiceです。

$ kubectl get deployments,services  --namespace default  NAME                     READY   UP-TO-DATE   AVAILABLE   AGE
  deployment.apps/coffee   2/2     2            2           69s
  deployment.apps/tea      3/3     3            3           68s
NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)   AGE
  service/coffee-svc   ClusterIP   10.128.154.225   <none>        80/TCP    68s
  service/kubernetes   ClusterIP   10.128.0.1       <none>        443/TCP   29m
	service/tea-svc      ClusterIP   10.128.96.145    <none>        80/TCP    68s

ClusterIssuerのデプロイ

cert-managerでは、ClusterIssuerを使用して証明書を発行できます。これはクラスタースコープのオブジェクトであり、どの名前空間からでも参照でき、定義された証明書発行機関を使用する任意の証明書リクエストで利用できます。この例では、Let’s Encrypt証明書に対するすべての証明書リクエストを、このClusterIssuerで処理できます。

選択したチャレンジタイプに対応するClusterIssuerをデプロイします。この記事では扱いませんが、ClusterIssuerで複数のリゾルバー（セレクターフィールドに基づいて選択）を指定できる高度な設定オプションがあります。

ACMEチャレンジの基礎

Automated Certificate Management Environment（ACME）プロトコルは、ドメイン名の所有権を確認し、Let’s Encrypt証明書を発行できるかどうかを判断するために使用されます。このチャレンジでは、次のパラメーターを渡す必要があります。

metadata.name：ClusterIssuer名です。Kubernetes環境内で一意である必要があります。この名前は、後ほど証明書を発行する例で使用します。
spec.acme.email：証明書を生成するためにLet’s Encryptへ登録するメールアドレスです。ご自身のメールアドレスを指定してください。
spec.acme.privateKeySecretRef：秘密鍵の保存に使用するKubernetes Secretの名前です。
spec.acme.solvers：これは変更せず、そのままにしてください。使用するチャレンジの種類（ACMEでは「solver」と呼ばれます）（HTTP-01またはDNS-01）と、適用先のIngressクラスを指定します。この場合はnginxです。

HTTP-01の使用

この例では、HTTP-01チャレンジを使用してドメインの所有権を証明し、証明書を取得するようにClusterIssuerを設定する方法を示します。

チャレンジにHTTP-01を使用するClusterIssuerを作成します。

$ cat << EOF | kubectl apply -f   apiVersion: cert-manager.io/v1
  kind: ClusterIssuer
  metadata:
    name: prod-issuer
  spec:
    acme:
      email: example@example.com
      server: https://acme-v02.api.letsencrypt.org/directory
      privateKeySecretRef:
        name: prod-issuer-account-key
      solvers:
      - http01:
         ingress:
           class: nginx
  EOF
  clusterissuer.cert-manager.io/prod-issuer created

ClusterIssuerを検証します（準備完了と表示されることを確認してください）。

$ kubectl get clusterissuer  NAME          READY   AGE
	prod-issuer   True    34s

DNS-01の使用

この例では、DNS-01チャレンジを使用してドメインの所有権を認証するようにClusterIssuerを設定する方法を示します。DNSプロバイダーによっては、トークンの保存にKubernetes Secretを使用する必要があります。この例では、Cloudflareを使用しています。namespaceの指定に注意してください。cert-manager namespaceにデプロイされるcert-managerアプリケーションには、このSecretへのアクセス権が必要です。

この例では、アカウントから作成できるCloudflare APIトークンが必要です。作成したトークンを、以下の<API Token>の行に入力してください。Cloudflareを使用していない場合は、ご利用のプロバイダーのドキュメントに従ってください。

APIトークン用のSecretを作成します。

$ cat << EOF | kubectl apply -f   apiVersion: v1
  kind: Secret
  metadata:
    name: cloudflare-api-token-secret
    namespace: cert-manager
  type: Opaque
  stringData:
    api-token: <API Token> 
  EOF

チャレンジにDNS-01を使用するIssuerを作成します。

$ cat << EOF | kubectl apply -f   apiVersion: cert-manager.io/v1
  kind: ClusterIssuer
  metadata:
    name: prod-issuer
  spec:
    acme:
      email: example@example.com
      server: https://acme-v02.api.letsencrypt.org/directory
      privateKeySecretRef:
        name: prod-issuer-account-key
      solvers:
        - dns01:
            cloudflare:
              apiTokenSecretRef:
                name: cloudflare-api-token-secret
                key: api-token
  EOF

発行者を検証します（準備完了と表示されることを確認してください）。

$ kubectl get clusterissuer  NAME          READY   AGE
	prod-issuer   True    31m

Ingressをデプロイ

ここまでの作業の目的である、アプリケーション用Ingressリソースのデプロイを行います。これにより、先ほどデプロイしたNGINX Cafeアプリケーションにトラフィックがルーティングされます。

Kubernetes Ingressの使用

標準のKubernetes Ingressリソースを使用している場合は、次のデプロイ用YAMLを使用してIngressを構成し、証明書をリクエストします。

apiVersion: networking.k8s.io/v1   kind: Ingress 
  metadata: 
    name: cafe-ingress 
    annotations: 
      cert-manager.io/cluster-issuer: prod-issuer 
      acme.cert-manager.io/http01-edit-in-place: "true" 
  spec: 
    ingressClassName: nginx 
    tls: 
    - hosts: 
      - cert.example.com 
      secretName: cafe-secret 
    rules: 
    - host: cert.example.com 
      http: 
        paths: 
        - path: /tea 
          pathType: Prefix 
          backend: 
            service: 
              name: tea-svc 
              port: 
                number: 80 
        - path: /coffee 
          pathType: Prefix 
          backend: 
            service: 
              name: coffee-svc 
              port: 
number: 80

マニフェストの主要な部分を確認しておきましょう。

呼び出されるAPIは、標準のKubernetes Ingressです。
この構成で重要な設定は、metadata.annotationsの下にあり、acme.cert-manager.io/http01-edit-in-placeを「true」に設定します。この値は必須であり、チャレンジの提供方法を調整します。詳細については、「Supported Annotations」ドキュメントを参照してください。また、master/minion setupを使用して対応することもできます。
The spec.ingressClassNameは、インストール済みで今後使用するNGINX Ingress Controllerを指します。
The spec.tls.secret Kubernetes Secretリソースには、Let’s Encryptによる証明書の発行時に返される証明書キーが保存されます。
ホスト名cert.example.comは、spec.tls.hostsとspec.rules.hostに指定されています。これは、ClusterIssuerが証明書を発行したホスト名です。
The spec.rules.httpセクションでは、パスと、そのパスへのリクエストを処理するバックエンドServiceを定義します。たとえば、/teaへのトラフィックは、tea-svcのポート80に転送されます。

上記のマニフェストをインストール環境に合わせて変更します。少なくとも、spec.rules.hostとspec.tls.hostsの値を変更する必要がありますが、設定内のすべてのパラメーターを確認してください。
マニフェストを適用します。

$  kubectl apply -f ./cafe-virtual-server.yaml  virtualserver.k8s.nginx.org/cafe created

証明書が発行されるまで待ちます。READYフィールドの値が「True」になっていることを確認します。

$ kubectl get certificates  NAME                                      READY   SECRET        AGE
  certificate.cert-manager.io/cafe-secret   True    cafe-secret   37m

NGINX Virtual Server／Virtual Routesの使用

NGINX CRDを使用している場合は、以下のデプロイYAMLを使用してIngressを構成する必要があります。

  apiVersion: k8s.nginx.org/v1 
  kind: VirtualServer 
  metadata: 
    name: cafe 
  spec: 
    host: cert.example.com 
    tls: 
      secret: cafe-secret 
      cert-manager: 
        cluster-issuer: prod-issuer 
    upstreams: 
      - name: tea 
        service: tea-svc 
        port: 80 
      - name: coffee 
        service: coffee-svc 
        port: 80 
    routes: 
      - path: /tea 
        action: 
          pass: tea 
      - path: /coffee 
        action: 
          pass: coffee

ここでも、マニフェストの主要な部分をいくつか確認しておきましょう。

呼び出されるAPIは、VirtualServerリソース用のNGINX固有のk8s.nginx.org/v1です。
The spec.tls.secret Kubernetes Secretリソースには、Let’s Encryptによる証明書の発行時に返される証明書キーが保存されます。
ホスト名「cert.example.com」はspec.hostに指定されています。これは、ClusterIssuerが証明書を発行したホスト名です。
The spec.upstreamsの値は、ポートを含むバックエンドServiceを参照します。
The spec.routesは、ルートと、そのルートへのアクセス時に実行するアクションの両方を定義します。

上記のマニフェストをインストール環境に合わせて変更します。少なくとも、spec.hostの値を変更する必要がありますが、設定内のすべてのパラメーターを確認してください。
マニフェストを適用します。

$  kubectl apply -f ./cafe-virtual-server.yaml  virtualserver.k8s.nginx.org/cafe created

証明書が発行されるまで待ちます。ステータスが［Valid］と表示されることを確認してください。

$ kubectl get VirtualServers  NAME   STATE   HOST                    IP             PORTS      AGE
  cafe   Valid   cert.example.com   www.xxx.yyy.zzz   [80,443]   51m

証明書の表示

Kubernetes APIを介して証明書を表示できます。証明書のサイズや関連付けられた秘密鍵など、証明書の詳細を確認できます。

$ kubectl describe secret cafe-secret  Name:         cafe-secret
  Namespace:    default
  Labels:       <none>
  Annotations:  cert-manager.io/alt-names: cert.example.com
                cert-manager.io/certificate-name: cafe-secret
                cert-manager.io/common-name: cert.example.com
                cert-manager.io/ip-sans:
                cert-manager.io/issuer-group:
                cert-manager.io/issuer-kind: ClusterIssuer
                cert-manager.io/issuer-name: prod-issuer
                cert-manager.io/uri-sans:Type:  kubernetes.io/tlsData
  ====
  tls.crt:  5607 bytes
  tls.key:  1675 bytes

実際の証明書とキーを確認するには、次のコマンドを実行します。（注：これはKubernetes Secretsの弱点を示すものでもあります。つまり、必要なアクセス権限を持つユーザーであれば誰でも読み取ることができます。）

$ kubectl get secret cafe-secret -o yaml

Ingressをテスト

証明書をテストします。ここでは任意の方法を使用できます。以下の例では、cURLを使用します。成功した場合は、前述のようなブロックが表示されます。このブロックには、サーバー名、サーバーの内部アドレス、日付、選択したURI（ルート）（coffeeまたはtea）、リクエストIDが含まれます。失敗した場合はHTTPエラーコードが表示されます。多くの場合、400または301です。

$ curl https://cert.example.com/tea
  Server address: 10.2.0.6:8080
  Server name: tea-5c457db9-l4pvq
  Date: 02/Sep/2022:15:21:06 +0000
  URI: /tea
  Request ID: d736db9f696423c6212ffc70cd7ebecf
  $ curl https://cert.example.com/coffee
  Server address: 10.2.2.6:8080
  Server name: coffee-7c86d7d67c-kjddk
  Date: 02/Sep/2022:15:21:10 +0000
  URI: /coffee
Request ID: 4ea3aa1c87d2f1d80a706dde91f31d54

証明書の更新

冒頭で、このアプローチにより証明書の更新管理が不要になるとお伝えしました。しかし、その仕組みについてはまだ説明していません。なぜでしょうか。それは、cert-managerの中核をなす組み込み機能だからです。この自動プロセスでは、証明書が存在しない、期限切れである、有効期限まで15日以内であるとcert-managerが判断した場合、またはユーザーがCLIから新しい証明書をリクエストした場合、新しい証明書が自動的にリクエストされます。これ以上ないほど簡単です。