이 페이지에서는 GKE 연결 클러스터 환경 내에서 커스텀 제약 조건을 사용 설정하고 사용하는 방법을 보여줍니다. Google Cloud의 조직 정책 서비스를 사용하면 클라우드 환경에서 리소스 구성을 관리하고 가드레일을 만들 수 있습니다.
개요
커스텀 조직 정책을 사용하면 GKE Multi-cloud 환경 전반에서 세분화된 리소스 정책을 만들어 조직의 특정 보안 및 규정 준수 요구사항을 충족할 수 있습니다. 테스트 실행 모드에서 조직 정책을 만들어 프로덕션 워크로드에 영향을 미치지 않고 새 정책을 테스트할 수도 있습니다.
기본적으로 조직 정책은 정책을 적용하는 리소스의 하위 요소에 상속됩니다. 예를 들어 조직에 정책을 적용하면 Google Cloud 에서 조직의 모든 프로젝트에 정책을 적용합니다. 정책 상속 및 평가 규칙 변경 방법에 대한 자세한 내용은 계층 구조 평가 규칙을 참조하세요.
제한사항
커스텀 제약 조건을 만들기 전에 다음 제한사항에 유의하세요.
커스텀 제약 조건은 GKE 연결된 클러스터 리소스의 CREATE 또는 UPDATE 메서드에만 적용될 수 있습니다.
새로 적용된 커스텀 제약 조건은 기존 리소스에 자동으로 적용되지 않습니다. 제약 조건을 적용하려면 기존 리소스를 업데이트해야 합니다.
업데이트해야 하는 기존 리소스를 찾으려면 시험 이전 조직 정책을 시행하면 됩니다.
제약 조건을 만들고 조직 정책을 시행하려면 Google Cloud 조직에 조직 정책 관리자(roles/orgpolicy.policyAdmin) IAM 역할이 필요합니다. 커스텀 제약 조건으로 조직 정책을 관리하는 데 필요한 권한에 대한 자세한 내용은 필요한 역할을 참조하세요.
가격 책정
조직 정책 및 커스텀 제약 조건은 무료로 제공됩니다.
커스텀 제약조건 만들기
'출력 전용'으로 설명된 필드를 제외하고 AttachedCluster API 리소스 사양의 필드를 사용하여 커스텀 제약 조건을 지정해야 합니다.
커스텀 제약조건 만들기
새 커스텀 제약 조건을 만들려면 YAML 파일에서 제약 조건을 정의하고 Google Cloud CLI를 사용하여 조직에서 커스텀 제약 조건을 적용합니다. 이 제약 조건은 GKE 연결 클러스터 리소스 전반에 적용할 특정 정책을 캡슐화해야 합니다.
CONSTRAINT_NAME : 새 커스텀 제약 조건 이름입니다. 커스텀 제약 조건은 custom.으로 시작되어야 하며 대문자, 소문자 또는 숫자만 포함할 수 있습니다. 예를 들면 custom.allowClusterCreateIfAnnotationPresent입니다. 이 필드의 최대 길이는 프리픽스를 제외하고 70자(영문 기준)입니다(예: organizations/123456789/customConstraints/custom).
CONDITION: 연결된 클러스터 리소스의 표현에 대해 작성된 조건입니다. 조건은 Common Expression Language(CEL)로 작성됩니다. 이 필드의 최대 길이는 1,000자(영문 기준)입니다.
예를 들면 조건: "key" in resource.annotations && resource.annotations.key == "created-by"입니다.
ACTION: 조건이 충족되면 수행할 작업입니다. ALLOW 또는 DENY일 수 있습니다.
DISPLAY_NAME: 제약 조건 표시 이름입니다. 이 필드의 최대 길이는 200자(영문 기준)입니다.
DESCRIPTION: 정책을 위반할 때 오류 메시지로 표시할 제약 조건에 대한 설명입니다(예: "Allow new clusters only when certain annotations are set."). 이 필드의 최대 길이는 2,000자(영문 기준)입니다.
커스텀 제약 조건을 만드는 방법에 대한 자세한 내용은 커스텀 제약 조건 정의를 참조하세요.
리소스와 제약 조건 연결
새 커스텀 제약 조건 YAML 파일을 만든 후에는 조직 정책에서 제약 조건을 사용할 수 있도록 설정해야 합니다.
커스텀 제약 조건을 설정하려면 gcloud org-policies set-custom-constraint 명령어를 사용합니다.
CUSTOM_CONSTRAINT:custom.allowClusterCreateIfAnnotationPresentACTION_TYPE:ALLOWMETHOD_TYPES:CREATERESOURCE_TYPES:gkemulticloud.googleapis.com/AttachedClusterDISPLAY_NAME:Allow new clusters only when certain annotations are set.
커스텀 제약 조건 시행
새 커스텀 제약 조건을 적용하려면 제약 조건을 참조하는 조직 정책을 만든 후 조직 정책을 적용합니다.
RESOURCE_HIERARCHY: 시정 조치 범위에 영향을 미치는 새 정책의 위치입니다. Google Cloud 리소스 계층 구조를 가이드로 사용합니다. 예를 들어 특정 프로젝트에 정책을 적용하려면 projects/PROJECT_ID를 사용합니다. 특정 조직에 정책을 적용하려면 organizations/ORGANIZATION_ID를 사용합니다.
POLICY_NAME: 새 정책의 이름입니다.
정책을 시행합니다.
gcloudorg-policiesset-policyPATH_TO_POLICY
PATH_TO_POLICY를 정책 정의 파일의 경로로 바꿉니다.
정책이 있는지 확인합니다.
gcloudorg-policieslist--RESOURCE_FLAG=RESOURCE_ID
다음을 바꿉니다.
RESOURCE_FLAG: 정책을 적용한 Google Cloud 리소스입니다. 예를 들면 프로젝트나 조직입니다.
RESOURCE_ID: 정책을 적용한 리소스의 ID입니다. 예를 들면 프로젝트 ID 또는 조직 ID입니다.
ERROR:(gcloud.container.attached.clusters.register)FAILED_PRECONDITION:Operationdeniedbyorgpolicyonresource'projects/PROJECT_NUMBER/locations/GOOGLE_CLOUD_REGION':["customConstraints/custom.allowClusterCreateIfAnnotationPresent":"Allow new clusters only when certain annotations are set."]'@type':type.googleapis.com/google.rpc.ErrorInfo
domain:googleapis.com
metadata:
customConstraints:customConstraints/custom.allowClusterCreateIfAnnotationPresent
service:gkemulticloud.googleapis.com
reason:CUSTOM_ORG_POLICY_VIOLATION
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-14(UTC)"],[],[],null,["# Create and manage custom constraints\n\nThis page shows you how to enable and use custom constraints within your GKE attached clusters environment. Google Cloud's [Organization Policy Service](/resource-manager/docs/organization-policy/overview) helps you manage resource configurations and create guardrails in your cloud environment.\n\nOverview\n--------\n\nWith custom organization policies, you can create granular resource policies across GKE Multi-Cloud environments to meet your organization's specific security and compliance requirements. You can also create organization policies in dry-run mode to test new policies without affecting your production workloads.\n\nTo learn more about organization policies, see [Introduction to the Organization Policy Service](/resource-manager/docs/organization-policy/overview#custom-organization-policies).\n\nBefore you begin\n----------------\n\nBefore you start, make sure you understand the following topics:\n\n### Policy inheritance\n\nBy default, organization policies are inherited by the descendants of the resources on which you enforce the policy. For example, if you enforce a policy on an organization, Google Cloud enforces the policy on all projects in the organization. To learn more about policy inheritance and how to change evaluation rules, see [Hierarchy evaluation rules](/resource-manager/docs/organization-policy/understanding-hierarchy#disallow_inheritance).\n\n### Limitations\n\nBefore you create custom constraints, keep in mind the following limitations:\n\n- Custom constraints can only be enforced on the `CREATE` or `UPDATE` methods for GKE attached clusters resources.\n- Newly enforced custom constraints don't automatically apply to existing resources. You must update existing resources to apply the constraint. To find existing resources that need to be updated, you can enforce a [dry-run organization policy](/resource-manager/docs/organization-policy/dry-run-policy).\n- To create constraints and enforce organization policies, you need the [Organization Policy Administrator](/iam/docs/understanding-roles#orgpolicy.policyAdmin) (`roles/orgpolicy.policyAdmin`) IAM role on your Google Cloud organization. For more information about the permissions required to manage organization policies with custom constraints, see [Required roles](/resource-manager/docs/organization-policy/creating-managing-custom-constraints#required-roles).\n\n### Pricing\n\nOrganizational policies and custom constraints are offered at no charge.\n| **Note:** This guide provides a general overview. Specific gcloud commands may vary based on your exact configuration and required policy enforcement.\n\nCreate custom constraints\n-------------------------\n\nCustom constraints must be specified by using the fields in the AttachedCluster [API resource spec](/kubernetes-engine/multi-cloud/docs/reference/rest/v1/projects.locations.attachedClusters#AttachedCluster), excluding fields that are described as \"Output only\".\n\n### Create a custom constraint\n\nTo create a new custom constraint, you define the constraint in a YAML file and apply the custom constraint in your organization using the Google Cloud CLI. This constraint must encapsulate the specific policy you want to enforce across your GKE attached clusters resources.\n\n1. Create a YAML file for the custom constraint:\n\n name: organizations/\u003cvar translate=\"no\"\u003eORGANIZATION_ID\u003c/var\u003e/customConstraints/\u003cvar translate=\"no\"\u003eCONSTRAINT_NAME\u003c/var\u003e\n resourceTypes:\n - gkemulticloud.googleapis.com/AttachedCluster\n methodTypes: \n - CREATE\n condition: \\\"\u003cvar translate=\"no\"\u003eCONDITION\u003c/var\u003e\\\"\n actionType: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eACTION\u003c/span\u003e\u003c/var\u003e\n displayName: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eDISPLAY_NAME\u003c/span\u003e\u003c/var\u003e\n description: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eDESCRIPTION\u003c/span\u003e\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eORGANIZATION_ID\u003c/var\u003e : your organization ID, such as `123456789`.\n\n - \u003cvar translate=\"no\"\u003eCONSTRAINT_NAME\u003c/var\u003e : the name of your new custom constraint. A custom constraint must start with `custom.`, and can only include uppercase letters, lowercase letters, or numbers. For example, `custom.allowClusterCreateIfAnnotationPresent`. The maximum length of this field is 70 characters, not counting the prefix, for example, `organizations/123456789/customConstraints/custom`.\n\n - \u003cvar translate=\"no\"\u003eCONDITION\u003c/var\u003e : a condition that is written against a representation of an attached cluster resource. Conditions are written in [Common Expression Language (CEL)](/resource-manager/docs/organization-policy/creating-managing-custom-constraints#common_expression_language). This field has a maximum length of 1,000 characters.\n For example, condition: `\"key\" in resource.annotations && resource.annotations.key == \"created-by\"`.\n\n - \u003cvar translate=\"no\"\u003eACTION\u003c/var\u003e : the action to take if the condition is met. This can be either `ALLOW` or `DENY`.\n\n - \u003cvar translate=\"no\"\u003eDISPLAY_NAME\u003c/var\u003e : a display name for the constraint. This field has a maximum length of 200 characters.\n\n - \u003cvar translate=\"no\"\u003eDESCRIPTION\u003c/var\u003e : a description of the constraint to display as an error message when the policy is violated, for example, `\"Allow new clusters only when certain annotations are set.\"` This field has a maximum length of 2,000 characters.\n\n For more information about how to create a custom constraint, see [Defining custom constraints](/resource-manager/docs/organization-policy/creating-managing-custom-constraints#defining_custom_constraints).\n\n### Associate the constraint with your resources\n\nAfter you have created the YAML file for a new custom constraint, you must set it up to make the constraint available for organization policies.\n\n1. To set up a custom constraint, use the `gcloud org-policies set-custom-constraint` command:\n\n gcloud org-policies set-custom-constraint \u003cvar translate=\"no\"\u003ePATH_TO_FILE\u003c/var\u003e\n\n Replace \u003cvar translate=\"no\"\u003ePATH_TO_FILE\u003c/var\u003e with the path of your custom constraint YAML definition.\n2. To verify that the custom constraint is created, use the `gcloud org-policies list-custom-constraints` command:\n\n gcloud org-policies list-custom-constraints --organization=\u003cvar translate=\"no\"\u003eORGANIZATION_ID\u003c/var\u003e\n\n The output lists the created policies: \n\n CUSTOM_CONSTRAINT: custom.allowClusterCreateIfAnnotationPresent\n ACTION_TYPE: ALLOW\n METHOD_TYPES: CREATE\n RESOURCE_TYPES: gkemulticloud.googleapis.com/AttachedCluster\n DISPLAY_NAME: Allow new clusters only when certain annotations are set.\n\nEnforce the custom constraint\n-----------------------------\n\nTo enforce the new custom constraint, create an organization policy that references the constraint, and then apply the organization policy.\n\n1. Create a YAML file for the organization policy:\n\n name: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eRESOURCE_HIERARCHY\u003c/span\u003e\u003c/var\u003e/policies/\u003cvar translate=\"no\"\u003ePOLICY_NAME\u003c/var\u003e\n spec:\n rules:\n - enforce: true\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eRESOURCE_HIERARCHY\u003c/var\u003e: the location of the new policy, which affects the scope of enforcement. Use the Google Cloud resource hierarchy as a guide. For example, if you want to enforce the policy in a specific project, use `projects/`\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e. To enforce the policy in a specific organization, use `organizations/`\u003cvar translate=\"no\"\u003eORGANIZATION_ID\u003c/var\u003e.\n\n - \u003cvar translate=\"no\"\u003ePOLICY_NAME\u003c/var\u003e: the name of the new policy.\n\n2. Enforce the policy:\n\n gcloud org-policies set-policy \u003cvar translate=\"no\"\u003ePATH_TO_POLICY\u003c/var\u003e\n\n Replace \u003cvar translate=\"no\"\u003ePATH_TO_POLICY\u003c/var\u003e with the path to your policy definition file.\n3. Verify that the policy exists:\n\n gcloud org-policies list --\u003cvar translate=\"no\"\u003eRESOURCE_FLAG\u003c/var\u003e=\u003cvar translate=\"no\"\u003eRESOURCE_ID\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eRESOURCE_FLAG\u003c/var\u003e: the Google Cloud resource where you enforced the policy. For example, a project or organization.\n\n - \u003cvar translate=\"no\"\u003eRESOURCE_ID\u003c/var\u003e: the ID of the resource where you enforced the policy. For example, your project ID or organization ID.\n\n The output is similar to the following: \n\n CONSTRAINT: custom.allowClusterCreateIfAnnotationPresent\n LIST_POLICY: -\n BOOLEAN_POLICY: SET\n ETAG: CPjb27wGEOijhL4B-\n\nTest the policy\n---------------\n\nTest the organization policy by registering an EKS cluster in a restricted project.\n\n1. Register an EKS cluster in a restricted project.\n\n gcloud container attached clusters register CLUSTER_NAME \\\n --location=GOOGLE_CLOUD_REGION \\\n --fleet-project=PROJECT_NUMBER \\\n --platform-version=PLATFORM_VERSION \\\n --distribution=eks \\\n --issuer-url=ISSUER_URL \\\n --context=KUBECONFIG_CONTEXT \\\n --kubeconfig=KUBECONFIG_PATH\n\n2. The output is similar to the following:\n\n ERROR: (gcloud.container.attached.clusters.register) FAILED_PRECONDITION: Operation denied by org policy on resource 'projects/PROJECT_NUMBER/locations/GOOGLE_CLOUD_REGION': [\"customConstraints/custom.allowClusterCreateIfAnnotationPresent\": \"Allow new clusters only when certain annotations are set.\"]\n\n '@type': type.googleapis.com/google.rpc.ErrorInfo\n domain: googleapis.com\n metadata:\n customConstraints: customConstraints/custom.allowClusterCreateIfAnnotationPresent\n service: gkemulticloud.googleapis.com\n reason: CUSTOM_ORG_POLICY_VIOLATION"]]
