AWS Load Balancer Controller アドオンのインストール - Amazon EKS

AWS Load Balancer Controller アドオンのインストール

重要

バージョン 2.5 以降では、AWS Load Balancer Controller は、type: LoadBalancer を持つ Kubernetes サービスリソースのデフォルトコントローラーとなり、サービスごとに AWS Network Load Balancer (NLB) を作成します。これは、サービスの変更ウェブフックを変化することで実行され、これにより type: LoadBalancer の新しいサービスの spec.loadBalancerClass フィールドが service.k8s.aws/nlb に設定されます。Helm チャートの値 enableServiceMutatorWebhook を false に設定すると、この機能をオフにして、レガシークラウドプロバイダーをデフォルトのコントローラーとして使用するように戻すことができます。この機能をオフにしない限り、クラスターはサービスに新しい Classic Load Balancer をプロビジョニングしません。既存の Classic Load Balancer は従来どおり機能します。

AWS Load Balancer Controller によって Kubernetes クラスター向けの AWS Elastic Load Balancer が管理されます。コントローラは、以下のリソースをプロビジョニングします。

Kubernetes Ingress

Kubernetes Ingress を作成すると、AWS Load Balancer Controller は AWS Application Load Balancer (ALB) を作成します。

LoadBalancer タイプの Kubernetes サービス

タイプ LoadBalancer の Kubernetes サービスを作成すると、AWS Load Balancer Controller は AWS Network Load Balancer (NLB) を作成します。以前は、インスタンスターゲットには Kubernetes network load balancer が使用されていましたが、IP ターゲットには AWS Load Balancer Controller が使用されていました。AWS Load Balancer Controller バージョン 2.3.0 以降では、いずれかのターゲットタイプを使用して NLBs を作成できます。NLB ターゲットタイプの詳細については、Network Load Balancer のユーザーガイドの 「ターゲットタイプ」を参照してください。

AWS Load Balancer Controller は、以前、AWS ALB Ingress Controller と呼ばれていたものです。これは、GitHub で管理される オープンソースのプロジェクト です。

このトピックでは、デフォルトのオプションを使用してコントローラをインストールする方法について説明します。GitHub でコントローラーの完全な ドキュメント を表示できます。コントローラをデプロイする前に、Amazon EKS でのアプリケーション負荷分散 および Amazon EKS でのネットワーク負荷分散 についての前提条件と考慮事項を、確認しておくことをお勧めします。これらのトピックでは、AWS Application Load Balancer と Network Load Balancer をプロビジョニングするにあたり、AWS Load Balancer Controller を必要とするサンプルアプリケーションをデプロイする方法の手順も扱います。

前提条件
Amazon EKS クラスターに AWS Load Balancer Controller デプロイするには

