데이터 스토어에 대한 IAM 인증 구성하기

데이터 스토어에 대한 IAM 인증 구성하기

PostgreSQL과 Redis 인증을 위해 Agent Server가 클라우드 워크로드 아이덴티티를 사용하도록 구성해요.

Agent Server는 클라우드 워크로드 아이덴티티를 사용해 런타임에 단기 수명의 PostgreSQL 및 Redis 자격 증명을 생성할 수 있어요. 이렇게 하면 배포 구성에서 정적 데이터베이스 및 캐시 암호를 제거하게 돼요. 연결 및 풀링 동작은 동일하게 유지돼요.

데이터 스토어 IAM 인증에는 langgraph-api>=0.12.0이 필요해요.

출처: 문서

본문

지원되는 서비스

GCP PostgreSQL 프로바이더는 Cloud SQL을 지원해요. 다른 토큰 범위가 필요한 AlloyDB는 지원하지 않아요.

프로바이더 설정은 인증만 제어해요. Agent Server를 시작하기 전에 네트워크 액세스, TLS, 데이터베이스 사용자, 캐시 사용자 및 프로바이더 권한을 구성하세요.

IAM 인증 활성화하기

IAM 인증을 활성화하려면:

1. 매니지드 데이터 스토어에서 IAM 또는 아이덴티티 기반 인증을 활성화하세요.

2. 데이터베이스 또는 캐시 프린시펄을 만들고 Agent Server가 필요로 하는 권한만 부여하세요.

3. 모든 Agent Server API 및 큐 프로세스에 워크로드 아이덴티티 자격 증명을 제공하세요.

4. 프린시펄 이름을 포함하지만 정적 암호는 없는 연결 URI를 설정하세요.

5. 해당하는 프로바이더 선택자를 aws, azure 또는 gcp로 설정하세요:

   AGENT_POSTGRES_IAM_AUTH_PROVIDER=<provider>
   AGENT_REDIS_IAM_AUTH_PROVIDER=<provider>
   

PostgreSQL, Redis 또는 둘 모두에 대해 IAM 인증을 활성화할 수 있어요. 선택자가 설정되지 않으면 Agent Server는 해당 데이터 스토어의 연결 URI에서 암호를 계속 사용해요.

배포 유형에 따라 다음과 같은 연결 URI 변수를 사용하세요:

연결 URI는 다음 요구 사항을 충족해야 해요:

• 전송 보안: PostgreSQL에는 sslmode=require 또는 더 엄격한 검증 모드를, Redis에는 rediss://를 사용하세요.
• 문자 인코딩: 사용자 이름의 URI 예약 문자를 퍼센트 인코딩하세요 (예: @ → %40).
• 프라이빗 인증 기관: Redis TLS가 프라이빗 인증 기관을 사용한다면 REDIS_TLS_CA_CERT를 base64로 인코딩된 PEM CA 번들로 설정하세요.
• 클러스터 모드: Redis 서비스가 클러스터 모드를 사용한다면 REDIS_CLUSTER=true도 설정하세요.

AWS 구성하기

Agent Server는 AWS SDK 기본 자격 증명 체인을 사용해 RDS 인증 토큰과 ElastiCache SigV4 인증 토큰을 생성해요.

Agent Server를 구성하기 전에:

• RDS 또는 Aurora PostgreSQL에 대해 IAM 데이터베이스 인증을 활성화하세요. 데이터베이스 사용자에게 rds_iam 역할을 부여하고, 워크로드 아이덴티티에 해당 사용자에 대한 rds-db:connect를 부여하세요.
• ElastiCache 사용자에 대해 IAM 인증을 활성화하세요. ElastiCache 캐시 또는 복제 그룹과 ElastiCache 사용자 모두에 워크로드 아이덴티티에 elasticache:Connect를 부여하세요.
• EKS Pod Identity, IRSA(서비스 계정용 IAM 역할), 인스턴스 프로파일 또는 다른 AWS SDK 자격 증명 소스를 통해 AWS 자격 증명을 구성하세요. AWS_REGION 또는 AWS_DEFAULT_REGION을 데이터 스토어의 리전으로 설정하세요.

연결 URI에 데이터베이스 사용자 이름을 설정하세요:

AWS_REGION=<region>
AGENT_POSTGRES_IAM_AUTH_PROVIDER=aws
AGENT_REDIS_IAM_AUTH_PROVIDER=aws
DATABASE_URI="postgresql://<rds-user>@<rds-endpoint>:5432/<database>?sslmode=require"
REDIS_URI="rediss://<elasticache-iam-user>@<elasticache-endpoint>:6379"

Redis 사용자 이름은 IAM이 활성화된 ElastiCache 사용자와 일치해야 해요. Agent Server는 프로비저닝된 ElastiCache 캐시 클러스터와 복제 그룹을 지원해요. ElastiCache IAM 인증에는 전송 중 암호화와 Valkey 7.2 이상 또는 Redis OSS 7.0 이상이 필요해요.

Azure 구성하기

