AWS Load Balancer Controller 추가 기능 설치 - Amazon EKS

AWS Load Balancer Controller 추가 기능 설치

AWS Load Balancer Controller는 Kubernetes 클러스터의 AWS Elastic Load Balancer를 관리합니다. 이 컨트롤러는 다음 리소스를 프로비저닝합니다.

  • AWS Kubernetes를 생성할 때 Ingress Application Load Balancer(ALB).

  • LoadBalancer 유형의 Kubernetes 서비스를 생성할 때 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 수신 컨트롤러였습니다. GitHub에서 관리되는 오픈 소스 프로젝트입니다. 이 주제에서는 기본 옵션을 사용하여 컨트롤러를 설치하는 방법을 설명합니다. GitHub에서 컨트롤러에 대한 전체 설명서를 볼 수 있습니다. 컨트롤러를 배포하기 전에 Amazon EKS의 애플리케이션 로드 밸런싱Amazon EKS의 네트워크 로드 밸런싱에서 필수 구성 요소 및 고려 사항을 검토하는 것이 좋습니다. 이러한 주제에는 AWS Load Balancer Controller가 AWS Application Load Balancer 및 Network Load Balancer를 프로비저닝하도록 요구하는 샘플 애플리케이션을 배포하는 방법에 관한 단계도 포함되어 있습니다.

사전 조건

  • 기존 Amazon EKS 클러스터. 배포하려면 Amazon EKS 시작하기 섹션을 참조하세요. 이 주제에서 사용되는 버전인 컨트롤러 버전 2.4.2를 사용하려면 클러스터가 1.19 이상이어야 합니다. 클러스터가 1.19 이전 버전인 경우 버전 2.3.1을 사용하는 것이 좋습니다.

  • 클러스터에 대한 기존 AWS Identity and Access Management(IAM) OpenID Connect(OIDC) 공급자. 이미 있는지 아니면 생성해야 하는지 확인하려면 클러스터에 대한 IAM OIDC 공급자 생성 섹션을 참조하세요.

  • 클러스터가 1.21 이전 버전인 경우 Amazon VPC CNI plugin for Kubernetes, kube-proxy, 및 CoreDNS 추가 기능은 서비스 계정 토큰에 나열된 최소 버전입니다.

Amazon EKS 클러스터에 AWS Load Balancer Controller 배포