以下のステップでは、 example values を独自の値に置き換えます。

  1. IAM ポリシーを作成します。

    1. ユーザーに代わって AWS API を呼び出すことを許可する、AWS Load Balancer Controller 用の IAM ポリシーをダウンロードします。

      • AWS GovCloud (米国東部) あるいは AWS GovCloud (米国東部) の AWS リージョン

        $ curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.5.4/docs/install/iam_policy_us-gov.json

      • その他すべての AWS リージョン

        $ curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.5.4/docs/install/iam_policy.json

    2. 前のステップでダウンロードしたポリシー を使用して、IAM ポリシーを作成します。iam_policy_us-gov.json をダウンロードしている場合は、コマンドを実行する前に iam_policy.json を iam_policy_us-gov.json に変更します。

      $ aws iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy.json
      注記

      AWS Management Console でポリシーを確認すると、コンソールには [ELB] サービスに関する警告が表示されますが、[ELB v2] サービスに関する警告は表示されません。これは、ポリシー内のアクションの一部が [ELB v2] には存在するが、[ELB] には存在しないために起こります。[ELB] に関する警告は無視できます。

  2. IAM ロールを作成します。AWS Load Balancer Controller 用の kube-system 名前空間に aws-load-balancer-controller という名前のKubernetes サービスアカウントを作成し、Kubernetes サービスアカウントに IAM ロールの名前をアノテーションします。

    IAM ロールと Kubernetes サービスアカウントを作成するには、eksctl または AWS CLI と kubectl を使用します。

    eksctl

    my-cluster をクラスターの名前に置き換え、111122223333 をアカウント ID に置き換えてから、コマンドを実行します。クラスターが AWS GovCloud (米国東部) または AWS GovCloud (米国東部) の AWS リージョン にある場合は、arn:aws: を arn:aws-us-gov: に置き換えます。

    $ eksctl create iamserviceaccount \
  --cluster=my-cluster \
  --namespace=kube-system \
  --name=aws-load-balancer-controller \
  --role-name AmazonEKSLoadBalancerControllerRole \
  --attach-policy-arn=arn:aws:iam::111122223333:policy/AWSLoadBalancerControllerIAMPolicy \
  --approve
    AWS CLI and kubectl

    AWS CLI および kubectl の使用

    1. クラスターの OIDC プロバイダー ID を取得し、変数に格納します。

      oidc_id=$(aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer" --output text | cut -d '/' -f 5)

    2. クラスターの ID を持つ IAM OIDC プロバイダーが既にアカウントにあるかどうかを確認します。

      aws iam list-open-id-connect-providers | grep $oidc_id | cut -d "/" -f4

      出力が返された場合は、クラスター用の IAM OIDC プロバイダーがすでに存在します。出力が返されない場合は、クラスター用の IAM OIDC プロバイダーを作成する必要があります。詳細については、「クラスター用の IAM OIDC プロバイダーの作成」を参照してください。

    3. 次のコンテンツをデバイスにコピーします。111122223333 をアカウントID に置き換えます。region-code をクラスターのある AWS リージョン に置き換えます。EXAMPLED539D4633E53DE1B71EXAMPLE を、前のステップで返された出力に置き換えます。クラスターが AWS GovCloud (米国東部) または AWS GovCloud (米国東部) の AWS リージョン にある場合は、arn:aws: を arn:aws-us-gov: に置き換えます。テキストを置き換えたら、変更したコマンドを実行して load-balancer-role-trust-policy.json ファイルを作成します。

      cat >load-balancer-role-trust-policy.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com",
                    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:aws-load-balancer-controller"
                }
            }
        }
    ]
}
EOF

    4. IAM ロールを作成します。

      aws iam create-role \
  --role-name AmazonEKSLoadBalancerControllerRole \
  --assume-role-policy-document file://"load-balancer-role-trust-policy.json"

    5. IAM ロールに、必要な Amazon EKS 管理の IAM ポリシーをアタッチします。111122223333 をアカウントID に置き換えます。

      aws iam attach-role-policy \
  --policy-arn arn:aws:iam::111122223333:policy/AWSLoadBalancerControllerIAMPolicy \
  --role-name AmazonEKSLoadBalancerControllerRole

    6. 次のコンテンツをデバイスにコピーします。111122223333 をアカウントID に置き換えます。クラスターが AWS GovCloud (米国東部) または AWS GovCloud (米国東部) の AWS リージョン にある場合は、arn:aws: を arn:aws-us-gov: に置き換えます。テキストを置き換えたら、変更したコマンドを実行して aws-load-balancer-controller-service-account.yaml ファイルを作成します。

      cat >aws-load-balancer-controller-service-account.yaml <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: aws-load-balancer-controller
  name: aws-load-balancer-controller
  namespace: kube-system
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/AmazonEKSLoadBalancerControllerRole
EOF

    7. クラスター上で Kubernetes サービスアカウントを作成します。aws-load-balancer-controller という名前の Kubernetes サービスアカウントは、AmazonEKSLoadBalancerControllerRole という名前で作成した IAM ロールで注釈が付けられています。

      $ kubectl apply -f aws-load-balancer-controller-service-account.yaml

  3. (オプション) Kubernetes サービスアカウントで使用されている AWS Security Token Service エンドポイントタイプを設定します。詳細については、「サービスアカウントの AWS Security Token Service エンドポイントの設定」を参照してください。

  4. 現在、Kubernetes 用の AWS ALB Ingress Controller がインストールされていない場合、または現在 Helm とともに AWS Load Balancer Controller の 0.1. バージョンがインストールされていない場合は、次のステップにスキップしてください。

    AWS ALB Ingress Controller、あるいは AWS Load Balancer Controller のバージョン 0.1.x (Helm を使用してインストールした場合のみ) をアンインストールします。この手順は、元々インストールしてあるツールを使用して実行します。AWS Load Balancer Controller は、AWS ALB Ingress Controller for Kubernetes の機能を置き換えます。

    Helm

    1. incubator/aws-alb-ingress-controller Helm チャートをインストールしてある場合は、これをアンインストールします。

      $ helm delete aws-alb-ingress-controller -n kube-system

    2. eks-charts/aws-load-balancer-controller のバージョン 0.1.x をインストールしている場合は、これをアンインストールします。0.1.x からバージョン 1.0.0 へのアップグレードは、Webhook API のバージョンとの互換性がないため動作しません。

      $ helm delete aws-load-balancer-controller -n kube-system
    Kubernetes manifest

    1. Ingress Controller がインストール済みであるかどうかを確認します。

      $ kubectl get deployment -n kube-system alb-ingress-controller

      これは、コントローラが取り付けられていない場合の出力です。「コントローラーをインストールする」のステップに進みます。

      サーバーからのエラー (NotFound): deployments.apps「alb-ingress-controller」が見つかりません

      これは、コントローラが取り付けられている場合の出力です。

      NAME                   READY UP-TO-DATE AVAILABLE AGE
