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 이상에서 대상 유형 중 하나를 사용하여 NLB를 생성할 수 있습니다. NLB 대상 유형에 대한 자세한 내용은 Network Load Balancer 사용 설명서에서 대상 유형을 참조하세요.

AWS Load Balancer Controller의 이전 이름은 AWS ALB Ingress Controller였습니다. GitHub에서 관리되는 오픈 소스 프로젝트입니다.

이 주제에서는 기본 옵션을 사용하여 컨트롤러를 설치하는 방법을 설명합니다. GitHub에서 컨트롤러에 대한 전체 설명서를 볼 수 있습니다. 컨트롤러를 배포하기 전에 Amazon EKS 애플리케이션 로드 밸런싱 및 Amazon EKS의 네트워크 로드 밸런싱에서 필수 구성 요소 및 고려 사항을 검토하는 것이 좋습니다. 이러한 주제에는 AWS Load Balancer Controller이(가) AWS Application Load Balancer 및 Network Load Balancer를 프로비저닝하도록 요구하는 샘플 애플리케이션을 배포하는 방법에 관한 단계도 포함되어 있습니다.

필수 조건

• 기존 Amazon EKS 클러스터. 배포하려면 Amazon EKS 시작하기 섹션을 참조하세요.

• 클러스터에 대한 기존 AWS Identity and Access Management(IAM) OpenID Connect(OIDC) 제공업체입니다. 이미 있는지 아니면 생성해야 하는지 확인하려면 클러스터의 IAM OIDC 제공업체 생성 부분을 참조하세요.

• Amazon VPC CNI plugin for Kubernetes, kube-proxy 및 CoreDNS 추가 기능이 서비스 계정 토큰에 나열된 최소 버전인지 확인합니다.

• AWS Elastic Load Balancing을 숙지합니다. 자세한 내용은 Elastic Load Balancing 사용 설명서를 참조하세요.

• Kubernetes 서비스 및 수신 리소스를 숙지합니다.

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 서비스 계정을 생성하고 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 제공업체 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. 필요한 Amazon EKS 관리형 IAM 정책을 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 수신 컨트롤러가 설치되지 않거나 현재 Helm과 함께 AWS Load Balancer Controller의 0.1.x 버전이 설치되지 않은 경우 다음 단계로 넘어갑니다.

   AWS ALB Ingress Controller 또는 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이 설치된 경우 제거합니다. 버전 0.1.x에서 1.0.0으로의 업그레이드는 웹후크 API 버전과 호환되지 않아 작동되지 않습니다.

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

   Kubernetes manifest

   1. 이 컨트롤러가 현재 설치되어 있는지 확인합니다.

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

      컨트롤러가 설치되어 있지 않은 경우의 출력입니다. 컨트롤러 설치 단계로 건너뜁니다.

      서버에서 발생한 오류(찾을 수 없음): 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 정책을 추가합니다. 이 정책은 Kubernetes용 ALB 수신 컨트롤러에서 생성된 리소스에 대한 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) 탭을 선택합니다. 실제 ID(Physical 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.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. 컨트롤러를 설치합니다.

      1. 컨트롤러 사양을 다운로드합니다. 컨트롤러에 대한 자세한 내용은 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에 배포하는 경우, - args:에서 following parameters를 추가합니다.

           [...]
           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 매니페스트를 사용하여 배포한 경우 복제본이 하나만 있습니다.

7. 컨트롤러를 사용하여 AWS 리소스를 프로비저닝하기 전에 클러스터가 특정 요구 사항을 충족해야 합니다. 자세한 내용은 Amazon EKS 애플리케이션 로드 밸런싱 및 Amazon EKS의 네트워크 로드 밸런싱 섹션을 참조하세요.