콘텐츠로 이동

OpenAPI를 통해 AWS 클라우드 계정 연동

OpenAPI를 통해 AWS 계정의 역할 권한 부여 구성을 생성하고, IAM 신뢰 관계를 구성하며, 권한 부여를 검증하고 저장할 수 있습니다. 다중 계정 시나리오에서는 각 AWS 계정에 대해 동일한 절차를 반복 수행할 수 있습니다.

사전 준비

  • OpenAPI 사이트 목록에서 워크스페이스가 위치한 사이트의 Endpoint를 선택합니다.
  • 해당 워크스페이스의 API Key를 준비합니다. 생성, 조회, 수정 및 삭제에는 클라우드 계정 관리 권한 cloudAccount.accountManage가 필요합니다.이 네 가지 API는 무료 플랜 워크스페이스에서 사용할 수 없습니다.
  • 고객 AWS 계정의 12자리 계정 ID, 파티션 및 대상 IAM Role 이름을 준비합니다. 예시에서는 국제 리전(area=intl, 파티션 aws) 및 collection/CloudCollection을 사용합니다. 중국 리전에서는 area=cn을 사용하며 파티션은 aws-cn입니다.
  • 실행 프로그램이 고객의 권한 부여를 받았으며 대상 AWS 계정에서 Role을 생성하고 수집에 필요한 권한을 추가할 수 있는지 확인합니다. AWS CLI 예시에서는 현재 AWS 자격 증명이 해당 계정 내의 권한 부여된 자격 증명으로 구성되어 있다고 가정합니다.

다음 예시에서는 환경 변수 API_BASE와 DF_API_KEY를 사용하며, 각각 Endpoint(끝에 슬래시 없음)와 보안 저장소에서 로드한 워크스페이스 API Key를 나타냅니다.

1. 클라우드 계정 구성 생성

AWS Role 클라우드 계정 생성을 호출합니다. config.accountId에는 고객 자신의 AWS 계정 ID를 입력합니다. 역할 경로와 이름은 다음 단계에서 실제로 생성하는 Role과 일치해야 합니다.

curl -sS -X POST "$API_BASE/api/v1/cloud_account/do/add" \
  -H "DF-API-KEY: $DF_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"provider":"aws","config":{"authType":"assume_role","area":"intl","accountId":"123456789012","roleName":"collection/CloudCollection","accountName":"AWS collection"}}'

content.creationResult.status가 created인 경우 다음 필드의 실제 반환 값을 저장합니다.

필드 용도
content.uuid 이후 조회, 검증, 수정 및 삭제를 위한 클라우드 계정 식별자
content.externalId Guance가 현재 구성에 대해 생성한 External ID
content.platformAccountId IAM 신뢰 정책의 Guance 플랫폼 AWS 계정 ID

구성 생성과 권한 부여 검증은 각각 결과를 반환합니다. 최초 호출 시 Role이 아직 생성되지 않았을 수 있으며, 이때 creationResult.status=created와 validationResult.status=failed를 동시에 얻을 수 있습니다. 저장한 UUID와 External ID를 그대로 사용하여 AWS 구성을 계속 진행합니다.

2. IAM Role 생성 및 신뢰 정책 구성

고객 AWS 계정에서 Role을 생성합니다. 다음 JSON을 trust-policy.json으로 저장하고 파티션, 플랫폼 AWS 계정 ID 및 External ID를 교체합니다. 신뢰 정책의 계정 ID에는 이전 단계에서 반환된 platformAccountId를 사용합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:<partition>:iam::<platformAccountId>:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<externalId>"
        }
      }
    }
  ]
}

AWS 콘솔, AWS CLI 또는 배포 템플릿을 사용하여 구성을 완료할 수 있습니다. AWS CLI를 사용하는 경우 collection/CloudCollection은 Role 이름 CloudCollection 및 IAM 경로 /collection/에 해당합니다.

aws iam create-role \
  --role-name CloudCollection \
  --path /collection/ \
  --assume-role-policy-document file://trust-policy.json

aws iam put-role-policy \
  --role-name CloudCollection \
  --policy-name CloudCollectionRead \
  --policy-document file://collection-policy.json

collection-policy.json은 고객의 승인을 거친 수집 권한 정책입니다. AWS 클라우드 통합 역할 권한 부여 구성의 수집 권한 JSON을 참고하고, 실제 수집하는 서비스에 맞게 구성합니다. 신뢰 정책은 누가 Role을 수임할 수 있는지 제어하고, 권한 정책은 Role을 수임한 후 액세스할 수 있는 AWS 리소스를 제어합니다.

