AWS Role 클라우드 계정 수정 또는 검증¶
POST /api/v1/cloud_account/{cloud_account_uuid}/do/modify
개요¶
현재 워크스페이스의 기존 AWS assume_role 구성을 검증하거나 수정합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 API Key를 사용하며, 관리 4개 진입점에는 cloudAccount.accountManage가 필요하고 무료 플랜에서는 명시적으로 거부됩니다. 계정 범위는 Key가 속한 워크스페이스를 따릅니다. 임시 자격 증명 읽기에는 별도의 cloudAccount.temporaryCredentialsRead가 필요하며, 관리 권한에 자동으로 포함되지 않습니다. 플랫폼 권한 부여는 현재 워크스페이스의 브랜드와 cn/intl 파티션에 따라 선택되며 다른 브랜드로 대체되지 않습니다. 모든 응답에는 Cache-Control: no-store, Pragma: no-cache가 포함됩니다.
dryRun은 반드시 명시해야 하며 config는 필수이고, {}는 기존 구성을 검증합니다. accountName/roleName/extraTags만 변경할 수 있으며, 각 항목을 생략하면 유지되고 태그는 []로 비웁니다. accountId/area/authType/External ID 변경은 허용되지 않으며, 기존 role 마이그레이션 진입점이 아닙니다.
dryRun=true이면 실제 STS 검증을 동기적으로 수행하고 계정을 저장하지 않으며 수집 스크립트를 배포하지 않고 saved=false를 반환합니다. 권한 부여가 통과하지 않아도 HTTP 200, operationResult=completed, validationResult=failed일 수 있습니다. dryRun=false도 마찬가지로 먼저 검증한 뒤 isAvailable=false로 저장할 수 있습니다. saved=true는 영속화 처리가 완료되었음(구성이 변경되지 않았지만 재동기화된 경우 포함)만 의미하며, 검증 passed 또는 수집 성공을 의미하지 않습니다.
기존 수집기가 있으면 정식 저장 시 스크립트를 재생성/배포하며, 구성이 변경되지 않아도 재동기화될 수 있습니다. 외부 배포와 데이터베이스는 서비스 간 원자적 트랜잭션이 아니므로 실패 시 현재 영속화된 구성에 따라 복구/제거를 시도하며, 복구 실패 시 관리자가 조사해야 하고 전체 롤백되었다고 단정할 수 없습니다. 동시 구성 변경이 있으면 이전 스냅샷으로 덮어쓰는 것을 거부합니다. 검증만 수행하면 saved=false이고, 정식 실패가 아직 확정되지 않은 경우 null일 수 있으며 성공 시 true입니다.
먼저 구성을 생성하고 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 사이트 목록을 참조하십시오.
경로 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| cloud_account_uuid | string | Y | 경로 필수이며, 삭제되지 않은 AWS assume_role 레코드여야 합니다. 고객 Account ID, 역할 ARN 또는 다른 워크스페이스 UUID를 사용하지 않습니다. 빈 문자열 허용: False 예시: clac_example가져오기 또는 입력 방법: 클라우드 계정 목록content.data[].uuid 또는 생성 성공 content.uuid에서 현재 워크스페이스의 clac_ 레코드를 가져옵니다. |
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| config.authType | string | 생성 시 필수이며 assume_role만 허용하고, 수정 시 전환할 수 없으며 기존 role/accessKey를 사용하지 않습니다. 예시: assume_role가져오기 또는 입력 방법: 타사 AWS IAM Role 권한 부여 방식을 사용합니다. |
|
| config.area | string | 생성 시 필수이며 cn/intl은 각각 aws-cn/aws에 대응하고 단일 AWS Region이 아닙니다. 수정 시 허용되지 않으며 기존 파티션이 고정됩니다. 현재 브랜드/파티션의 플랫폼 권한 부여를 사용할 수 없으면 생성할 수 없습니다. 예시: intl가져오기 또는 입력 방법: AWS 중국 파티션은 cn, 글로벌 파티션은 intl을 선택하며 고객 계정 및 역할 ARN의 파티션과 일치해야 합니다. |
|
| config.accountId | string | 생성 시 필수이며 비즈니스 요구사항상 정확히 12자리 숫자 문자열이어야 하고 플랫폼 계정 ID/이메일/Role ARN이 아닙니다. 수정 시 계정 교체는 허용되지 않습니다. 목록의 동일 이름 Query는 퍼지 필터이므로 혼동하지 마십시오. 예시: 123456789012가져오기 또는 입력 방법: 고객 AWS 콘솔의 계정 정보에서 12자리 Account ID를 가져오고 앞의 0을 유지합니다. |
|
| config | object | Y | 생성 시 전체 구성이 필수이고, 수정 시 객체가 필수이며 {}는 기존 구성을 유지하지만 여전히 검증하고 dryRun=false이면 기존 수집 스크립트를 다시 동기화할 수 있습니다. externalId/브랜드/워크스페이스/장기 자격 증명 등 공개되지 않은 필드를 추가할 수 없습니다. null 허용: False 예시: {}가져오기 또는 입력 방법: 고객 AWS 계정/IAM 역할 정보와 아래 필드로 구성합니다. |
| config.accountName | string | 생성 시 필수이며 비어 있지 않은 문자열이고, 수정 시 생략하면 유지되며 빈 문자열은 비즈니스 검증에서 거부됩니다. 최대 256 가중치 문자입니다. AWS 로그인 사용자 이름 또는 고유 Account ID가 아니며 복구 고유 키로 사용되지 않습니다. null 허용: False 최대 길이: 256 예시: example-account가져오기 또는 입력 방법: 호출자가 식별하기 쉬운 클라우드 계정 표시 이름을 제공합니다. |
|
| 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 | 생성 시 필수이며 수정 시 생략하면 유지됩니다. 비어 있지 않은 ASCII 경로/이름이어야 하고 arn: 또는 /로 시작할 수 없으며 /로 끝날 수 없습니다. 마지막 이름은 1..64자이고 영문/숫자/_+=,.@-만 허용됩니다. 경로는 IAM 최대 512자(구분자 포함) 규칙을 따르며 공개 총 길이 상한은 575입니다. 수정 시 고객 측 역할과 신뢰 정책을 동기화해야 하며 표시 이름만 변경할 수 없습니다. null 허용: False 최대 길이: 575 예시: collection/ExampleCollector가져오기 또는 입력 방법: 고객 IAM 역할 ARN에서 role/ 이후의 전체 경로와 역할 이름을 가져옵니다. |
|
| dryRun | boolean | Y | 필수 불리언이며 기본값이 없습니다. true이면 실제로 STS를 호출하지만 클라우드 계정을 저장하지 않고 수집 스크립트를 배포하지 않으며 saved=false를 반환합니다. false이면 검증 후 저장하고(검증 failed여도 저장 가능) 기존 수집 스크립트를 동기화하며, 검증이 반드시 통과함을 의미하지 않습니다. 생성 시에는 이 매개변수를 허용하지 않습니다. null 허용: False 예시: true가져오기 또는 입력 방법: 수정 시 검증만 수행하려면 true, 정식 저장하려면 false를 명시적으로 선택합니다. |
매개변수 추가 설명¶
현재 워크스페이스에 저장된 AWS assume_role 레코드만 지원하며 cloudAccount.accountManage가 필요합니다. accountName, roleName, extraTags만 수정할 수 있고 계정 ID, 파티션, 인증 유형 및 External ID는 이 API로 변경할 수 없습니다.
검증 및 저장¶
- 고객 Role/신뢰 정책 구성이 완료되면
{"config":{},"dryRun":true}를 전달합니다.saved=false와 이번 검증 결과를 반환하며 데이터베이스에 쓰지 않고 수집 스크립트를 배포하지 않으며 수정 감사 로그를 생성하지 않습니다. dryRun=false를 전달하면 다시 검증하고 기존 로직에 따라 저장하며 성공 시saved=true를 반환합니다. 검증에 실패해도isAvailable=false로 저장할 수 있으므로 HTTP 200만으로 권한 부여 성공을 판단할 수 없습니다.- 기존 수집기는 Front의 현재 로직에 따라 재동기화되며, 동일한 구성으로 재시도해도 다시 배포될 수 있습니다. 계정 구성 저장의 멱등성은 다운스트림 exactly-once를 의미하지 않으며, dryRun 성공을 이후 저장이 반드시 성공한다는 약속으로 간주하지 않습니다.
- 태그를 생략하면 유지되고
[]는 비웁니다. RoleName은 경로를 지원하며 전체 ARN은 허용하지 않습니다. 일반 수정에서는 기존 External ID를 유지합니다.
반환 및 실패¶
content.uuid, content.saved, content.operationResult, content.validationResult(및 공통 content.declaration)를 반환하며, 두 결과 그룹은 각각 status/code/message를 포함합니다. 작업 상태는 completed/failed, 검증 상태는 not_run/passed/failed입니다. saved는 커밋이 확인되지 않은 경우 null이고, dryRun은 명시적으로 false, 정식 성공은 명시적으로 true입니다. 검증이 완료된 후 저장/잠금이 실패해도 이번 검증 결론은 유지되며 HTTP는 오류 상태를 유지합니다.
대상이 아닌 인증 유형, 교차 워크스페이스 또는 삭제된 UUID는 비즈니스 수정 전에 거부되며 STS, 스크립트 또는 마이그레이션을 트리거하지 않습니다. IAM 전파 지연에는 상한이 있는 백오프를 적용하고 원래 UUID/External ID를 재사용합니다. 실패 시 현재 구성을 조회하고 traceId를 확인하며 권한 부여 식별자를 무작정 교체하지 않습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/cloud_account/clac_example/do/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"config":{},"dryRun":true}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.uuid | string 또는 null | 대상 UUID이며 대상 사전 검사 실패 시 null일 수 있습니다. |
| content.saved | boolean 또는 null | dryRun 성공 시 false, 정식 처리 성공 시 true, 정식 저장이 확인되지 않은 경우 null입니다. |
| content.operationResult | object | 작업 적용 결과이며 completed 또는 failed입니다. 검증 실패여도 completed일 수 있습니다. |
| content.operationResult.status | string | 작업 결과 상태이며 creationResult 또는 operationResult 설명 기준을 따릅니다. |
| content.operationResult.code | string | 작업 오류 코드이며 성공 시 빈 문자열입니다. validationResult.code와 같지 않습니다. |
| content.operationResult.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.declaration | object | 성공 시에만 래핑되는 외부 공통 선언입니다. |
| 응답 헤더 | 유형 | 설명 |
|---|---|---|
| Cache-Control | string | no-store이며 성공 및 이 블루프린트 라우트 오류 모두 캐시를 금지합니다. |
| Pragma | string | no-cache. |
{
"code": 200,
"content": {
"uuid": "clac_example",
"saved": false,
"operationResult": {
"status": "completed",
"code": "",
"message": ""
},
"validationResult": {
"status": "passed",
"code": "",
"message": ""
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-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.CloudAccountNotFound | 대상 UUID가 현재 워크스페이스의 비삭제 클라우드 계정 범위에 없음 | 클라우드 계정이 존재하지 않습니다 | 현재 워크스페이스 AWS Role 클라우드 계정 목록 content.data[].uuid에서 대상을 다시 가져오십시오. 이 읽기는 쓰기 잠금을 기다리지 않습니다. |
| 404 | ft.InvalidCloudAccountType | 전달된 또는 대상 레코드가 AWS assume_role이 아님 | 유효하지 않은 클라우드 계정 유형 | 현재 워크스페이스의 전용 클라우드 계정 목록에서 레코드를 가져오십시오. 기존 accessKey/role 및 다른 공급업체는 이 진입점에 사용할 수 없습니다. |
| 400 | ft.ParamsValidateError | JSON Body가 빈 객체 {}가 아니거나 기존에 저장된 AWS assume_role 구성이 계정/역할/External ID 규격에 맞지 않음 | 매개변수 검증 실패: {} | 요청에는 {}만 제출하십시오. 기존 구성이 유효하지 않으면 권한이 있는 클라우드 계정 관리 흐름을 통해 확인 및 수정하고, 이 API에서 dryRun/구성 업데이트 필드를 전달하지 마십시오. |
| 400 | ft.CloudAccountAKRepeat | 현재 워크스페이스의 다른 assume_role 레코드와 Account ID가 중복됨 | 현재 워크스페이스에 이미 동일한 {} {}가 존재합니다 |
기존 계정을 확인하고 다른 레코드를 마이그레이션/덮어쓰지 마십시오. |
| 429 | ft.OperationTooFrequently | 쓰기 잠금 경쟁/잠금 유실, 대기 중 구성이 다른 요청에 의해 수정됨 | 작업이 너무 빈번합니다. 잠시 후 다시 시도하십시오 | 제한된 백오프 전에 UUID로 다시 읽고 이전 스냅샷을 기준으로 새 제출을 덮어쓰지 마십시오. 생성 결과가 불확실하면 먼저 Account ID로 복구하십시오. |
| 500 | ft.CodeError | 클라우드 계정/기존 JSON/수집기 자료 조회 또는 플랫폼 권한 부여 표시 중 내부 예외가 발생함 | 내부 처리 오류 | traceId 및 Query를 보존하고 기존 구성/데이터베이스 및 플랫폼 권한 부여를 확인하십시오. 이 읽기는 수집 스크립트 배포 또는 구성 쓰기를 수행하지 않습니다. |