安装 AWS Load Balancer Controller 附加组件 - Amazon EKS

安装 AWS Load Balancer Controller 附加组件

AWS Load Balancer Controller 管理适用于 Kubernetes 集群的 AWS 弹性负载均衡器。此控制器预置以下资源：

  • 当您创建 Kubernetes Ingress 时的 AWS 应用程序负载均衡器 (ALB, Application Load Balancer)。

  • 当您创建 LoadBalancer 类型的 Kubernetes 服务时的 AWS 网络负载均衡器（NLB）。在过去，实例目标使用 Kubernetes 网络负载均衡器，而 IP 目标使用 AWS 负载均衡器控制器。使用 AWS Load Balancer Controller 版本 2.3.0 或更高版本，您可以使用任一目标类型创建 NLB。有关 NLB 目标类型的更多信息，请参阅 Network Load Balancer 用户指南中的目标类型。

AWS Load Balancer Controller 控制器以前名为 AWS ALB 入口控制器。它是托管在 GitHub 上的一个开源项目。本主题描述如何使用原定设置选项安装该控制器。您可以在 GitHub 上查看关于该控制器的完整文档。在部署控制器之前，我们建议您查看 Amazon EKS 上的应用程序负载均衡 和 Amazon EKS 上的网络负载均衡 的先决条件和注意事项。这些主题还包括如何部署需要使用 AWS Load Balancer Controller 来预置 AWS 应用程序负载均衡器和网络负载均衡器的示例应用程序。

先决条件

  • 现有 版 Amazon EKS 集群。要部署一个角色，请参阅 开始使用 Amazon EKS。

  • 集群的现有 AWS Identity and Access Management IAM OpenID Connect (OIDC) 提供商。要确定您是否已经拥有一个或是否要创建一个，请参阅 为集群创建 IAM OIDC 提供商。

  • 如果您的集群为 1.21 版本或更高版本，确保您的 Amazon VPC CNI plugin for Kubernetes、kube-proxy 和 CoreDNS 附加组件为服务账户令牌中列出的最低版本。

  • 熟悉 AWS Elastic Load Balancing。有关更多信息，请参阅 Elastic Load Balancing 用户指南。

  • 熟悉 Kubernetes 服务和传入资源。

要将 AWS Load Balancer Controller 部署到 Amazon EKS 集群

