에이전트의 코드와 모델 설정을 변경할 때는 새 버전을 배포하고 정상적으로 응답하는지 확인해야 합니다. Amazon Elastic Kubernetes Service(Amazon EKS)와 GitOps로 애플리케이션을 운영하는 팀이라면, Amazon Bedrock AgentCore에 배포하는 에이전트도 같은 저장소와 배포 절차로 관리할 수 있습니다.

이 글에서는 기존 GitOps 환경을 사용해 Amazon Bedrock AgentCore Runtime에 에이전트를 배포하는 방법을 소개합니다. Helm 차트와 환경별 values를 Git에 기록하면 Argo CD가 Kubernetes 리소스로 적용하고, AWS Controllers for Kubernetes(ACK)가 해당 구성을 AWS API에 반영합니다. 플랫폼 팀은 Argo CD에서 배포 상태를 확인하고, 에이전트는 AgentCore Runtime에서 실행합니다.

실습에서는 AWS Cloud Development Kit(AWS CDK)로 기반 인프라를 구성하고, Strands Agents SDK로 작성한 에이전트를 Runtime에 배포합니다. 이후 Gateway 호출과 새 이미지 배포를 수행하고, Argo CD 상태와 API 응답에서 릴리스가 전환됐는지 확인합니다.

솔루션 개요

배포는 Git에 저장한 이미지 digest를 변경하는 것으로 시작합니다. Argo CD와 ACK가 새 구성을 Runtime에 적용하면, 배포 후 검증 Job이 Gateway를 호출해 예상한 릴리스가 응답하는지 검사합니다. 리소스가 준비됐는지와 실제 모델 호출이 성공했는지를 각각 확인합니다.

아키텍처와 리소스 소유권

그림 1. 배포 컨트롤러는 EKS에, 에이전트 실행 환경은 AgentCore에 배치합니다. 파랑은 관리와 배포, 초록은 요청 경로, 주황은 이미지, 보라는 로그와 관측을 나타냅니다. 관리용 ALB는 Argo CD 접속에 사용합니다. NAT, VPC endpoint, 관리자의 EKS API 접근 경로는 생략했습니다. 글로벌 교차 리전 추론을 사용하므로 모델 요청은 검증 리전인 us-east-1 외의 지원 리전에서도 처리될 수 있습니다.

관리 경로는 Git → Argo CD → Kubernetes 사용자 정의 리소스(CR) → ACK → AWS API 순서입니다. 실제 요청은 애플리케이션 → AgentCore Gateway → AgentCore Runtime → Amazon Bedrock 순서로 전달됩니다. 에이전트는 AgentCore Runtime에서 실행하므로, EKS에 에이전트용 Deployment나 ReplicaSet을 생성하지 않습니다.

같은 리소스를 서로 다른 도구가 수정하지 않도록 소유권을 나눕니다.

기반 인프라는 두 가용 영역의 프라이빗 서브넷에 ARM64 m7g.large 노드 두 대를 배치합니다. 실습에서는 새 EKS 클러스터를 생성합니다. 기존 클러스터에 적용할 때는 컨트롤러의 중복 설치 여부를 확인하고, 네임스페이스와 Pod Identity 연결 설정을 플랫폼 정책에 맞춰 조정해야 합니다.

사전 준비 사항

데모 코드는 aws-samples GitHub 저장소의 containers/eks-ack-agentcore-gitops에서 받을 수 있습니다. 이 폴더에는 README와 실습에 필요한 코드가 있습니다. 이후 명령은 샘플 디렉터리에서 실행합니다.

git clone https://github.com/aws-samples/kr-tech-blog-sample-code.git
cd kr-tech-blog-sample-code/containers/eks-ack-agentcore-gitops

실습 전에 다음 항목을 준비합니다.

