콘텐츠로 이동

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를 보존하고 기존 구성/데이터베이스 및 플랫폼 권한 부여를 확인하십시오. 이 읽기는 수집 스크립트 배포 또는 구성 쓰기를 수행하지 않습니다.

문서 평가

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