Storage > Object Storage > 컨테이너 정책 설정 가이드

이 문서는 컨테이너 정책을 사용해 NHN Cloud 오브젝트 스토리지의 컨테이너 관련 설정을 관리하는 방법을 설명합니다.

컨테이너 정책

컨테이너 정책을 사용하면 컨테이너 설정을 JSON 형식의 정책 문서로 통합하여 관리할 수 있습니다.

정책 문서는 다음과 같이 기능별 최상위 키로 구성되며, 각 최상위 키 하위에 세부 설정을 정의합니다.

{
  "lifecycle": { ... },
  "acl": { ... },
  "ip_acl": { ... },
  "cors": { ... },
  "lock": { ... }
}

각 최상위 키가 담당하는 기능은 다음과 같습니다.

컨테이너 정책 API

정책 조회

컨테이너에 설정된 정책 문서를 조회합니다.

GET /v1/{Account}/{Container}?policy
X-Auth-Token: {token-id}

요청

응답

성공 시 HTTP 상태 코드 200과 함께 JSON 형식의 정책 문서를 반환합니다. 설정된 정책이 없으면 빈 JSON 오브젝트를 반환합니다.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

policy 쿼리 파라미터에 값을 지정하지 않으면 설정된 모든 기능의 정책을 하나의 문서로 반환합니다.

GET /v1/{Account}/{Container}?policy
X-Auth-Token: {token-id}

{
  "lifecycle": {
    "default_rule": { "days": 10, "action": { "type": "delete" } },
    "rules": [
      {
        "name": "rule1",
        "condition": { "prefix": "logs/" },
        "days": 5,
        "action": { "type": "transfer", "destination": "archive-container" }
      }
    ]
  },
  "acl": {
    "read": { "public": true, "grantees": [ { "tenant": "project-a", "user": "user-1" } ] }
  },
  "ip_acl": {
    "whitelist": [ { "permission": "read", "cidr": "10.0.0.0/24" } ],
    "services": [ { "name": "service_gateway", "permission": "read" } ]
  },
  "cors": {
    "allow_origins": [ "https://example.com" ],
    "max_age": 3600,
    "expose_headers": [ "ETag" ]
  },
  "lock": { "days": 30 }
}

policy 쿼리 파라미터에 값을 지정하면 해당 기능의 정책만 반환합니다. 설정되지 않은 기능은 응답에 포함되지 않습니다.

GET /v1/{Account}/{Container}?policy=acl
X-Auth-Token: {token-id}

{
  "acl": {
    "read": {
      "public": true,
      "grantees": [ { "tenant": "project-a", "user": "user-1" } ]
    }
  }
}

정책 설정

요청 본문에 JSON 정책 문서를 포함해 컨테이너 정책을 설정합니다.

정책을 설정할 때 다음 규칙이 적용됩니다.

• 최상위 키는 lifecycle, acl, ip_acl, cors, lock만 사용할 수 있으며, 스키마에 정의되지 않은 키나 필드를 포함하면 요청이 거부됩니다.
• 정책 문서에 포함한 최상위 키는 보낸 내용으로 전체를 덮어쓰고, 포함하지 않은 최상위 키의 설정은 그대로 유지됩니다. 최상위 키를 보내면서 일부 하위 항목만 담으면 담지 않은 항목은 해제되므로, 유지하려는 항목은 항상 함께 보내야 합니다.

POST /v1/{Account}/{Container}
X-Auth-Token: {token-id}
Content-Type: application/json

요청

응답

성공 시 HTTP 상태 코드 204를 반환합니다. 응답 본문은 없습니다.

수명 주기

컨테이너 정책 문서의 lifecycle 키를 사용해 수명 주기 규칙을 설정합니다. 수명 주기에는 두 가지 종류의 규칙이 있습니다.

JSON 정책 문서 스키마

수명 주기 정책 문서의 구조는 다음과 같습니다.

{
  "lifecycle": {
    "default_rule": {
      "days": integer,
      "action": {
        "type": "transfer" | "delete",
        "destination": string
      }
    },
    "rules": [
      {
        "name": string,
        "condition": {
          "prefix": string
        },
        "days": integer,
        "action": {
          "type": "transfer" | "delete",
          "destination": string
        }
      }
    ]
  }
}

필드 설명

수명 주기 규칙 적용

규칙 우선순위

오브젝트 하나에는 단 하나의 수명 주기 규칙만 적용됩니다. 규칙은 아래 우선순위에 따라 적용됩니다.

수명 주기

수명 주기는 오브젝트 업로드 시점에 컨테이너의 정책을 조회하여 적용합니다.

• 오브젝트를 업로드하는 시점의 수명 주기 규칙을 평가하여, 부합하는 규칙의 수명 주기(days) 값을 기반으로 오브젝트 만료 일시를 설정합니다.
• 이후 컨테이너의 수명 주기 규칙이 변경되어도 이미 업로드된 오브젝트의 만료 일시는 자동으로 갱신되지 않습니다.

만료 동작

만료 동작은 오브젝트 만료 시점에 컨테이너의 정책을 조회하여 적용합니다.

• 오브젝트 만료 시점에 수명 주기 규칙을 다시 평가하여, 부합하는 규칙의 만료 동작(action)에 따라 이동(transfer) 또는 삭제(delete)를 수행합니다.
• 만료 시점에 어떤 규칙과도 부합하지 않고 기본 규칙도 없으면 오브젝트는 삭제됩니다.

