AWS Role 클라우드 계정 생성¶
POST /api/v1/cloud_account/do/add
개요¶
현재 워크스페이스의 AWS assume_role 구성을 생성하고 독립적인 External ID를 생성합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 API Key를 사용합니다. 관리 4개 진입점은 cloudAccount.accountManage 권한이 필요하며 무료 플랜에서는 명시적으로 거부됩니다. 계정 범위는 Key가 속한 워크스페이스에서 가져옵니다. 임시 자격 증명 읽기에는 별도로 cloudAccount.temporaryCredentialsRead가 필요하며, 관리 권한에 자동으로 포함되지 않습니다. 플랫폼 권한 부여는 현재 워크스페이스의 브랜드와 cn/intl 파티션에 따라 선택되며 다른 브랜드로 폴백하지 않습니다. 모든 응답에는 Cache-Control: no-store, Pragma: no-cache가 포함됩니다.
먼저 구성을 생성하고 uuid/externalId/platformAccountId를 저장한 다음, 권한이 있는 고객 관리자 또는 자동화를 통해 AWS에서 Role과 권한 정책을 생성하고, 플랫폼 계정을 신뢰하며 반환된 고유 External ID를 요구하도록 설정합니다. cn은 aws-cn 파티션을, intl은 aws를 사용합니다. roleName은 IAM Role의 실제 경로와 같아야 합니다. 최초에 Role을 생성하지 않은 경우 validationResult는 failed일 수 있지만 creationResult는 여전히 created이며, 동일한 레코드를 계속 사용하여 신뢰를 완료한 다음 modify dryRun=true로 검증하고 마지막으로 false로 저장합니다. 반복 생성으로 External ID를 교체할 수 없습니다. 전체 단계는 OpenAPI를 통한 AWS 클라우드 계정 연동을 참고하고, 사이트 Endpoint는 OpenAPI 사이트 목록을 참고하세요.
권한 부여 컨텍스트는 자동 생성되며 dryRun/externalId/authorizationContext 또는 고객 AK/SK를 받지 않습니다. 생성 시 먼저 동일 계정의 기존 accessKey/role 충돌을 확인한 다음 Account ID 기준으로 중복을 판단합니다(이름 기준 아님). 퍼지 목록에서 한 건이 조회되지 않았다고 해서 생성되지 않았다고 추론해서는 안 됩니다. 검증은 올바른 External ID 1회의 긍정 탐지와 누락/오류 External ID 2회의 부정 탐지를 포함하며, 부정 탐지는 모두 명확히 거부되어야 합니다. 검증에 통과하지 못해도 isAvailable=false로 정상 저장할 수 있으며, 이는 AWS 리소스가 생성되었거나 수집 서비스 권한이 완전하다는 것을 의미하지 않습니다.
타임아웃/5xx 발생 후에는 먼저 list를 페이지 단위로 조회하여 config.accountId, area를 정확히 대조하거나, 충돌 응답으로 반환된 existingCloudAccountUUIDs를 사용해 레코드를 복구합니다. 구성 저장이 확인되지 않은 경우 권한 부여 필드는 null입니다. 제출 이후 단계에서 오류가 발생하면 작업 오류가 함께 표시될 수 있지만 creationResult.status=created일 수 있으므로 반드시 다시 읽어 확인해야 합니다.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| config | object | Y | 생성 시 필수 전체 구성입니다. 수정 시 객체가 필수이며, {}는 기존 구성을 유지하지만 여전히 검증하며 dryRun=false이면 기존 수집 스크립트를 다시 동기화할 수 있습니다. externalId/브랜드/워크스페이스/장기 자격 증명 등 공개되지 않은 필드를 추가해서는 안 됩니다. null 허용: False 예: {}가져오기 또는 입력 방법: 고객 AWS 계정/IAM 역할 정보와 아래 필드로 구성합니다. |
| config.accountId | string | Y | 생성 시 필수이며 비즈니스 요구사항상 정확히 12자리 숫자인 문자열입니다. 플랫폼 계정 ID/이메일/Role ARN이 아닙니다. 수정 시 계정 변경은 허용되지 않습니다. 목록의 동명 Query는 퍼지 필터이므로 혼동하지 마세요. 빈 문자열 허용: True null 허용: False 예: 123456789012가져오기 또는 입력 방법: 고객 AWS 콘솔 계정 정보에서 12자리 Account ID를 가져오며 앞의 0을 유지합니다. |
| config.accountName | string | Y | 생성 시 필수이며 비어 있지 않은 문자열입니다. 수정 시 생략하면 유지되며, 빈 문자열은 비즈니스 검증에서 거부됩니다. 최대 256 가중 문자입니다. AWS 로그인 사용자 이름 또는 고유 Account ID가 아니며 복구 고유 키로 사용되지 않습니다. null 허용: False 최대 길이: 256 예: example-account가져오기 또는 입력 방법: 호출자가 식별하기 쉬운 클라우드 계정 표시 이름을 제공합니다. |
| config.area | custom_enum | Y | 생성 시 필수이며 cn/intl이며 각각 aws-cn/aws에 대응합니다. 단일 AWS Region이 아닙니다. 수정 시 허용되지 않으며 원래 파티션이 고정됩니다. 현재 브랜드/파티션의 플랫폼 권한 부여를 사용할 수 없으면 생성할 수 없습니다. null 허용: False 선택 가능한 값: ['cn', 'intl'] 예: intl가져오기 또는 입력 방법: AWS 중국 파티션은 cn, 글로벌 파티션은 intl을 선택하며 고객 계정 및 역할 ARN의 파티션과 일치해야 합니다. |
| config.authType | custom_enum | Y | 생성 시 필수이며 assume_role만 가능합니다. 수정 시 전환할 수 없으며 기존 role/accessKey를 사용하지 않습니다. null 허용: False 선택 가능한 값: ['assume_role'] 예: assume_role가져오기 또는 입력 방법: 타사 AWS IAM Role 권한 부여 방식을 사용합니다. |
| config.extraTags | array | 선택 사항이며 최대 50개 항목입니다. 생성 시 기본값은 []이고, 수정 시 생략하면 유지되며 []는 지웁니다. 각 항목은 key/value만 가능하고 문자열이어야 하며 추가 필드를 넣을 수 없습니다. 이 페이지는 태그를 관리하며 기존 과거 텔레메트리 데이터를 직접 덮어쓰지 않습니다. null 허용: False 최대 길이: 50 예: [{"key": "env", "value": "prod"}]가져오기 또는 입력 방법: 고객이 클라우드 수집 데이터에 추가할 태그 키-값을 선택하며, 먼저 실제 비즈니스 명명을 확인합니다. |
|
| config.extraTags[*] | object | 단일 객체는 정확히 key/value여야 하며 null이 없어야 합니다. 중복 키는 거부되며 마지막 값으로 덮어쓰지 않습니다. 예: {"key": "env", "value": "prod"}가져오기 또는 입력 방법: 비즈니스 태그 키-값 한 쌍입니다. |
|
| config.extraTags[*].key | string | 조건부 필수 | 필수이며 비어 있으면 안 되고 영문자/숫자/_만 허용하며 최대 256 UTF-8 바이트입니다. __로 시작하는 값, account_id/account_name 예약 키는 금지됩니다. 동일 배열 내에서 중복될 수 없습니다. null 허용: False 예: env가져오기 또는 입력 방법: 표준 비즈니스 태그 키를 사용합니다. |
| config.extraTags[*].value | string | 조건부 필수 | 필수이며 비어 있지 않은 문자열이고 최대 1024 UTF-8 바이트입니다. 제어 문자 및 잘못된 서로게이트 문자는 금지되며, 숫자 값은 호출자가 명시적으로 문자열로 변환해야 합니다. null 허용: False 예: prod가져오기 또는 입력 방법: 해당 비즈니스 태그의 실제 값입니다. |
| config.roleName | string | Y | 생성 시 필수이며 수정 시 생략하면 유지됩니다. 비어 있지 않은 ASCII 경로/이름이며 arn: 또는 /로 시작할 수 없고 /로 끝날 수 없습니다. 마지막 이름은 1..64자이고 영문자/숫자/_+=,.@-만 허용됩니다. 경로는 구분자를 포함한 IAM 최대 512자 규칙을 따르며 공개 총 길이 상한은 575입니다. 수정 시 고객 측 역할과 신뢰 정책을 동기화해야 하며 표시 이름만 변경할 수 없습니다. null 허용: False 최대 길이: 575 예: collection/ExampleCollector가져오기 또는 입력 방법: 고객 IAM 역할 ARN에서 role/ 이후의 전체 경로와 역할 이름을 가져옵니다. |
| provider | custom_enum | Y | 생성 시 필수이며 aws만 가능합니다. Front 멀티 클라우드 계정 생성 진입점이 아니며 ak/sk 또는 다른 클라우드 공급자를 전달하지 않습니다. null 허용: False 선택 가능한 값: ['aws'] 예: aws가져오기 또는 입력 방법: 현재 공개 관리 진입점은 AWS만 지원합니다. |
매개변수 추가 설명¶
AWS assume_role만 지원합니다. 호출자는 현재 워크스페이스의 cloudAccount.accountManage 권한이 있어야 하며 무료 플랜에서는 사용할 수 없습니다. DF-API-KEY를 사용하며, 이 권한에는 임시 자격 증명 읽기 권한이 자동으로 포함되지 않습니다.
타사 자동화 권한 부여¶
- 구성을 생성하고 반환된
uuid,externalId,platformAccountId를 저장합니다. 첫 검증은 실패할 수 있지만 구성은 여전히 저장할 수 있습니다. HTTP 성공이 AWS 권한 부여가 통과되었음을 의미하지는 않습니다. - 타사는 고객이 이미 권한을 부여한 AWS IAM/CloudFormation 권한을 사용하여 Role을 생성하고, 수집에 필요한 읽기 권한을 구성하며, 다음 신뢰 정책을 설정합니다.
cn은aws-cn에,intl은aws에 대응합니다. 플랫폼 계정 ID와 External ID를 이 레코드의 반환 값으로 바꿉니다. OpenAPI는 고객 AWS 리소스를 대신 관리하지 않으며 고객 AK/SK도 받지 않습니다. - Role의 경로/이름은
config.roleName과 일치해야 합니다. 고객 배포가 완료되면 수정 인터페이스{"config":{},"dryRun":true}를 호출하여 검증합니다. 통과 후dryRun=false를 전달하여 다시 검증하고 저장합니다. IAM 전파 지연에 대해서는 상한이 있는 백오프를 수행하며, 반복 생성하거나 External ID를 교체하지 않습니다. 역할의 권한 정책과 신뢰 정책은 두 가지 독립적인 구성입니다. 신뢰만 성공했다고 해서 모든 수집 서비스 권한이 완전하다고 보장되지 않습니다. - 다중 계정 자동화는 고객 AWS 계정별로 UUID/External ID 매핑을 저장하며 External ID를 공유하지 않습니다. 클라우드 계정 관리는 수집기를 자동으로 설치하지 않습니다.
반환 및 복구¶
creationResult.status:created또는failed;validationResult.status:not_run,passed또는failed이며 각각code/message를 포함합니다. 한 번의 검증에는 기존의 올바른/누락/오류 External ID 탐지가 포함됩니다.- 생성 성공 시
uuid,externalId,platformAccountId,isAvailable을 반환합니다. 검증 실패 시에도created일 수 있습니다. 생성 성공이 확인되지 않은 경우 권한 부여 필드는 null이며, HTTP 오류 상태를 200으로 변경하지 않습니다. dryRun,externalId,authorizationContext, 브랜드 또는 워크스페이스 재정의 필드를 받지 않습니다. 생성 시 플랫폼이 External ID를 생성하며 별도의 프런트엔드 작업이 필요하지 않습니다.- 동일 워크스페이스의 동일 AWS Account ID에 기존
accessKey/role이 있으면ft.CloudAccountLegacyCredentialsConflict(409) 및content.existingCloudAccountUUIDs를 반환합니다. 사용자가 기존 레코드를 처리한 후 다시 시도해야 합니다. 생성 시 이미 존재하는 레코드만 확인하며 진입점 간 영구/동시 상호 배제를 보장하지 않습니다. - 중복 생성 시
ft.CloudAccountAKRepeat충돌과 기존 레코드 UUID를 따르며 자동으로 수정하거나 교체하지 않습니다. 네트워크 타임아웃/5xx 발생 후에는 먼저 목록으로 레코드를 복구합니다.accountId는 퍼지 쿼리이므로 페이지를 순회하며config.accountId를 정확히 대조해야 합니다. 레코드를 찾으면 원래 UUID/External ID를 사용합니다. 찾지 못했더라도 한 번의 쿼리를 이전 요청이 반드시 제출되지 않았다고 볼 수 없으므로, 제한된 범위로 쿼리하고 충돌 결과를 확인한 뒤 재시도 여부를 결정해야 합니다. - 매개변수/인증/충돌 등 검증 전 실패는
not_run입니다. 검증 완료 후 잠금 또는 제출 실패가 발생해도 이번passed/failed는 유지됩니다. 5xx는 안전한 일반 오류 및 traceId를 반환하며 원래 SQL/AWS 응답을 반환하지 않습니다.
AWS 참고: 타사 교차 계정 권한 부여, CloudFormation 역할.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/cloud_account/do/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"provider":"aws","config":{"authType":"assume_role","area":"intl","accountId":"123456789012","roleName":"collection/ExampleCollector","accountName":"example-account","extraTags":[{"key":"env","value":"prod"}]}}'
응답¶
HTTP 200, application/json입니다. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.uuid | string 또는 null | 저장이 확인된 경우 clac_ UUID, 그렇지 않으면 null. |
| content.externalId | string 또는 null | 이 레코드에서 생성된 독립 External ID로, AWS 신뢰 조건을 구성합니다. 저장이 확인되지 않은 경우 null. |
| content.platformAccountId | string 또는 null | 현재 브랜드/파티션 플랫폼 AWS Account ID이며 고객 Account ID가 아닙니다. 저장이 확인되지 않은 경우 null. |
| content.isAvailable | boolean 또는 null | 이번 검증의 가용성이며 저장 여부와는 독립적입니다. |
| content.creationResult | object | 생성/영속화 작업 결과. |
| content.creationResult.status | string | 작업 결과 상태이며 creationResult 또는 operationResult 설명을 따릅니다. |
| content.creationResult.code | string | 작업 오류 코드이며 성공 시 빈 문자열입니다. validationResult.code와 동일하지 않습니다. |
| content.creationResult.message | string | 작업 오류 설명이며 성공 시 빈 문자열입니다. |
| content.validationResult | object | 동일한 권한 부여 탐지의 독립 결과이며 영속화 결론이 아닙니다. |
| content.validationResult.status | string | not_run은 검증 미완료, passed는 통과, failed는 실행되었지만 통과하지 못함을 의미합니다. |
| content.validationResult.code | string | passed는 빈 문자열이며 failed는 일반적으로 ft.CloudAccountAuthInvalid 또는 ft.CloudAccountExternalIdTrustInvalid입니다. |
| content.validationResult.message | string | 안전한 비즈니스 설명이며 AWS 원본 응답/장기 키를 에코하지 않습니다. |
| content.existingCloudAccountUUIDs | array<string> | 관련 충돌 오류 content에만 존재하며, 이 워크스페이스에서 복구 가능한 레코드 UUID입니다. |
| content.existingCloudAccountUUIDs[] | string | 단일 클라우드 계정 UUID. |
| content.declaration | object | 성공 응답 외부의 공통 선언이며, 자체 반환 오류에는 이 선언이 추가되지 않습니다. |
| 응답 헤더 | 유형 | 설명 |
|---|---|---|
| Cache-Control | string | no-store, 성공 및 이 블루프린트 라우트 오류 모두 캐시를 금지합니다. |
| Pragma | string | no-cache. |
{
"code": 200,
"content": {
"uuid": "clac_example",
"externalId": "EXTERNAL-ID-EXAMPLE",
"platformAccountId": "111111111111",
"isAvailable": false,
"creationResult": {
"status": "created",
"code": "",
"message": ""
},
"validationResult": {
"status": "failed",
"code": "ft.CloudAccountAuthInvalid",
"message": "无效账号,请检查配置信息是否正确,并确保网络连接正常"
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
고객 측 신뢰 정책 예시(플랫폼 계정/External ID는 반드시 이 레코드의 반환 값으로 바꾸고, cn 파티션은 ARN 접두사를 aws-cn으로 바꿉니다. 필요한 수집 읽기 권한 정책은 별도로 구성합니다):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111111111111:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "EXTERNAL-ID-EXAMPLE"
}
}
}
]
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
공개 선언/인증 계층 실패 시 표준 content={}만 있을 수 있으며 validationResult가 반드시 나타난다고 보장하지 않습니다. 관리 4개 진입점이 비즈니스 어댑테이션으로 진입한 후 생성/수정 실패에는 안전한 작업 결과가 포함될 수 있습니다. 내부의 일반 5xx는 통일적으로 자체 반환 500 ft.CodeError를 사용하며, content에는 이번 검증 상태가 유지되고 전역적으로 InternalServerError로 대체되지 않습니다. 임시 자격 증명 진입점의 일반적인 미처리 예외만 전역 500 ft.InternalServerError로 처리됩니다. HTTP 또는 success만 보지 말고 작업 결과, 검증 결과, saved 및 다시 읽은 레코드를 함께 판단해야 합니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 매개변수 구문 분석 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | Body 최상위가 JSON 객체가 아님 | 일부 json 파일 형식 오류 | 예시에 맞는 JSON 객체를 제출합니다. |
| 403 | ft.Forbidden | 관리 4개 진입점이 무료 플랜 워크스페이스에서 명시적 버전 검사로 거부됨 | 작업 권한이 없습니다 | 워크스페이스 버전과 관리 권한을 확인하고, 해당 기능과 권한이 있는 대상 워크스페이스로 전환합니다. |
| 404 | ft.InvalidCloudAccountType | 전달된 또는 대상 레코드가 AWS assume_role이 아님 | 유효하지 않은 클라우드 계정 유형 | 현재 워크스페이스의 전용 클라우드 계정 목록에서 레코드를 가져옵니다. 기존 accessKey/role 및 다른 공급업체는 이 진입점에 사용할 수 없습니다. |
| 400 | ft.ParamsValidateError | JSON Body가 빈 객체 {}가 아니거나, 기존에 저장된 AWS assume_role 구성이 계정/역할/External ID 규격에 맞지 않음 | 매개변수 검증 실패: {} | 요청에는 {}만 제출합니다. 기존 구성이 잘못된 경우 권한이 있는 클라우드 계정 관리 흐름을 통해 확인 및 수정하며, 이 인터페이스에서 dryRun/구성 업데이트 필드를 전달하지 않습니다. |
| 400 | ft.CloudAccountAssumeRoleCreationDisabled | 현재 브랜드/파티션의 플랫폼 권한 부여가 제공되지 않았거나 정보가 불완전함 | 현재 환경에서는 assume_role 권한 부여 추가가 제공되지 않습니다. 관리자에게 문의하세요 | 관리자에게 해당 브랜드 파티션 지원 여부를 확인하고 다른 브랜드 플랫폼 ID로 변경하지 마세요. |
| 400 | ft.CloudAccountAuthorizationContextInvalid | 서버에서 자동 생성한 권한 부여 컨텍스트가 만료되었거나 ID/브랜드/구성이 일치하지 않음 | 권한 부여 초안이 만료되었거나 현재 작업과 일치하지 않습니다. 다시 생성하세요 | 현재 워크스페이스/브랜드 및 동시 변경을 확인합니다. 먼저 조회하여 생성된 레코드를 복구한 후 안내에 따라 다시 시도합니다. |
| 409 | ft.CloudAccountLegacyCredentialsConflict | 동일 AWS Account ID에 기존 accessKey/role 비삭제 레코드가 있음 | 현재 워크스페이스에 해당 AWS 계정의 기존 자격 증명 레코드가 있습니다. 기존 레코드를 수동으로 삭제한 후 다시 시도하세요 | 먼저 existingCloudAccountUUIDs로 기존 수집 의존성을 확인하고 비즈니스 권한 부여에 따라 기존 레코드를 처리합니다. 자동으로 덮어쓰지 않습니다. |
| 400 | ft.CloudAccountAKRepeat | 동일 워크스페이스에 동일 AWS Account ID의 assume_role 레코드가 이미 있음 | 현재 워크스페이스에 동일한 {} {}가 이미 있습니다 |
반환된 existingCloudAccountUUIDs 및 원래 External ID를 사용하며 계정을 중복 생성하지 않습니다. |
| 429 | ft.OperationTooFrequently | 쓰기 잠금 경쟁/잠금 유실, 대기 중 구성이 다른 요청에 의해 수정됨 | 작업이 너무 빈번합니다. 잠시 후 다시 시도하세요 | 제한된 백오프 전에 UUID로 다시 읽고, 이전 스냅샷을 기준으로 새 제출을 덮어쓰지 않습니다. 생성 결과를 알 수 없는 경우 먼저 Account ID로 복구합니다. |
| 500 | ft.CodeError | 클라우드 계정/기존 JSON/수집기 자료 또는 플랫폼 권한 부여 표시를 읽는 중 내부 예외 발생 | 내부 처리 오류 | traceId 및 Query를 보존하고 기존 구성/데이터베이스 및 플랫폼 권한 부여를 확인합니다. 이 읽기는 수집 스크립트 배포 또는 구성 쓰기를 수행하지 않습니다. |