alb-ingress-controller 1/1   1          1         122d

    2. 次のコマンドを入力してコントローラを削除します。

      $ kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/aws-alb-ingress-controller/v1.1.8/docs/examples/alb-ingress-controller.yaml
kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/aws-alb-ingress-controller/v1.1.8/docs/examples/rbac-role.yaml

    3. 次の IAM ポリシーを、前のステップで作成した IAM ロールに追加します。このポリシーは、ALB Ingress Controller for Kubernetes によって作成されたリソースへのアクセスを、AWS Load Balancer Controller に許可します。

      1. IAM ポリシーをダウンロードします。ポリシーを表示することもできます。

        $ curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.5.4/docs/install/iam_policy_v1_to_v2_additional.json

      2. クラスターが AWS GovCloud (米国東部) または AWS GovCloud (米国東部) の AWS リージョン にある場合は、arn:aws: を arn:aws-us-gov: に置き換えます。。

        $ sed -i.bak -e 's|arn:aws:|arn:aws-us-gov:|' iam_policy_v1_to_v2_additional.json

      3. IAM ポリシーを作成し、返された ARN を書き留めます。

        $ aws iam create-policy \
  --policy-name AWSLoadBalancerControllerAdditionalIAMPolicy \
  --policy-document file://iam_policy_v1_to_v2_additional.json

      4. 作成した IAM ポリシーを、前のステップで作成した IAM ロールにアタッチします。your-role-name はロールの名前に置き換えます。eksctl を使用してロールを作成している場合、作成されたロール名を見つけるには、AWS CloudFormation コンソールを開き、eksctl-my-cluster-addon-iamserviceaccount-kube-system-aws-load-balancer-controller スタックを選択します。[Resources (リソース)] タブを選択します。ロール名は、[Physical ID (物理 ID)] 列で見つかります。AWS Management Consoleを使用してロールを作成した場合、ロール名は作成時に付けたもの (例えば、AmazonEKSLoadBalancerControllerRole など) になります。クラスターが AWS GovCloud (米国東部) または AWS GovCloud (米国東部) の AWS リージョン にある場合は、arn:aws: を arn:aws-us-gov: に置き換えます。

        $ aws iam attach-role-policy \
  --role-name your-role-name \
  --policy-arn arn:aws:iam::111122223333:policy/AWSLoadBalancerControllerAdditionalIAMPolicy
    表示を増やす表示を減らす

  5. Helm V3 以降を使用して、または Kubernetes マニフェストを適用して AWS Load Balancer Controller をインストールします。Fargate でコントローラーをデプロイする場合は、Helm プロシージャを使用します。Helm プロシージャは、自己署名証明書を生成するため、cert-manager に依存しません。

    Helm

    1. eks-charts リポジトリを追加します。

      $ helm repo add eks https://aws.github.io/eks-charts

    2. ローカルリポジトリを更新して、最新のグラフがあることを確認します。

      $ helm repo update eks

    3. ノードが Amazon ECR Public イメージリポジトリにアクセスできない場合は、次のコンテナイメージをプルして、ノードがアクセス可能なリポジトリにプッシュする必要があります。イメージをプルし、タグ付けして独自のリポジトリにプッシュする方法の詳細については、あるリポジトリから別のリポジトリにコンテナイメージをコピーする を参照してください。

      public.ecr.aws/eks/aws-load-balancer-controller:v2.5.4

    4. AWS Load Balancer Controller のインストール。Amazon EC2 インスタンスメタデータサービス (IMDS) に対するアクセスが制限されている Amazon EC2 ノードにコントローラーをデプロイする場合、または Fargate にデプロイする場合には、次の helm コマンドに次のフラグを追加します。

      • --set region=region-code

      • --set vpcId=vpc-xxxxxxxx

      my-cluster を自分のクラスター名に置き換えます。次のコマンドでは、aws-load-balancer-controller は前のステップで作成した Kubernetes サービスアカウントです。

      $ helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
  -n kube-system \
  --set clusterName=my-cluster \
  --set serviceAccount.create=false \
  --set serviceAccount.name=aws-load-balancer-controller
      重要

      デプロイされたグラフは、セキュリティに関する更新を自動的に受信しません。この更新が利用可能になったら、手動で新しいグラフにアップグレードする必要があります。アップグレードする場合は、前のコマンドの install を upgrade に変更します。ただし、前のコマンドを実行する前に次のコマンドを実行し、TargetGroupBinding のカスタムリソース定義をインストールします。

      $ kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller/crds?ref=master"
    Kubernetes manifest

    1. 以下のいずれかの方法で cert-manager をインストールして、Webhook に証明書設定を導入します。詳細については、「cert-manager ドキュメント」の「開始方法」を参照してください。

      • ノードが quay.io コンテナレジストリにアクセスできる場合は、cert-manager をインストールして、Webhook に証明書設定を挿入します。

        $ kubectl apply \
    --validate=false \
    -f https://github.com/jetstack/cert-manager/releases/download/v1.12.3/cert-manager.yaml

      • ノードが quay.io コンテナレジストリにアクセスできない場合、以下のタスクをすべて実行します。

        1. マニフェストをダウンロードします。

          curl -Lo cert-manager.yaml https://github.com/jetstack/cert-manager/releases/download/v1.12.3/cert-manager.yaml

        2. 次のイメージをプルして、ノードがアクセスできるリポジトリにプッシュします。イメージをプルし、タグ付けして独自のリポジトリにプッシュする方法の詳細については、あるリポジトリから別のリポジトリにコンテナイメージをコピーする を参照してください。

          quay.io/jetstack/cert-manager-cainjector:v1.12.3