다음 단계에서 example values를 사용자의 값으로 교체합니다. 클러스터가 1.19 이전 버전인 경우 2.4.2의 모든 인스턴스를 2.3.1로, v2_4_2_full.yaml의 모든 인스턴스를 v2_3_1_full.yaml로 변경합니다.

  1. IAM 정책을 생성합니다.

    1. 사용자 대신 AWS API를 호출할 수 있는 AWS Load Balancer Controller의 IAM 정책을 다운로드합니다.

      • AWS GovCloud(미국 동부) 또는 AWS GovCloud(미국 서부) AWS 리전

        curl -o iam_policy_us-gov.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.2/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.2/docs/install/iam_policy.json
    2. 이전 단계에서 다운로드한 정책을 사용하여 IAM 정책을 만듭니다. iam_policy_us-gov.json을 다운로드한 경우 iam_policy.jsoniam_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. 다음 콘텐츠를 load-balancer-role-trust-policy.json라는 파일에 복사합니다. 111122223333을 계정 ID로 바꿉니다. region-code를 클러스터가 있는 AWS 리전으로 바꿉니다. EXAMPLED539D4633E53DE1B71EXAMPLE을 이전 단계에서 반환된 출력으로 바꿉니다. 클러스터가 AWS GovCloud(미국 동부) 또는 AWS GovCloud(미국 서부) AWS 리전에 있는 경우 arn:aws:arn:aws-us-gov:로 바꿉니다.

      { "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" } } } ] }
    3. IAM 역할을 생성합니다.

      aws iam create-role \ --role-name AmazonEKSLoadBalancerControllerRole \ --assume-role-policy-document file://"load-balancer-role-trust-policy.json"
    4. 필요한 Amazon EKS 관리형 IAM 정책을 IAM 역할에 연결합니다. 111122223333을 계정 ID로 바꿉니다.

      aws iam attach-role-policy \ --policy-arn arn:aws:iam::111122223333:policy/AWSLoadBalancerControllerIAMPolicy \ --role-name AmazonEKSLoadBalancerControllerRole
    5. 다음 내용을 aws-load-balancer-controller-service-account.yaml이라는 파일에 저장합니다. 이때 111122223333을 계정 ID로 바꿉니다. 클러스터가 AWS GovCloud(미국 동부) 또는 AWS GovCloud(미국 서부) AWS 리전에 있는 경우 arn:aws:arn:aws-us-gov:로 바꿉니다.

      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
    6. 클러스터에 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

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

      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 역할에 다음 IAM 정책을 추가합니다. 이 정책은 Kubernetes용 ALB 수신 컨트롤러에서 생성된 리소스에 대한 AWS Load Balancer Controller 액세스를 허용합니다.

      1. IAM 정책을 다운로드합니다. 정책을 볼 수도 있습니다.

        curl -o iam_policy_v1_to_v2_additional.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.2/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-your-cluster-name-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에서 컨트롤러를 배포하려면 cert-manager에 의존하지 않는 Helm 프로시저를 사용하십시오.

    Helm
    1. eks-charts 리포지토리를 추가합니다.

      helm repo add eks https://aws.github.io/eks-charts
    2. 최신 차트가 적용되도록 로컬 리포지토리를 업데이트합니다.

      helm repo update
    3. 노드가 Amazon EKS Amazon ECR 이미지 리포지토리에 액세스할 수 없는 경우 다음 컨테이너 이미지를 가져와서 노드가 액세스할 수 있는 리포지토리로 푸시해야 합니다. 이미지를 가져오기, 태그 지정 및 자체 리포지토리로 푸시하는 방법에 대한 자세한 내용은 한 리포지토리에서 다른 리포지토리로 컨테이너 이미지 복사 단원을 참조하세요. 602401143452region-codeAmazon 컨테이너 이미지 레지스트리에 나열된 AWS 리전 값으로 바꿉니다.

      602401143452.dkr.ecr.region-code.amazonaws.com/amazon/aws-load-balancer-controller:v2.4.2
    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 명령에 다음 플래그를 한 후 602401143452region-codeAmazon 컨테이너 이미지 레지스트리에 나열된 AWS 리전의 값으로 바꿉니다. 이미지를 가져와서 자체 리포지토리로 푸시한 경우 전체 레지스트리 및 리포지토리를 자체 레지스트리 및 리포지토리로 바꿉니다.

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

      cluster-name을 사용자의 값으로 교체합니다. 다음 명령에서 aws-load-balancer-controller는 이전 단계에서 생성한 Kubernetes 서비스 계정입니다.

      helm install aws-load-balancer-controller eks/aws-load-balancer-controller \ -n kube-system \ --set clusterName=cluster-name \ --set serviceAccount.create=false \ --set serviceAccount.name=aws-load-balancer-controller
      중요

      배포된 차트는 보안 업데이트를 자동으로 수신하지 않습니다. 새 차트가 사용 가능해지면 수동으로 업그레이드해야 합니다. 업그레이드 시 이전 명령에서 installupgrade로 변경하되, 이전 명령을 실행하기 전에 다음 명령을 실행하여 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_2_full.yaml https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.4.2/v2_4_2_full.yaml
      2. 파일에 대해 편집한 항목:

        • my-cluster를 해당 클러스터 이름으로 바꿔 파일의 Deployment spec 섹션에 있는 your-cluster-name을 해당 클러스터의 이름으로 바꿉니다.

          sed -i.bak -e 's|your-cluster-name|my-cluster|' ./v2_4_2_full.yaml
        • 노드가 Amazon EKS Amazon ECR 이미지 리포지토리에 액세스할 수 없는 경우 다음 이미지를 가져와서 노드가 액세스할 수 있는 리포지토리로 푸시해야 합니다. 이미지를 가져오기, 태그 지정 및 자체 리포지토리로 푸시하는 방법에 대한 자세한 내용은 한 리포지토리에서 다른 리포지토리로 컨테이너 이미지 복사 단원을 참조하세요.

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

          매니페스트에 레지스트리 이름을 추가합니다. 다음 명령은 개인 리포지토리의 이름이 원본 리포지토리와 같다고 가정하고 개인 레스트리의 이름을 파일에 추가합니다. 원본 파일에서 기본적으로 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_2_full.yaml
        • 편집기에서 파일을 열고 다음 라인을 제거합니다. 이 섹션을 제거하면 이전 단계에서 생성한 aws-load-balancer-controller Kubernetes 서비스 계정에 추가된 IAM 역할의 주석이 컨트롤러가 배포될 때 덮어쓸 수 없습니다. 또한 컨트롤러를 삭제할 경우 이전 단계에서 생성한 서비스 계정도 유지됩니다.

          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 ---
        • 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_4_2_full.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의 네트워크 로드 밸런싱 단원을 참조하십시오.