적용 예시

아래와 같은 수명 주기 규칙이 설정되어 있다고 가정합니다.

{
  "lifecycle": {
    "default_rule": {
      "days": 10,
      "action": { "type": "delete" }
    },
    "rules": [
      {
        "name": "rule1",
        "condition": { "prefix": "logs/" },
        "days": 5,
        "action": { "type": "transfer", "destination": "archive-container" }
      }
    ]
  }
}

• 오브젝트 image/test.jpg 업로드
  • logs/ 접두사 조건에 부합하지 않으므로 기본 규칙 적용
  • 수명 주기 10일 설정
• 업로드 이후, rule1의 조건 변경
  • 조건을 "condition": { "prefix": "image/" }로 변경
• 오브젝트 image/test.jpg 수명 주기 만료
  • 만료 시점에 규칙을 다시 평가: rule1의 image/ 접두사 조건에 부합
  • 만료 동작: archive-container로 이동

접근 제어(ACL)

컨테이너 정책 문서의 acl 키를 사용해 컨테이너 접근 권한을 설정합니다. 접근 제어는 읽기, 쓰기, 조회 세 가지 권한으로 구성됩니다.

정책 문서의 read, write, view는 각각 컨테이너의 X-Container-Read, X-Container-Write, X-Container-View 속성에 대응합니다. 각 권한의 자세한 내용은 접근 정책 설정 가이드를 참고합니다.

JSON 정책 문서 스키마

접근 제어 정책 문서의 구조는 다음과 같습니다.

{
  "acl": {
    "read": {
      "public": boolean,
      "listing": boolean,
      "referrers": {
        "allow": [ string ],
        "deny": [ string ]
      },
      "grantees": [
        { "tenant": string, "user": string }
      ]
    },
    "write": {
      "grantees": [
        { "tenant": string, "user": string }
      ]
    },
    "view": {
      "grantees": [
        { "tenant": string, "user": string }
      ]
    }
  }
}

필드 설명

적용 예시

{
  "acl": {
    "read": {
      "public": true,
      "listing": true,
      "grantees": [ { "tenant": "project-a", "user": "user-1" } ]
    },
    "write": {
      "grantees": [ { "tenant": "project-a", "user": "user-1" } ]
    }
  }
}

view를 포함하지 않았으므로 조회 권한은 해제됩니다.

IP 접근 제어(IP ACL)

컨테이너 정책 문서의 ip_acl 키를 사용해 IP 기반 접근 제어를 설정합니다. 화이트리스트와 블랙리스트는 동시에 사용할 수 없으며, 둘 다 설정하면 화이트리스트만 적용됩니다. 그 외 동작 방식은 접근 정책 설정 가이드의 IP 기반 접근 정책을 참고합니다.

JSON 정책 문서 스키마

IP 접근 제어 정책 문서의 구조는 다음과 같습니다.

{
  "ip_acl": {
    "whitelist": [
      { "permission": "read" | "write" | "full_control", "cidr": string }
    ],
    "blacklist": [
      { "permission": "read" | "write" | "full_control", "cidr": string }
    ],
    "services": [
      { "name": "service_gateway", "permission": "read" | "write" | "full_control" | "deny" }
    ]
  }
}

필드 설명

적용 예시

{
  "ip_acl": {
    "whitelist": [
      { "permission": "read", "cidr": "10.0.0.0/24" },
      { "permission": "full_control", "cidr": "192.168.0.1" }
    ],
    "services": [
      { "name": "service_gateway", "permission": "read" }
    ]
  }
}

교차 출처 리소스 공유(CORS)

컨테이너 정책 문서의 cors 키를 사용해 교차 출처 리소스 공유(CORS)를 설정합니다. CORS 설정과 허용 출처 형식의 자세한 내용은 API 가이드의 교차 출처 리소스 공유(CORS)를 참고합니다.

JSON 정책 문서 스키마

CORS 정책 문서의 구조는 다음과 같습니다.

{
  "cors": {
    "allow_origins": [ string ],
    "max_age": integer,
    "expose_headers": [ string ]
  }
}

필드 설명

적용 예시

{
  "cors": {
    "allow_origins": [ "https://example.com", "https://app.example.com" ],
    "max_age": 3600,
    "expose_headers": [ "ETag", "X-Timestamp" ]
  }
}

오브젝트 잠금

컨테이너 정책 문서의 lock 키를 사용해 오브젝트 잠금(WORM, Write-Once-Read-Many)의 잠금 주기를 설정합니다. 오브젝트 잠금의 개념과 제약은 API 가이드의 오브젝트 잠금 기간 변경을 참고합니다.

JSON 정책 문서 스키마

오브젝트 잠금 정책 문서의 구조는 다음과 같습니다.

{
  "lock": {
    "days": integer
  }
}

필드 설명

적용 규칙

오브젝트 잠금은 설정할 때 다음 사항에 유의해야 합니다.

• 오브젝트 잠금은 컨테이너를 생성할 때만 활성화할 수 있습니다. 오브젝트 잠금이 설정되지 않은 기존 컨테이너에 lock을 설정하는 요청은 거부됩니다.
• 오브젝트 잠금은 해제할 수 없습니다. days를 0으로 설정하면 기본 잠금 주기가 0일이 될 뿐, 오브젝트 잠금은 활성 상태로 유지됩니다.

적용 예시

{
  "lock": {
    "days": 30
  }
}