quay.io/jetstack/cert-manager-controller:v1.12.3
quay.io/jetstack/cert-manager-webhook:v1.12.3

        3. 三つのイメージのマニフェストの quay.io を、独自のレジストリ名に置き換えます。次のコマンドは、プライベートリポジトリの名前がソースリポジトリと同じであることを前提としています。111122223333.dkr.ecr.region-code.amazonaws.com をプライベートレジストリに置き換えます。

          $ sed -i.bak -e 's|quay.io|111122223333.dkr.ecr.region-code.amazonaws.com|' ./cert-manager.yaml

        4. マニフェストを適用します。

          $ kubectl apply \
    --validate=false \
    -f ./cert-manager.yaml
        表示を増やす表示を減らす

    2. Load Balancer Controller をインストールします。

      1. Controller の詳細をダウンロードします。コントローラーの詳細については、「GitHub」の ドキュメント を参照してください。

        curl -Lo v2_5_4_full.yaml https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.5.4/v2_5_4_full.yaml

      2. ファイルに以下の編集を行います。

        • v2_5_4_full.yaml ファイルをダウンロードした場合は、次のコマンドを実行してマニフェストの ServiceAccount セクションを削除します。このセクションを削除しないと、前のステップでサービスアカウントに追加した必須の注釈が上書きされます。コントローラーを削除した場合、このセクションの削除により、前のステップで作成したサービスアカウントも保持されます。

          $ sed -i.bak -e '596,604d' ./v2_5_4_full.yaml

          別のバージョンのファイルをダウンロードした場合は、エディタでファイルを開き、次の行を削除します。

          apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: aws-load-balancer-controller
  name: aws-load-balancer-controller
  namespace: kube-system