在以下步骤中，将 example values 替换为您自己的值：。

  1. 创建一个 IAM policy。

    1. 下载 AWS Load Balancer Controller 的 IAM policy，该策略允许负载均衡器代表您调用 AWS API。

      • AWS GovCloud（美国东部）或 AWS GovCloud（美国西部）AWS 区域

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

      • 所有其他 AWS 区域

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

    2. 使用上一步中下载的策略创建一个 IAM policy。如果您已下载 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 的警告。

  2. 创建一个 IAM 角色。在 AWS Load Balancer Controller 的 kube-system 命名空间中创建名为 aws-load-balancer-controller 的 Kubernetes 服务账户，并使用 IAM 角色的名称注释 Kubernetes 服务账户。

    您可以使用 eksctl 或 AWS CLI 和 kubectl 创建 IAM 角色和 Kubernetes 服务账户。

    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 提供商 URL。

      aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer" --output text

      输出示例如下。

      oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE

      如果没有返回输出，则您必须为集群创建 IAM OIDC 提供程序。

    2. 将以下内容复制到您的设备。请将 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

    3. 创建 IAM 角色。

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

    4. 将所需的 Amazon EKS 托管 IAM policy 附加到 IAM 角色。请将 111122223333 替换为您的账户 ID。

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

    5. 将以下内容复制到您的设备。请将 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

    6. 在集群上创建 Kubernetes 服务账户。使用您创建的名为 AmazonEKSLoadBalancerControllerRole 的 IAM 角色注释名为 aws-load-balancer-controller 的 Kubernetes 服务账户。

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

  3. （可选）配置您的 Kubernetes 服务账户使用的 AWS Security Token Service 端点类型。有关更多信息，请参阅配置服务账户的 AWS Security Token Service 端点。

  4. 如果您当前没有安装适用于 Kubernetes 的 AWS ALB 入口控制器，或者当前安装了 Helm 的 AWS Load Balancer Controller 的 0.1.x 版本，则跳至下一步。

    卸载 AWS ALB 入口控制器或 AWS Load Balancer Controller 的 0.1.x 版本（仅在安装了 Helm 时）。使用原来安装它的工具完成该过程。AWS Load Balancer Controller 取代适用于 Kubernetes 的 AWS ALB 入口控制器的功能。

    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 版本，请将其卸载。由于与 Webhook API 版本不兼容，从 0.1.x 升级到版本 1.0.0 不起作用。

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

    1. 检查当前是否安装了该控制器。

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

      这是未安装控制器情况下的输出。跳至安装控制器步骤。

      Error from server (NotFound): deployments.apps "alb-ingress-controller" not found

      这是安装了控制器情况下的输出。

      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 policy 添加到在前一步骤中创建的 IAM 角色。该策略允许 AWS Load Balancer Controller 访问由适用于 Kubernetes 的 ALB 入口控制器创建的资源。

      1. 下载该 IAM policy。您还可以查看策略。

        curl -o iam_policy_v1_to_v2_additional.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.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 policy 并记下返回的 ARN。

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

      4. 将您创建的 IAM policy 附加到您在前一步骤中创建的 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

    3. 如果您的节点无权访问 Amazon EKS Amazon ECR 镜像存储库，则需要提取以下容器镜像并将其推送到节点有权访问的存储库。有关如何提取、标记和推送镜像到您自己的存储库的更多信息，请参阅 将容器镜像从一个存储库复制到另一个存储库。请将 602401143452 和 region-code 替换为 Amazon 容器镜像注册表 中列出的 AWS 区域 的值。

      602401143452.dkr.ecr.region-code.amazonaws.com/amazon/aws-load-balancer-controller:v2.4.4

    4. 安装 AWS Load Balancer Controller。如果要将控制器部署到被限制访问 Amazon EC2 实例元数据服务 (IMDS) 的 Amazon EC2 节点，或者部署到 Fargate 节点，则需要在以下 helm 命令中添加以下标志：

      • --set region=region-code

      • --set vpcId=vpc-xxxxxxxx

      如果要部署除 us-west-2 外的 AWS 区域，则将以下标志添加到 helm 命令，以将 602401143452 和 region-code 替换为 Amazon 容器镜像注册表 中列出的您的 AWS 区域 的值。如果您已提取镜像并将其推送到自己的存储库中，请将完整的注册表和存储库替换为您自己的注册表和存储库。

      --set image.repository=602401143452.dkr.ecr.region-code.amazonaws.com/amazon/aws-load-balancer-controller

      将 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。

      • 如果您的节点有权访问 quay.io 容器注册表，请安装 cert-manager 以将证书配置注入 Webhook。

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

      • 如果您的节点无权访问 quay.io，请完成以下任务：

        1. 下载清单。

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

        2. 请提取以下镜像并将其推送到节点有权访问的存储库。有关如何提取、标记和推送镜像到您自己的存储库的更多信息，请参阅 将容器镜像从一个存储库复制到另一个存储库。

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

        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. 安装控制器。

      1. 下载控制器规范。有关控制器的更多信息，请参阅 GitHub 上的文档。

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

      2. 对文件进行以下编辑。

        • 如果您已下载 v2_4_4_full.yaml 文件，请运行以下命令以删除清单中的 ServiceAccount 部分。如果您不删除此部分，系统将覆盖您在上一步中对服务账户所做的必需注释。如果删除此部分，若您删除了控制器，系统还会保留您在上一步中创建的服务账户。

          sed -i.bak -e '480,488d' ./v2_4_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_4_4_full.yaml

        • 如果您的节点无权访问 Amazon EKS Amazon ECR 镜像存储库，则需要提取以下镜像并将其推送到节点有权访问的存储库。有关如何提取、标记和推送镜像到您自己的存储库的更多信息，请参阅 将容器镜像从一个存储库复制到另一个存储库。

          amazon/aws-alb-ingress-controller:v2.4.4

          请为清单添加注册表的名称。以下命令假定您的私有存储库名称与源存储库的名称相同，并将您的私有注册表名称添加到文件中。在源文件中没有指定注册表，因为默认情况下 Kubernetes 会从 docker.io 中提取。将 111122223333.dkr.ecr.region-code.amazonaws.com 替换为您的注册表。此行假定您的私有存储库名称与源存储库的名称相同。如果不相同，请将私有注册表名称后面的 amazon/aws-alb-ingress-controller 文本给更改为您的存储库名称。

          sed -i.bak -e 's|amazon/aws-alb-ingress-controller|111122223333.dkr.ecr.region-code.amazonaws.com/amazon/aws-alb-ingress-controller|' ./v2_4_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_4_4_full.yaml

      4. 将 IngressClass 和 IngressClassParams 清单下载到您的集群。

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

      5. 将清单应用于集群。

        kubectl apply -f v2_4_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 清单进行部署，则只有一个副本。

  7. 在使用控制器预置AWS资源前，您的集群必须满足特定要求。有关更多信息，请参阅 Amazon EKS 上的应用程序负载均衡 和 Amazon EKS 上的网络负载均衡。