일괄 연동 시 각 AWS 계정에 대해 해당 계정의 UUID, 파티션, 역할 경로 및 External ID를 유지 관리합니다. 배포 템플릿을 재사용할 때는 각 레코드에 해당 값을 주입합니다. 동일한 이름의 Role이 이미 존재하는 경우 먼저 계정, 경로 및 해당 Role의 용도를 확인한 후 고객의 IAM 변경 절차에 따라 신뢰 및 수집 권한을 업데이트합니다.

3. 권한 부여 검증 및 저장

CLOUD_ACCOUNT_UUID를 생성 시 반환된 UUID로 설정하고 AWS Role 클라우드 계정 수정 또는 검증을 호출합니다.

curl -sS -X POST "$API_BASE/api/v1/cloud_account/$CLOUD_ACCOUNT_UUID/do/modify" \
  -H "DF-API-KEY: $DF_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"config":{},"dryRun":true}'

dryRun=true는 검증만 수행하며 content.saved=false는 예상된 결과입니다. content.validationResult.status를 읽습니다. 결과가 passed이면 동일한 URL로 {"config":{},"dryRun":false}를 제출합니다. 정식 저장은 다시 검증하며, 이번 응답이 content.saved=true와 content.validationResult.status=passed를 동시에 충족해야만 권한 부여 구성이 성공적으로 검증되고 저장되었음을 의미합니다.

검증에 실패하면 파티션, 역할 경로, 플랫폼 계정 및 External ID를 확인합니다. 신뢰 정책은 External ID가 없거나 잘못된 External ID가 포함된 수임 요청을 거부해야 합니다. IAM 구성이 방금 업데이트된 경우 동일한 UUID로 제한된 횟수의 백오프 재시도를 수행할 수 있습니다. STS 검증이 통과한 후 필요에 따라 클라우드 통합 수집기를 구성하고 실제 수집 권한을 검증합니다.

4. 구성 조회, 복구 또는 수정

AWS Role 클라우드 계정 조회를 사용하여 uuid로 정확히 조회하거나 accountId로 페이지를 나누어 필터링합니다. 목록 항목은 content.data에 있고, 페이지 정보는 응답 최상위의 pageInfo에 있습니다.

curl -sS --get "$API_BASE/api/v1/cloud_account/do/list" \
  -H "DF-API-KEY: $DF_API_KEY" \
  --data-urlencode "uuid=$CLOUD_ACCOUNT_UUID"

생성 응답이 유실된 경우 먼저 기존 레코드를 조회합니다. AWS 계정 ID만 알고 있는 경우 accountId는 부분 일치 필터 조건이므로 페이지별로 content.data[].config.accountId를 정확히 대조해야 합니다. 중복 생성 시 ft.CloudAccountAKRepeat가 반환되면 content.existingCloudAccountUUIDs를 사용하여 레코드를 찾을 수 있습니다. 복구 후에는 config.externalId와 해당 레코드의 platformAccountId를 계속 사용합니다. 플랫폼 권한 부여 상태가 unavailable이면 해당 브랜드 및 파티션의 플랫폼 구성이 복구될 때까지 기다린 후 플랫폼 계정 ID를 조회합니다.

생성 시 기존 자격 증명 충돌 ft.CloudAccountLegacyCredentialsConflict가 발생하면 먼저 반환된 기존 레코드 UUID를 확인하고, 연결된 수집기를 평가한 후 원래 구성을 처리합니다. 수정 API는 별칭, Role 이름 및 태그를 지원합니다. 계정 ID, 파티션, 인증 유형 및 External ID는 기존 레코드에 의해 결정됩니다. 태그 업데이트 시 extraTags를 생략하면 기존 값이 유지되고, []를 전달하면 비워집니다. 기존 수집기는 정식 저장 시 다시 동기화될 수 있습니다.

5. 구성 삭제 또는 임시 자격 증명 조회

연동을 비활성화할 때는 대상 UUID와 연결된 수집기를 확인한 후 AWS Role 클라우드 계정 삭제에 {}를 전송합니다. 삭제하면 플랫폼 구성과 연결된 수집기, 작업이 정리됩니다. 고객 AWS 측 Role은 고객이 관리하며, 과거 관측 데이터는 보존됩니다. 프라이빗 Func를 사용하는 경우 언인스톨 작업이 완료되었는지도 확인해야 합니다. 이후 다시 생성하면 새로운 UUID와 External ID가 발급되므로 새 값에 맞게 IAM 신뢰 정책을 구성해야 합니다.

애플리케이션에서 임시 자격 증명이 필요한 경우 cloudAccount.temporaryCredentialsRead 권한이 있는 API Key를 사용하여 AWS 임시 자격 증명 가져오기를 호출합니다. API는 매번 저장된 권한 부여를 실시간으로 검증하고 유효 기간이 있는 자격 증명을 반환합니다. 자격 증명의 유효 기간에 맞게 사용하고 자격 증명을 로그에 기록하지 않도록 합니다.

문서 평가

이 페이지가 도움이 되었나요?