---

        • my-cluster をユーザーのクラスター名で置き換えて、ファイルの Deployment spec セクションの your-cluster-name をクラスター名に置き換えます。

          $ sed -i.bak -e 's|your-cluster-name|my-cluster|' ./v2_5_4_full.yaml

        • ノードが Amazon EKS Amazon ECR イメージリポジトリにアクセスできない場合は、次のイメージをプルして、ノードがアクセスできるリポジトリにプッシュする必要があります。イメージをプルし、タグ付けして独自のリポジトリにプッシュする方法の詳細については、あるリポジトリから別のリポジトリにコンテナイメージをコピーする を参照してください。

          public.ecr.aws/eks/aws-load-balancer-controller:v2.5.4

          マニフェストにレジストリの名前を追加します。次のコマンドは、プライベートリポジトリの名前がソースリポジトリと同じであると仮定し、プライベートレジストリの名前をファイルに追加します。111122223333.dkr.ecr.region-code.amazonaws.com は、実際のレジストリに置き換えます。この行は、プライベートリポジトリにソースリポジトリと同じ名前を付けたことを前提としています。そうでない場合は、プライベートレジストリ名の後の eks/aws-load-balancer-controller テキストを、リポジトリ名に変更します。

          $ sed -i.bak -e 's|public.ecr.aws/eks/aws-load-balancer-controller|111122223333.dkr.ecr.region-code.amazonaws.com/eks/aws-load-balancer-controller|' ./v2_5_4_full.yaml
          表示を増やす表示を減らす

        • Amazon EC2 インスタンスメタデータサービス (IMDS) に対するアクセスが制限されている Amazon EC2 ノードにコントローラをデプロイする場合、または Fargate にデプロイする場合には、following parameters の下に - args: を追加します。

          [...]
spec:
      containers:
        - args:
            - --cluster-name=your-cluster-name
            - --ingress-class=alb
            - --aws-vpc-id=vpc-xxxxxxxx
            - --aws-region=region-code
            
            
[...]

      3. ファイルを適用します。

        $ kubectl apply -f v2_5_4_full.yaml

      4. IngressClass および IngressClassParams マニフェストをクラスターにダウンロードします。

        $ curl -Lo v2_5_4_ingclass.yaml https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.5.4/v2_5_4_ingclass.yaml

      5. マニフェストをクラスターに適用します。

        $ kubectl apply -f v2_5_4_ingclass.yaml

  6. コントローラがインストールされていることを確認します。

    $ kubectl get deployment -n kube-system aws-load-balancer-controller

    出力例は次のとおりです。

    NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
aws-load-balancer-controller   2/2     2            2           84s

    Helm を使用してデプロイした場合は、前の出力を受け取ります。Kubernetes マニフェストを使用してデプロイした場合、レプリカは 1 つのみとなります。

  7. コントローラーを使用して AWS リソースをプロビジョニングする場合には、クラスターは特定の要件を満たしている必要があります。詳細については、Amazon EKS でのアプリケーション負荷分散 および Amazon EKS でのネットワーク負荷分散 を参照してください。