Agent Server는 DefaultAzureCredential을 사용해 PostgreSQL과 Redis에 대한 Microsoft Entra 토큰을 획득해요. 자격 증명 체인은 Azure Workload Identity, 관리 ID 및 서비스 프린시펄을 지원해요.

Agent Server를 구성하기 전에:

• Azure Database for PostgreSQL Flexible Server에 대해 Microsoft Entra 인증을 구성하세요. 관리 ID 또는 서비스 프린시펄에 대한 데이터베이스 역할을 만드세요. 그 역할 이름을 PostgreSQL URI 사용자 이름으로 사용하세요.
• Azure Managed Redis에 대해 Microsoft Entra 인증과 데이터 액세스 정책을 구성하세요. 관리 ID 또는 서비스 프린시펄 객체 ID를 Redis URI 사용자 이름으로 사용하세요.
• 각 Agent Server 워크로드에 Azure Workload Identity, 관리 ID 또는 다른 DefaultAzureCredential 소스를 구성하세요.

연결 URI에 Microsoft Entra 프린시펄 식별자를 설정하세요:

AGENT_POSTGRES_IAM_AUTH_PROVIDER=azure
AGENT_REDIS_IAM_AUTH_PROVIDER=azure
DATABASE_URI="postgresql://<entra-principal-name>@<postgres-host>:5432/<database>?sslmode=require"
REDIS_URI="rediss://<entra-object-id>@<redis-host>:<port>"

Azure Managed Redis를 클러스터 모드로 사용할 때는 REDIS_CLUSTER=true를 설정하세요. Agent Server는 토큰 만료 전에 Microsoft Entra 토큰을 갱신하고 열린 Redis 연결을 재인증해요.

GCP 구성하기

Agent Server는 Google ADC를 사용해 Cloud SQL 로그인 토큰과 Memorystore 액세스 토큰을 획득해요. ADC는 GKE Workload Identity Federation, 연결된 서비스 계정, 서비스 계정 가장(impersonation) 및 GOOGLE_APPLICATION_CREDENTIALS를 지원해요.

Agent Server를 구성하기 전에:

• Cloud SQL IAM 데이터베이스 인증을 구성하고 IAM 프린시펄을 데이터베이스 사용자로 추가한 뒤 roles/cloudsql.instanceUser를 부여하세요. 데이터베이스 권한은 별도로 부여하세요.
• Memorystore IAM 인증을 구성하고 워크로드 아이덴티티에 roles/redis.dbConnectionUser를 부여하세요.
• 각 Agent Server 워크로드에 대해 ADC를 구성하세요. 서비스 계정 키보다 Workload Identity Federation 또는 연결된 서비스 계정을 권장해요.

PostgreSQL URI에 Cloud SQL IAM 데이터베이스 사용자를 설정하세요. Memorystore는 default Redis 사용자 이름만 지원해요:

AGENT_POSTGRES_IAM_AUTH_PROVIDER=gcp
AGENT_REDIS_IAM_AUTH_PROVIDER=gcp
DATABASE_URI="postgresql://<cloud-sql-iam-user>@<cloud-sql-host>:5432/<database>?sslmode=require"
REDIS_URI="rediss://default@<memorystore-discovery-endpoint>:<port>"
REDIS_CLUSTER=true

서비스 계정의 경우, Cloud SQL 데이터베이스 사용자 이름은 .gserviceaccount.com 접미사를 뺀 이메일 주소예요.

독립 실행형 Helm 차트 구성하기

Kubernetes의 독립 실행형 Agent Server 배포의 경우 모든 Agent Server 워크로드에 프로바이더 선택자를 설정하세요. 별도의 큐 배포가 활성화되어 있다면 API와 큐 배포를 동일한 아이덴티티와 환경 변수로 구성하세요.

다음 예시는 두 데이터 스토어 모두에 AWS를 사용해요. 다른 클라우드 프로바이더를 사용할 때는 각 프로바이더 값을 azure 또는 gcp로 설정하세요:

postgres:
  external:
    enabled: true
    connectionUrl: "postgresql://<database-user>@<postgres-host>:5432/<database>?sslmode=require"
redis:
  external:
    enabled: true
    connectionUrl: "rediss://<redis-user>@<redis-host>:<port>"

apiServer:
  deployment:
    extraEnv:
      - name: AGENT_POSTGRES_IAM_AUTH_PROVIDER
        value: "aws"
      - name: AGENT_REDIS_IAM_AUTH_PROVIDER
        value: "aws"

queue:
  enabled: true
  deployment:
    extraEnv:
      - name: AGENT_POSTGRES_IAM_AUTH_PROVIDER
        value: "aws"
      - name: AGENT_REDIS_IAM_AUTH_PROVIDER
        value: "aws"

apiServer.serviceAccount와 queue.serviceAccount를 클라우드 프로바이더의 워크로드 아이덴티티 메커니즘으로 구성하세요. 두 워크로드 모두 자격 증명을 획득하고 데이터 스토어에 연결할 수 있어야 해요.

더 알아보기 (Learn more)

• 독립 실행형 서버 셀프 호스팅
• 셀프 호스팅 Agent Server 환경 변수
• 셀프 호스팅 플랫폼 기능
• 확장을 위한 Agent Server 구성