• AWS 계정과 권한: 비운영 계정에서 AWS CLI의 default 프로파일을 설정합니다. CDK 스택의 VPC, EKS, ECR, IAM 리소스를 생성하고 AgentCore와 모델을 사용할 권한이 필요합니다. 검증 리전은 us-east-1입니다.
• 로컬 실행 도구: Node.js와 npm, Helm, kubectl, Docker Buildx, uv, GitHub CLI, jq를 설치합니다. AWS CDK는 프로젝트 의존성으로 설치하며 ACK의 Go 빌드는 Docker 안에서 수행합니다. k9s는 선택 사항입니다.
• 배포용 Git 저장소: 계정별 values를 관리할 자신의 저장소를 준비합니다. 실습용 configure-gitops.sh는 해당 저장소에 읽기 전용 deploy key를 등록하므로 이 작업을 수행할 GitHub 권한도 필요합니다. 계정별 값을 aws-samples 저장소에 올리지 않습니다.
• 네트워크와 모델 정책: EKS API와 관리용 ALB에 접근할 관리자의 공인 IPv4 주소와 EKS 관리 권한을 부여할 IAM 사용자 또는 역할 ARN을 준비합니다. 조직의 Service Control Policy(SCP)와 데이터 처리 정책에서 글로벌 교차 리전 추론 사용을 허용하는지도 확인합니다.

이 실습은 새 EKS 환경을 만들기 때문에 EKS, EC2, NAT Gateway, ALB와 모델 호출 등에 비용이 발생합니다. 실습이 끝나면 뒤의 리소스 정리 절차에 따라 삭제합니다. 배포에는 약 15분이 소요되며 환경에 따라 달라질 수 있습니다.

리소스 버전

다음은 데모 환경에서 사용한 주요 버전입니다. 샘플 코드는 버전 설정 파일과 lockfile로 의존성을 고정합니다. 이 표는 검증에 사용한 조합이며 최신 버전 목록은 아닙니다. 운영 환경에서는 조직의 지원 버전과 보안 정책을 확인하고, 변경한 조합으로 다시 검증해야 합니다.

ACK 1.15.1은 AgentRuntime을 기본 지원합니다. 예제 저장소의 패치는 Gateway HTTP Runtime target을 추가하고, 이름을 지정한 Runtime endpoint의 버전 업데이트를 보정합니다. 이 실습에서는 Runtime 버전 업데이트와 PostSync 사후 검증을 사용합니다. Argo Rollouts의 blue/green, canary와 자동 rollback은 이 예제에 구현하지 않았으며, 적용하려면 트래픽 전환과 복구 절차를 별도로 구성해야 합니다.

1. AWS CDK로 기반 인프라 배포하기

CDK는 VPC, EKS, IAM 역할과 ECR 저장소를 생성합니다. 다음 VPC 설정은 두 가용 영역에 퍼블릭 서브넷과 프라이빗 서브넷을 만들고, 데모 비용을 고려해 NAT Gateway를 하나만 사용합니다.

const vpc = new ec2.Vpc(this, 'Vpc', {
  maxAzs: 2,
  natGateways: 1,
  ipAddresses: ec2.IpAddresses.cidr('10.83.0.0/16'),
  subnetConfiguration: [
    { name: 'public', subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
    { name: 'private', subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS, cidrMask: 24 },
  ],
});

EKS 노드는 프라이빗 서브넷에 배치합니다. 에이전트 이미지가 저장될 ECR은 태그 덮어쓰기를 막고 이미지 스캔을 활성화합니다. 저장소를 RETAIN으로 지정했으므로 CDK 스택 삭제가 이미지 삭제로 이어지지 않습니다.

const repository = new ecr.Repository(this, 'AgentRepository', {
  repositoryName: prefix,
  imageScanOnPush: true,
  imageTagMutability: ecr.TagMutability.IMMUTABLE,
  encryption: ecr.RepositoryEncryption.AES_256,
  lifecycleRules: [{ tagStatus: ecr.TagStatus.UNTAGGED, maxImageCount: 20 }],
  removalPolicy: RemovalPolicy.RETAIN,
});

배포 전에 ADMIN_CIDR과 ADMIN_PRINCIPAL_ARN을 설정합니다. ADMIN_CIDR은 EKS API와 관리용 ALB 접근을 허용할 공인 IPv4 주소이며, 이 샘플에서는 /32 형식으로 지정합니다. ADMIN_PRINCIPAL_ARN은 EKS 관리자 권한을 부여할 IAM 사용자 또는 역할 ARN입니다. 역할을 사용하는 경우 aws sts get-caller-identity가 반환하는 STS 세션 ARN 대신 원래 IAM 역할 ARN을 입력해야 합니다. 아래 예시 값은 자신의 환경에 맞게 변경합니다. 기반 배포 스크립트는 검사와 diff 후 별도 승인 프롬프트 없이 배포하므로, 실행 전에 infra/platform-stack.ts와 배포 설정을 검토해야 합니다.

export AWS_PROFILE=default
export AWS_REGION=us-east-1
export ADMIN_CIDR="YOUR_PUBLIC_IPV4/32"
export ADMIN_PRINCIPAL_ARN="YOUR_IAM_USER_OR_ROLE_ARN"
aws sts get-caller-identity

npm ci
source scripts/environment.sh
npx cdk bootstrap "aws://$CDK_DEFAULT_ACCOUNT/$AWS_REGION"
bash scripts/deploy-foundation.sh

kubectl --context eks-ack-agentcore get nodes
k9s --context eks-ack-agentcore

deploy-foundation.sh는 TypeScript 검사와 테스트, strict synth, diff를 거쳐 CDK를 배포하고 kubeconfig에 eks-ack-agentcore context를 등록합니다. CNI 권한을 Pod Identity로 전환하는 후속 CDK 배포도 포함합니다. 출력값은 .state/outputs.json에 저장됩니다.

2. Helm으로 플랫폼 컨트롤러 설치하기

다음 명령은 ACK 확장 이미지를 빌드하고 플랫폼 컨트롤러를 설치합니다.

bash scripts/build-ack-controller.sh
bash scripts/install-platform.sh
helm list --all-namespaces --kube-context eks-ack-agentcore

Argo CD에는 ACK 상태를 읽는 health check를 설정합니다. Runtime의 ACK.ResourceSynced 조건이 True이고 AWS 상태가 READY일 때 Healthy로 표시합니다. 생성 중이거나 동기화가 끝나지 않았으면 Progressing, 복구할 수 없는 ACK 오류는 Degraded로 표시합니다. 모델 호출 성공은 별도 PostSync Job으로 확인합니다.

ACK는 agentcore 네임스페이스만 감시하고 EKS Pod Identity 역할로 AWS API를 호출합니다. Runtime은 ACK 1.15.1의 기본 지원을 사용하며, Gateway HTTP Runtime target과 이름을 지정한 endpoint의 버전 업데이트에는 예제 패치를 적용합니다. 서비스 CRD 네 개와 공통 CRD 세 개를 먼저 설치하고 Helm에 --skip-crds를 전달해 기본 CRD와 확장 CRD의 충돌을 방지합니다. 이 패치는 HTTP passthrough나 inference target 전체를 구현하지 않습니다.

Argo Rollouts는 배포 후 분석에만 사용합니다. 이 실습에서는 Rollout 리소스나 트래픽 가중치를 만들지 않습니다.

설치가 끝나면 bash scripts/argo-admin.sh로 Argo CD URL과 초기 접속 정보를 확인합니다. EKS API와 관리용 ALB는 설정한 CIDR에서만 접근할 수 있습니다. ALB URL은 Argo CD 관리용이며, 뒤에서 호출할 Gateway URL과는 다릅니다. 실습에서는 자체 서명 인증서를 사용하므로 브라우저 접속 전에 인증서를 확인하고 신뢰하도록 설정해야 합니다.

3. Helm 차트로 Runtime과 Gateway 선언하기

Runtime 이미지 URI 설정

이미지를 ARM64로 빌드하고 ECR에 올립니다. 태그는 매번 고유하게 지정합니다.

bash scripts/build-agent.sh "blog-v1-$(date -u +%Y%m%dT%H%M%SZ)" blog-v1
cat .state/image-uri

이 명령은 테스트를 실행하고 BUILD_REVISION=blog-v1을 이미지에 넣어 빌드한 뒤 digest를 출력합니다. 아래 values는 첫 릴리스를 준비하기 위한 예시입니다. imageUri에는 .state/image-uri의 값을, roleArn에는 .state/outputs.json의 ExecutionRoleArn을 입력합니다. 예시의 blog-v1과 뒤의 화면에 표시된 gif-v4는 서로 다른 실습 릴리스 이름입니다.

runtime:
  imageUri: "123456789012.dkr.ecr.us-east-1.amazonaws.com/eks-ack-agentcore@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  roleArn: "arn:aws:iam::123456789012:role/AgentCoreRuntimeExecutionRole"
  region: us-east-1
  modelId: global.anthropic.claude-sonnet-5
  release: blog-v1
  buildRevision: blog-v1

release는 애플리케이션 환경변수로 전달하는 릴리스 이름입니다. buildRevision은 이미지에 포함된 빌드 식별자를 검증할 때 사용하는 기대값입니다. 두 필드는 AWS Runtime 버전 번호를 지정하지 않으며, Helm 차트의 appVersion도 AWS Runtime 버전과 별개입니다.

Runtime 템플릿은 이미지 값을 다음과 같이 AWS 리소스 선언에 연결합니다.

apiVersion: bedrockagentcorecontrol.services.k8s.aws/v1alpha1
kind: AgentRuntime
metadata:
  name: {{ .Values.runtime.name | replace "_" "-" }}
  annotations:
    argocd.argoproj.io/sync-wave: "0"
    services.k8s.aws/deletion-policy: delete
spec:
  agentRuntimeName: {{ .Values.runtime.name }}
  roleARN: {{ required "runtime.roleArn is required" .Values.runtime.roleArn | quote }}
  agentRuntimeArtifact:
    containerConfiguration:
      containerURI: {{ required "runtime.imageUri is required" .Values.runtime.imageUri | quote }}
  networkConfiguration:
    networkMode: PUBLIC
  protocolConfiguration:
    serverProtocol: HTTP
  environmentVariables:
    AWS_REGION: {{ .Values.runtime.region | quote }}
    MODEL_ID: {{ .Values.runtime.modelId | quote }}
    RELEASE_VERSION: {{ .Values.runtime.release | quote }}

배포할 이미지는 values의 runtime.imageUri에서 Runtime 선언의 containerURI로 전달되며, ACK가 UpdateAgentRuntime API를 호출해 반영합니다. Argo CD Application에 ECR 저장소를 별도 배포 대상으로 등록할 필요는 없습니다. ECR에 이미지만 푸시하면 Git의 값이 바뀌지 않으므로 재배포가 시작되지 않습니다.

Gateway 주소 유지와 DEFAULT 호출

Gateway는 authorizerType: AWS_IAM과 전용 실행 역할을 사용합니다. 이 HTTP 구성에서는 protocolType을 지정하지 않습니다. templates/gateway.yaml의 GatewayTarget 부분은 다음과 같습니다.

apiVersion: bedrockagentcorecontrol.services.k8s.aws/v1alpha1
kind: GatewayTarget
metadata:
  name: {{ .Values.gateway.name }}-{{ .Values.gateway.targetName }}
  annotations:
    argocd.argoproj.io/sync-wave: "2"
spec:
  name: {{ .Values.gateway.targetName }}
  gatewayIdentifierRef:
    from:
      name: {{ .Values.gateway.name }}
  targetConfiguration:
    http:
      agentcoreRuntime:
        arn: {{ required "gateway.runtimeArn is required" .Values.gateway.runtimeArn | quote }}
        qualifier: DEFAULT
  credentialProviderConfigurations:
    - credentialProviderType: GATEWAY_IAM_ROLE

클라이언트는 IAM SigV4로 Gateway 요청을 서명하고, Gateway는 자신의 IAM 역할로 Runtime을 호출합니다. 이름이 agent인 target의 호출 경로는 /agent/invocations입니다. 이 실습은 HTTP Runtime target을 사용하며 MCP 도구 목록을 제공하는 구성과는 구분됩니다.

Runtime을 업데이트하면 변경할 수 없는 새 버전이 생성되고, DEFAULT endpoint가 새 버전을 가리킵니다. GatewayTarget은 동일한 Runtime ARN과 DEFAULT를 계속 사용하므로 릴리스마다 클라이언트 URL을 바꿀 필요가 없습니다.

처음에는 Runtime만 생성하기

GatewayTarget에는 생성된 Runtime의 ARN이 필요합니다. 첫 배포에서는 다음 값을 환경 파일에 명시해 Runtime만 렌더링합니다. 저장소에 이전 환경의 값이 남아 있더라도 Gateway, 분석 Job 또는 예전 endpoint가 먼저 생성되지 않도록 합니다.

gateway:
  enabled: false
analysis:
  enabled: false
endpoint:
  enabled: false

다음 절에서 Application을 연결해 Runtime을 생성한 뒤 ARN과 ID를 확인합니다. 이후 아래 값을 입력하고 다시 Git에 반영하면 Gateway와 배포 후 검증이 활성화됩니다.

analysis.imageUri는 검증 Job의 이미지이며 배포할 에이전트 이미지는 runtime.imageUri입니다. 검증 코드가 바뀌지 않았다면 검증 이미지 digest는 유지할 수 있습니다.

Helm 차트에는 이름을 지정한 AgentRuntimeEndpoint를 생성하는 선택적 템플릿도 있습니다. endpoint.version은 해당 endpoint가 참조할 Runtime 버전이며, 이미지를 배포하는 필드는 아닙니다. 이 글의 Gateway는 DEFAULT를 사용하므로 endpoint.enabled: false를 유지합니다. endpoint.runtimeId는 검증기 입력으로도 사용하므로 별도 endpoint를 생성하지 않아도 입력해야 합니다.

4. Argo CD에 Git 저장소 연결하기

다음은 Application의 source와 동기화 정책입니다. valueFiles 경로는 차트 디렉터리를 기준으로 해석됩니다.

source:
  repoURL: ssh://git@github.com/YOUR_GITHUB_ORG/YOUR_REPOSITORY.git
  targetRevision: main
  path: containers/eks-ack-agentcore-gitops/charts/agentcore-agent
  helm:
    releaseName: devops-agent
    valueFiles:
      - ../../gitops/environments/dev.yaml
syncPolicy:
  automated:
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true
    - ServerSideApply=true

자신이 관리하는 비공개 Git 저장소에 코드를 준비하고 gitops/application.yaml과 gitops/project.yaml의 저장소 주소를 함께 바꿉니다. 위 path는 공개 샘플의 디렉터리 구조를 유지한 경우입니다. 샘플 폴더의 내용만 새 저장소 루트로 복사했다면 charts/agentcore-agent로 바꿉니다. configure-gitops.sh는 Git 루트에서 실제 차트까지의 경로와 저장소 주소가 맞는지 검사합니다.

첫 Runtime의 이미지와 실행 역할, 비활성화 설정을 gitops/environments/dev.yaml에 입력합니다. 이 파일과 두 manifest를 검토해 자신의 저장소에 커밋하고 푸시한 뒤 아래 스크립트로 연결합니다.

export GITHUB_REPOSITORY=YOUR_GITHUB_ORG/YOUR_REPOSITORY
bash scripts/configure-gitops.sh
kubectl --context eks-ack-agentcore -n argocd get application devops-agent
kubectl --context eks-ack-agentcore -n agentcore get agentruntimes -o yaml

Runtime 상태가 READY가 되면 status.agentRuntimeID와 status.ackResourceMetadata.arn을 읽습니다. 앞 절의 표에 따라 Gateway와 분석 설정을 채우고, runtime.buildRevision이 이미지의 빌드 식별자와 일치하는지 확인한 다음 두 번째 변경을 Git에 반영합니다. Argo CD가 Gateway와 GatewayTarget을 순서대로 생성합니다.

스크립트는 지정한 저장소 하나에 대한 읽기 전용 deploy key를 Argo CD에 설정합니다. Argo CD는 Helm으로 템플릿을 렌더링하고 리소스의 수명주기를 직접 관리합니다. 따라서 에이전트 애플리케이션은 helm list에 별도 Helm release로 표시되지 않을 수 있습니다. 자세한 내용은 Argo CD의 Helm 사용 방식에서 확인할 수 있습니다.

5. 새 릴리스 배포와 실제 호출 검증하기

그림 2. Git의 이미지 digest 변경부터 PostSync 호출 검증까지의 순서입니다. 이미지 빌드는 제공된 스크립트로 수행하며 CI에도 연결할 수 있습니다. 지속 트래픽 검증은 PostSync Job과 별도로 실행합니다.

새 릴리스를 배포하려면 이미지를 빌드한 뒤 gitops/environments/dev.yaml의 runtime.imageUri, runtime.release, runtime.buildRevision을 변경합니다. Pull request 리뷰와 병합은 기존 팀 절차에 맞춰 진행합니다. Argo CD는 Runtime의 sync wave 0, Gateway의 wave 1, GatewayTarget의 wave 2 순서로 동기화합니다.

bash scripts/build-agent.sh "blog-v2-$(date -u +%Y%m%dT%H%M%SZ)" blog-v2
cat .state/image-uri

새 digest를 runtime.imageUri에 넣고 runtime.release와 runtime.buildRevision을 blog-v2로 변경합니다. 배포할 이미지와 검증할 기대값을 같은 Git 변경에 포함해야 합니다. 이미지 빌드만으로 배포가 시작되지는 않습니다.

배포 후 AnalysisRun 템플릿의 PostSync hook이 실행됩니다. 다음은 hook과 Job 정의의 일부입니다.

apiVersion: argoproj.io/v1alpha1
kind: AnalysisRun
metadata:
  name: {{ .Release.Name }}-gateway-check
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  metrics:
    - name: gateway-runtime-inference
      count: 1
      failureLimit: 0
      provider:
        job:
          spec:
            backoffLimit: 1
            activeDeadlineSeconds: 660
            template:
              spec:
                serviceAccountName: gateway-check
                automountServiceAccountToken: false
                restartPolicy: Never
                nodeSelector:
                  kubernetes.io/arch: arm64

전체 템플릿은 검증 컨테이너에 예상 이미지, 릴리스와 빌드 식별자를 전달합니다. Job은 전용 Pod Identity로 Runtime과 DEFAULT의 준비 상태 및 이미지 digest를 확인하고, 새 session ID로 Gateway에 요청을 보냅니다. 반환된 JSON의 release와 build_revision을 기대값과 대조하고 모델 응답이 비어 있지 않은지 확인합니다.

에이전트는 deployment_info 도구로 릴리스 정보를 제공하며, 모델에는 짧은 답변을 요청합니다. agent/main.py에서 모델을 설정하는 부분은 다음과 같습니다.

model_id = os.getenv("MODEL_ID", "global.anthropic.claude-sonnet-5")
model = BedrockModel(
    model_id=model_id,
    region_name=os.getenv("AWS_REGION", "us-east-1"),
    max_tokens=512,
)

이 예제는 temperature를 별도로 설정하지 않습니다. Runtime SDK가 /ping과 /invocations 경로를 제공하며, 에이전트는 JSON 응답을 반환합니다.

kubectl --context eks-ack-agentcore -n argocd get application devops-agent
kubectl --context eks-ack-agentcore -n agentcore get agentruntimes,gateways,gatewaytargets
kubectl --context eks-ack-agentcore -n agentcore get analysisruns,jobs,pods
bash scripts/invoke-gateway.sh

Synced는 Application에서 렌더링한 선언과 클러스터의 리소스가 일치한다는 뜻입니다. 사용자 정의 health check의 Healthy는 리소스가 준비됐다는 뜻입니다. AnalysisRun이 Successful이고 Argo CD 동기화 작업이 Succeeded인지 확인한 뒤, 별도 호출에서도 예상한 릴리스가 응답하는지 점검합니다.

curl로 API 응답의 릴리스 전환 확인

배포 전에 다음 명령을 실행해 두고, 다른 터미널에서 새 이미지 digest와 릴리스 값을 Git에 반영합니다. 이 명령 자체는 리소스를 배포하지 않습니다.

bash scripts/watch-gateway-curl.sh --session-mode both --count 60 --interval 3

도구는 AWS CLI의 default 프로파일로 Gateway 주소를 조회하고 실제 curl 요청을 보냅니다. both 모드는 같은 session ID를 유지하는 요청과 매번 새 session ID를 만드는 요청을 교대로 보냅니다. 기존 세션의 유지 여부를 보려면 첫 요청을 새 버전 배포 전에 보내야 합니다.

출력은 요청당 JSON 한 줄입니다. lane으로 기존 세션과 신규 세션을 구분하고, release와 build_revision으로 응답한 릴리스를 확인합니다. 같은 종류의 요청에서 두 값 중 하나가 직전 성공 응답과 달라지면 changed: true가 표시됩니다. release는 앱의 릴리스 이름이며 AWS Runtime의 숫자 버전과는 별개입니다.

자격 증명은 매 요청 전에 AWS CLI에서 다시 가져와 curl의 표준입력으로 전달합니다. 키와 토큰을 명령줄 인자나 로그 파일에 넣지 않습니다. HTTP 오류와 응답 해석 실패도 기록하면서 관찰을 계속하며, 실패가 한 번이라도 있으면 마지막 종료 코드는 1입니다. 요청은 기본 60건 또는 300초에서 끝나고, 각 호출에는 모델 사용 비용이 발생합니다.

이 도구의 both 모드는 순차 호출입니다. 동시 요청이나 배포 구간별 성공률 측정에는 지속 요청 프로브를 사용합니다. curl 관찰 옵션은 bash scripts/watch-gateway-curl.sh --help로 확인합니다.

DEFAULT는 PostSync 검증 전에 새 버전으로 전환됩니다. 검증이 실패하면 Argo CD가 동기화 작업의 실패를 표시하지만, Runtime을 자동으로 이전 상태로 복구하지는 않습니다. 이전 이미지 digest와 해당 릴리스의 release 및 buildRevision을 Git에 복원하면 이전 코드를 새 Runtime 버전으로 재배포할 수 있습니다. 신규 요청이 새 버전에 도달하기 전에 검증하려면 별도 endpoint에서 검증한 뒤 호출 대상을 전환하는 절차가 필요합니다. 단계적인 트래픽 전환도 별도로 설계해야 합니다.

6. Argo CD 화면에서 배포 확인하기

이 절의 화면은 고정된 Git 커밋의 Helm 차트에 Application의 helm.valuesObject로 배포 값을 전달한 결과입니다. 따라서 화면에 표시된 Git 커밋은 바뀌지 않습니다. 이 화면은 Runtime 갱신과 PostSync 검증의 상태 변화를 보여주며, Git 커밋 변경을 감지하는 과정까지 입증하는 자료는 아닙니다. 1~5장의 Git 기반 절차를 적용할 때는 필요한 값을 환경별 values 파일에 커밋하고 푸시한 뒤 valuesObject 설정을 제거해야 합니다. valuesObject가 남아 있으면 같은 키의 valueFiles 값보다 우선하므로 Git 파일을 수정해도 해당 값이 반영되지 않을 수 있습니다.

Argo CD의 Applications에서 devops-agent를 열면 Runtime, Gateway, GatewayTarget과 검증용 AnalysisRun이 표시됩니다. 에이전트는 AgentCore Runtime에서 실행하므로 이 화면에서는 Runtime의 상태와 PostSync 검증 결과를 순서대로 확인합니다.

다음 화면은 Runtime v3에서 v4로 업데이트되는 동안의 Argo CD 상태입니다.

Runtime 갱신 상태 확인

그림 3. Runtime 갱신 중인 화면입니다. 위쪽 SYNC STATUS는 Synced이지만 APP HEALTH는 Progressing입니다. Kubernetes 선언은 적용됐으며, ACK가 AWS 리소스의 준비 상태를 확인하는 중입니다.

오른쪽 LAST SYNC에는 waiting for healthy state ... AgentRuntime 메시지가 표시됩니다. 이 상태가 오래 지속되면 Runtime 리소스의 status.conditions와 ACK 컨트롤러 로그를 확인합니다.

PostSync 호출 검증

그림 4. Runtime이 준비된 뒤 새 AnalysisRun이 실행됩니다. APP HEALTH는 Healthy로 바뀌었지만 LAST SYNC는 아직 Syncing입니다.

이 Job은 Gateway를 거쳐 모델을 호출하므로 Runtime의 READY 상태만으로 확인할 수 없는 IAM 권한이나 호출 경로 문제도 점검할 수 있습니다. 예상 이미지 digest, 릴리스와 빌드 식별자를 대조하며, 검증이 실패하면 Argo CD의 동기화 작업도 실패로 표시됩니다.

동기화 성공과 새 릴리스 확인하기

그림 5. 새 AnalysisRun이 성공한 뒤의 화면입니다. Runtime과 Gateway의 이름은 그대로이고 AnalysisRun의 생성 시각이 바뀌었습니다.

별도 Gateway 호출에서도 다음 식별자를 확인했습니다. 아래 JSON은 응답의 식별 필드만 발췌한 것이며, 모델 응답 본문이 비어 있지 않은지도 검사했습니다.

{
  "runtime_version": "4",
  "release": "gif-v4",
  "build_revision": "argocd-gif-v4",
  "model_id": "global.anthropic.claude-sonnet-5"
}

다음은 배포 과정에서 PostSync 검증이 진행 중인 화면입니다.

그림 6. APP HEALTH는 Healthy, SYNC STATUS는 Synced이며 LAST SYNC는 Syncing으로 표시된 검증 진행 화면입니다. 검증이 완료된 Sync OK 상태는 그림 5에서 확인할 수 있습니다. 6장 첫머리에서 설명한 valuesObject 적용 예시입니다.

배포 전후 요청 처리 결과

배포 중에도 같은 Gateway URL로 트래픽을 계속 보냈습니다. 기존 세션은 이전 버전으로 응답했고, 새 세션은 새 Runtime 버전으로 전환됐습니다.

그림 7. 배포 중 세션별 응답 버전과 요청 지연입니다. 파란 원은 v3 응답, 주황 사각형은 v4 응답을 나타냅니다. 위쪽 선분은 각 요청의 처리 구간이고 아래쪽 점은 응답 지연입니다. 회색 영역은 배포 진행 구간이며 서비스 중단 구간을 뜻하지 않습니다.

데모의 지속 요청 프로브에서 요청 94건이 모두 정상 처리됐습니다. 측정 구간에서는 Gateway URL 변경이나 요청 실패 없이 새 Runtime 버전으로 전환됐습니다. 이 결과는 해당 데모의 요청 수와 부하 조건에서 확인한 결과입니다. 운영 환경에서는 실제 동시 요청 수, 세션 유지 시간, 응답 지연과 실패율을 기준으로 추가 검증해야 합니다.

리소스 정리

AgentCore 리소스와 ALB가 남은 상태에서 EKS나 IAM 역할을 먼저 삭제하면 컨트롤러가 정리를 완료할 수 없습니다. 정리 스크립트는 Argo CD의 재생성을 멈춘 뒤 GatewayTarget, Gateway, 별도 endpoint, Runtime, Ingress 순서로 제거하고 컨트롤러와 CDK 기반 리소스를 삭제합니다.

CONFIRM_DESTROY=eks-ack-agentcore bash scripts/destroy.sh

정리 스크립트는 stack/cluster 태그와 Argo CD tracking ID로 소유권을 확인한 리소스만 삭제합니다. EKS 기반 스택까지 제거하므로 전용 데모 환경에서 사용해야 합니다. ECR 저장소는 보존되며, 삭제한 환경의 로컬 상태는 별도 폴더로 이동합니다. 남은 로그와 이미지, GitHub deploy key를 확인하고 조직의 보안 자동화가 생성한 네트워크 리소스도 점검해야 합니다. 샘플 코드의 ECR 수명주기 정책은 태그 없는 이미지만 대상으로 하므로 릴리스 태그가 있는 이미지는 별도로 정리해야 합니다.

결론

이 글에서는 EKS의 Argo CD와 ACK를 사용해 AgentCore Runtime과 Gateway를 관리하는 배포 파이프라인을 구성했습니다. 개발자는 이미지와 Helm values를 Git에 반영하고, 플랫폼 팀은 Argo CD의 리소스 상태와 PostSync 호출 결과로 배포를 확인합니다. 데모에서는 Gateway 주소를 유지한 상태에서 기존 세션은 이전 버전으로 응답하고 신규 세션은 새 버전으로 전환됐으며, 측정한 요청 94건은 모두 성공했습니다. 다만 DEFAULT는 PostSync 검증 전에 전환되고 자동 rollback은 구현하지 않았습니다. 운영에 적용할 때는 서비스의 부하 조건을 검증하고, 필요에 따라 별도 endpoint를 이용한 사전 검증과 승인 후 전환, 복구 절차를 추가해야 합니다.