정책 컨트롤러에서 마이그레이션

이 문서에서는 정책 컨트롤러에서 가입 정책을 마이그레이션하여 정책 시행의 격차 위험을 줄이는 방법을 설명합니다. 정책 컨트롤러는 2026년 11월 12일부터 지원 중단되며 2027년 12월 31일에 지원이 종료됩니다. 버전 1.39 이상에서 Google Kubernetes Engine(GKE) 클러스터는 정책 컨트롤러를 지원하지 않습니다.

정책 컨트롤러를 사용하여 적용하는 허용 정책을 Kubernetes ValidatingAdmissionPolicies 또는 자체 관리형 Open Policy Agent(OPA) Gatekeeper로 마이그레이션할 수 있습니다. 마이그레이션은 이미 실행 중인 워크로드에 영향을 미치지 않습니다. 정책 컨트롤러는 리소스 생성 또는 업데이트 요청을 평가하므로 이를 삭제해도 실행 중인 워크로드가 다시 시작되거나 변경되지 않습니다.

이 문서는 Fleet에서 정책 컨트롤러를 관리하는 운영자 및 보안 전문가를 대상으로 합니다.Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참조하세요.

GKE 버전 1.39로의 업그레이드 차단

GKE는 정책 컨트롤러가 설치된 클러스터의 버전 1.39 이상으로의 업그레이드를 차단합니다. 클러스터를 버전 1.39로 업그레이드하기 전에 정책을 마이그레이션하고 해당 클러스터에서 정책 컨트롤러를 삭제합니다. 정책을 마이그레이션하기 전에 업그레이드를 차단 해제하기 위해 정책 컨트롤러를 삭제하지 마세요. 이렇게 하면 클러스터에 정책 시행이 적용되지 않습니다.

대체 사진 선택

정책 컨트롤러에서 각 허용 정책을 평가하고 다음 표에서 해당 정책의 대체 옵션을 선택합니다. 전체 클러스터에 대해 하나의 대체 항목을 선택할 필요는 없습니다. 각 정책의 요구사항에 따라 동일한 클러스터에서 옵션을 결합할 수 있습니다.

정책 컨트롤러 교체 옵션 비교
옵션 사용 시기 운영 및 지원
ValidatingAdmissionPolicy(권장) 리소스가 생성되거나 업데이트될 때 단일 리소스를 확인하는 정책입니다. 정책 컨트롤러 템플릿 라이브러리의 대부분의 템플릿은 이 방식으로 작동합니다. ValidatingAdmissionPolicies는 Kubernetes에 기본 제공되며 GKE 버전 1.30 이상에서 추가 비용 없이 사용할 수 있습니다. Cloud Customer Care는 GKE의 일부로 ValidatingAdmissionPolicies를 지원합니다.
포드 보안 허용(포드 보안 번들에 권장) pss-baseline-v2022, pss-restricted-v2022 또는 psp-v2022 번들의 사전 정의된 포드 보안 제어 자세한 내용은 포드 보안 번들에 포드 보안 허용 사용을 참조하세요. 포드 보안 허용은 Kubernetes에 기본 제공되며 GKE에서 추가 비용 없이 기본적으로 사용 설정됩니다. 고객 지원은 GKE의 일부로 포드 보안 허용을 지원합니다.
자체 관리형 OPA Gatekeeper 클러스터의 다른 리소스를 읽는 참조 정책, Rego에 보관하려는 정책, 기존 리소스 감사와 같이 ValidatingAdmissionPolicies에서 표현할 수 없는 정책 또한 Gatekeeper가 API 서버 시행을 위해 ValidatingAdmissionPolicies를 생성하고 감사 컨트롤러가 기존 리소스를 확인하도록 Gatekeeper ConstraintTemplates에 Common Expression Language(CEL) 규칙을 추가할 수 있습니다. Gatekeeper를 설치, 업그레이드, 운영합니다. 고객 지원은 오픈소스 게이트키퍼를 지원하지 않습니다. Gatekeeper 커뮤니티는 GitHub를 통해 지원을 제공합니다.

정책 인벤토리 및 분류

기본적으로 정책 컨트롤러 템플릿 라이브러리는 모든 템플릿을 설치하고 정책 번들은 dryrun 시정 조치로 제약 조건을 설치합니다. 따라서 클러스터의 템플릿과 제약조건이 시행하는 정책과 반드시 일치하지는 않습니다. 시행 중인 정책을 확인하려면 다음 단계를 따르세요.

  1. 정책 컨트롤러를 실행하는 Fleet의 클러스터를 식별합니다.

    gcloud container fleet policycontroller describe \
    --project=PROJECT_ID

    PROJECT_ID를 Fleet 호스트 프로젝트의 ID로 바꿉니다.

  2. 식별한 각 클러스터에서 제약조건을 나열합니다.

    kubectl get constraints \
    -o custom-columns='KIND:.kind,NAME:.metadata.name,'\
'ACTION:.spec.enforcementAction,VIOLATIONS:.status.totalViolations,'\
'BUNDLE:.metadata.labels.policycontroller\.gke\.io/bundleName'

    출력에는 각 제약 조건의 시정 조치, 최근 감사에서 발견된 위반 횟수, 이를 설치한 번들이 표시됩니다. ACTION 열에 값이 없는 제약조건은 기본 deny 시정 조치를 사용합니다.

  3. ConstraintTemplates 및 제약조건을 별도의 파일에 백업합니다.

    kubectl get constrainttemplates -o yaml \
    > policy-controller-templates-backup.yaml
kubectl get constraints -o yaml \
    > policy-controller-constraints-backup.yaml

  4. 선택사항: 다음 추가 백업 작업을 수행합니다.

    • 정책 컨트롤러에서 참조 규칙을 사용 설정한 경우 동기화 구성을 백업합니다.

      kubectl get config.config.gatekeeper.sh -n gatekeeper-system -o yaml \
    > policy-controller-config-backup.yaml

    • 정책 컨트롤러에서 변형을 사용 설정한 경우 변형자를 백업합니다.

      kubectl get assign,assignmetadata,assignimage,modifyset -o yaml \
    > policy-controller-mutators-backup.yaml

이 백업 파일을 안전한 장소에 보관하세요. 정책 컨트롤러를 삭제하면 사용자가 만든 항목을 포함하여 클러스터의 모든 ConstraintTemplate, 제약조건, 동기화 구성, 변형자가 삭제됩니다. 정책을 변환하거나 다시 만들려면 백업이 필요합니다.

정책을 백업한 후 다음 표에서 제약조건 유형을 확인하여 각 제약조건의 마이그레이션 경로를 결정합니다.

제약조건 유형별 이전 경로
제약조건 유형 이전 경로
단일 리소스 제약 조건 제약조건이 data.inventory를 읽거나 포드 보안 번들에 속하지 않고 수신 리소스의 필드만 평가하는 경우 ValidatingAdmissionPolicy를 사용합니다.
시행되지 않은 dryrun 제약 조건 제약조건에서 dryrun 시정 조치를 사용하고 시행할 계획이 없으면 제약조건을 삭제합니다.
포드 보안 번들 제약 조건 제약조건이 pss-baseline-v2022, pss-restricted-v2022 또는 psp-v2022 번들에서 제공되는 경우 포드 보안 허용을 사용합니다. 포드 보안 허용에서 다루지 않는 제어에는 ValidatingAdmissionPolicies를 사용합니다.
참조 제약 조건 제약조건이 클러스터의 다른 리소스를 읽는 참조 템플릿을 사용하는 경우 자체 관리형 Gatekeeper를 사용합니다. 참조 템플릿을 찾으려면 백업 파일에서 data.inventory 참조를 검색합니다.
Cloud Service Mesh, Istio 또는 Google Cloud제약조건 제약조건을 개별적으로 검토하여 기본 제공 GKE 기능이 정책을 대체하는지 또는 백업 파일의 ConstraintTemplate이 data.inventory를 읽는지 확인합니다. 이러한 템플릿 대부분은 수신 리소스만 확인하고 ValidatingAdmissionPolicies에서 작동합니다. 단, 자체 관리형 게이트키퍼가 필요한 참조 AsmAuthzPolicyDefaultDeny 및 AsmPeerAuthnMeshStrictMtls 템플릿은 예외입니다. 기본 제공 대체 항목의 경우 K8sRequireBinAuthZ ConstraintTemplate을 사용하는 대신 Binary Authorization을 사용 설정하고 K8sRequireCosNodeImage ConstraintTemplate을 사용하는 대신 노드 풀의 노드 이미지를 구성합니다.

ValidatingAdmissionPolicy로 마이그레이션

ValidatingAdmissionPolicy에는 ConstraintTemplate과 같은 정책 로직이 포함됩니다. ValidatingAdmissionPolicyBinding은 제약조건과 같은 정책을 적용합니다. ValidatingAdmissionPolicy는 Rego 대신 CEL 표현식을 사용하며 API 서버는 웹훅 없이 표현식을 직접 평가합니다.

예시: 허용되는 이미지 저장소

다음 정책 컨트롤러 제약조건을 사용하려면 포드가 하나의 Artifact Registry 저장소에서 이미지를 사용해야 합니다. kube-system 네임스페이스를 제외합니다.

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sAllowedRepos
metadata:
  name: allowed-repos
spec:
  enforcementAction: deny
  match:
    kinds:
    - apiGroups: [""]
      kinds: ["Pod"]
    excludedNamespaces: ["kube-system"]
  parameters:
    repos:
    - "us-docker.pkg.dev/example-project/example-repo/"

다음 ValidatingAdmissionPolicy 및 ValidatingAdmissionPolicyBinding은 동일한 규칙을 적용합니다. ValidatingAdmissionPolicyBinding은 Warn 및 Audit 작업을 사용하므로 ValidatingAdmissionPolicy를 적용하기 전에 결과를 비교할 수 있습니다.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: allowed-repos
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      operations: ["CREATE", "UPDATE"]
      resources: ["pods", "pods/ephemeralcontainers"]
  variables:
  - name: repos
    expression: "['us-docker.pkg.dev/example-project/example-repo/']"
  - name: images
    expression: >-
      object.spec.containers.map(c, c.image) +
      (has(object.spec.initContainers) ?
        object.spec.initContainers.map(c, c.image) : []) +
      (has(object.spec.ephemeralContainers) ?
        object.spec.ephemeralContainers.map(c, c.image) : [])
  validations:
  - expression: >-
      variables.images.all(image,
        variables.repos.exists(repo, image.startsWith(repo)))
    messageExpression: >-
      'container images must come from one of these repositories: ' +
      variables.repos.join(', ')
    reason: Forbidden
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: allowed-repos
spec:
  policyName: allowed-repos
  validationActions: ["Warn", "Audit"]
  matchResources:
    namespaceSelector:
      matchExpressions:
      - key: kubernetes.io/metadata.name
        operator: NotIn
        values: ["kube-system", "gatekeeper-system"]

이 예시에서 repos 변수는 제약조건의 parameters 필드 값을 보유합니다. 검증 표현식은 ValidatingAdmissionPolicy를 준수하는 포드에 대해 true 값을 반환하며, 이는 Rego 위반 규칙과 반대입니다. 서로 다른 값을 제공하는 여러 ValidatingAdmissionPolicyBinding에서 하나의 ValidatingAdmissionPolicy를 재사용하려면 변수 대신 매개변수 리소스를 사용합니다. 파라미터 리소스에 대한 자세한 내용은 Kubernetes 문서의 파라미터 리소스를 참조하세요.

다음 표에서는 제약조건 필드가 ValidatingAdmissionPolicy 및 ValidatingAdmissionPolicyBinding 필드에 매핑되는 방식을 보여줍니다.

정책 컨트롤러 제약조건 필드를 ValidatingAdmissionPolicy 및 ValidatingAdmissionPolicyBinding 필드에 매핑
제약조건 필드 ValidatingAdmissionPolicy 또는 ValidatingAdmissionPolicyBinding 필드
spec.enforcementAction ValidatingAdmissionPolicyBinding의 validationActions 필드. deny, warn, dryrun 작업을 ["Deny"], ["Warn"], ["Audit"] 값에 매핑합니다.
spec.parameters ValidatingAdmissionPolicy의 variables 필드 또는 ValidatingAdmissionPolicyBinding이 paramRef 필드에서 참조하는 매개변수 리소스
spec.match.kinds 종류 대신 API 그룹 및 리소스 이름(예: pods 리소스)을 사용하는 ValidatingAdmissionPolicy의 matchConstraints.resourceRules 필드
spec.match.namespaces 및 spec.match.excludedNamespaces kubernetes.io/metadata.name 라벨에서 In 또는 NotIn 연산자를 사용하는 ValidatingAdmissionPolicyBinding의 matchResources.namespaceSelector 필드
spec.match.labelSelector ValidatingAdmissionPolicyBinding의 matchResources.objectSelector 필드
spec.match.namespaceSelector ValidatingAdmissionPolicyBinding의 matchResources.namespaceSelector 필드
spec.match.scope 각 리소스 규칙의 scope 필드

표현식을 작성하는 방법에 대한 자세한 내용은 Kubernetes 문서의 Kubernetes의 CEL을 참조하세요.

정책 컨트롤러와 함께 정책 테스트

시행에 공백이 없이 제약조건을 바꾸려면 ValidatingAdmissionPolicy를 시행하기 전에 제약조건 옆에 있는 ValidatingAdmissionPolicy를 실행합니다.

  1. validationActions: ["Warn", "Audit"] 설정이 있는 ValidatingAdmissionPolicy 및 ValidatingAdmissionPolicyBinding을 적용합니다. 정책 컨트롤러 제약조건을 그대로 둡니다.
  2. 위반 보고서 바꾸기에서 감사 로그 쿼리를 사용하여 결과를 비교합니다. ValidatingAdmissionPolicy가 정책 컨트롤러에서 허용하는 요청에 플래그를 지정하거나 그 반대의 경우 ValidatingAdmissionPolicy를 수정합니다. 포드와 일치하는 ValidatingAdmissionPolicies의 경우 경고에 의존하지 마세요. 컨트롤러는 배포 및 기타 워크로드의 포드를 만들므로 컨트롤러가 경고를 수신합니다.
  3. 결과가 일치하면 validationActions: ["Deny"] 설정을 사용하도록 ValidatingAdmissionPolicyBinding을 변경합니다.
  4. 정책 컨트롤러 제약 조건을 삭제합니다.

동작 차이 계획

ValidatingAdmissionPolicies는 다음과 같은 방식으로 정책 컨트롤러와 다르게 작동하므로 요청을 차단하거나 시행에 공백이 생길 수 있습니다.

  • 실패 정책: 정책 컨트롤러 웹훅이 열리지 않습니다. 즉, 정책 컨트롤러가 응답하지 않으면 API 서버가 요청을 허용합니다. failurePolicy: Fail 설정이 있는 ValidatingAdmissionPolicy는 표현식이 오류를 반환하거나 CEL 비용 한도를 초과하는 경우 요청을 거부합니다. 또한 ValidatingAdmissionPolicy는 참조된 매개변수 리소스가 존재하지 않고 ValidatingAdmissionPolicyBinding의 paramRef.parameterNotFoundAction 필드 값이 Deny인 경우 요청을 거부합니다. 값이 Allow이면 API 서버는 failurePolicy 설정과 관계없이 누락된 매개변수 리소스를 건너뜁니다. 각 ValidatingAdmissionPolicy를 테스트하고 두 필드의 값을 선택합니다.
  • 누락된 필드: Rego는 누락된 필드를 위반이 아닌 것으로 처리하지만 CEL은 오류를 반환합니다. 옵션 필드를 읽기 전에 has() 매크로를 사용하여 필드가 있는지 확인합니다.
  • 예외: ValidatingAdmissionPolicy는 기본적으로 네임스페이스를 예외로 처리하거나 admission.gatekeeper.sh/ignore 라벨을 사용하지 않습니다. GKE Standard 클러스터에서 ValidatingAdmissionPolicyBinding은 ValidatingAdmissionPolicyBinding의 matchResources.namespaceSelector 필드 또는 ValidatingAdmissionPolicy의 matchConstraints.namespaceSelector 또는 matchConditions 필드에서 제외하지 않는 한 kube-system 네임스페이스와 같은 시스템 네임스페이스를 포함하여 클러스터의 모든 네임스페이스에 적용됩니다. Autopilot 클러스터에서 GKE는 관리형 네임스페이스를 자동으로 제외하고 nodes, persistentVolumes, certificatesigningrequests 또는 tokenreviews 리소스와 일치하는 ValidatingAdmissionPolicies를 거부합니다. 자세한 내용은 GKE Autopilot 보안 조치를 참조하세요.
  • 하위 리소스: 정책 컨트롤러는 임시 컨테이너를 추가하는 포드 업데이트를 확인합니다. 이 범위를 유지하려면 예시와 같이 리소스 규칙에 pods/ephemeralcontainers 하위 리소스를 포함합니다.
  • 기존 리소스 감사 없음: ValidatingAdmissionPolicy는 수신 API 서버 요청만 평가합니다. ValidatingAdmissionPolicy를 위반하는 기존 리소스는 보고하지 않습니다.
  • 각 요청에 대한 하나의 메시지: ValidatingAdmissionPolicy는 모든 위반이 아닌 실패한 첫 번째 검증을 보고합니다.

포드 보안 번들에 포드 보안 허용 사용

pss-baseline-v2022 또는 pss-restricted-v2022 번들을 사용하는 경우 각 제약조건을 변환하는 대신 번들을 포드 보안 허용으로 바꿉니다. 포드 보안 허용은 기본 제공되는 Kubernetes PodSecurity 허용 컨트롤러를 사용하여 네임스페이스 라벨을 기준으로 Kubernetes 포드 보안 표준에서 사전 정의된 규칙을 적용합니다. pss-baseline-v2022 번들은 baseline 수준에 해당하고 pss-restricted-v2022 번들은 restricted 수준에 해당합니다.

포드 보안 허용은 호스트 경로, 사용자, 기능, sysctl의 허용 목록과 같은 psp-v2022 번들의 모든 제어를 포함하지 않습니다. 이러한 제어에는 ValidatingAdmissionPolicies를 사용하세요. 또한 포드 보안 허용은 exemptImages 매개변수를 사용하는 정책 컨트롤러 제약조건과 같은 특정 이미지를 예외 처리할 수 없습니다. GKE는 포드 보안 허용 예외 구성을 지원하지 않습니다. 예외가 필요한 경우 영향을 받는 정책에 ValidatingAdmissionPolicies를 사용합니다.

포드 보안 허용을 구성하는 방법에 대한 자세한 내용은 PodSecurity를 사용하여 사전 정의된 포드 수준 보안 정책 적용을 참조하세요.

자체 관리형 OPA 게이트키퍼로 마이그레이션

ValidatingAdmissionPolicies에서 표현할 수 없는 정책에는 Gatekeeper를 선택합니다. 정책 컨트롤러는 Gatekeeper를 기반으로 하므로 ConstraintTemplates 및 제약조건은 Gatekeeper에서 동일한 API를 사용합니다. 정책 컨트롤러 템플릿 라이브러리의 모든 템플릿은 로직을 변경하지 않고 Gatekeeper에서 작동합니다. 하지만 Gatekeeper는 커스텀 ConstraintTemplate을 거부할 수 있는 최신 Rego 엔진과 더 엄격한 검증을 사용합니다.

자체 관리형 게이트키퍼를 사용하는 경우 각 클러스터에서 게이트키퍼 설치, 업그레이드, 확장, 모니터링과 같이Google Cloud 가 정책 컨트롤러를 위해 수행하는 태스크를 사용자가 직접 수행해야 합니다. 고객 지원은 오픈소스 게이트키퍼를 지원하지 않습니다. 도움이 필요하면 Gatekeeper GitHub Issue Tracker를 사용하세요.

Gatekeeper에는 정책 컨트롤러 템플릿 라이브러리 또는 정책 번들이 포함되지 않습니다. 백업 파일에는 클러스터의 ConstraintTemplates 및 제약조건이 포함됩니다. 오픈소스 Gatekeeper 라이브러리에서 시작된 템플릿의 경우 Gatekeeper 정책 라이브러리의 템플릿을 사용할 수 있습니다. 템플릿 이름은 동일하게 유지되지만 매개변수와 메시지는 버전마다 다를 수 있습니다.

정책을 Gatekeeper로 이동하려면 다음 단계를 따르세요.

  1. 선택사항: 정책 컨트롤러를 교체하는 동안 시행 공백을 허용할 수 없는 경우 가장 중요한 정책을 먼저 ValidatingAdmissionPolicies로 마이그레이션합니다. Gatekeeper 설치 작업을 차단하지 않도록 ValidatingAdmissionPolicyBindings에서 gatekeeper-system 네임스페이스를 제외해야 합니다. 정책 컨트롤러를 삭제하면 해당 Gatekeeper 제약조건을 적용할 때까지 클러스터에서 Gatekeeper 정책 시행이 중지됩니다. ValidatingAdmissionPolicies는 정책 컨트롤러 또는 게이트키퍼에 종속되지 않으므로 계속 적용됩니다.

  2. 커스텀 ConstraintTemplates를 사용하는 경우 설치하려는 Gatekeeper 버전의 gator 명령줄 도구를 사용하여 각 맞춤 템플릿 매니페스트를 테스트합니다.

    gator test --filename=TEMPLATE_FILE

    TEMPLATE_FILE를 ConstraintTemplate 매니페스트 파일의 경로로 바꿉니다. 정책 컨트롤러를 삭제하기 전에 Gatekeeper가 거부하는 커스텀 ConstraintTemplate을 수정합니다.

  3. GitOps 도구를 사용하여 Git 저장소에서 제약조건을 배포하는 경우 제약조건에서 사용하는 ConstraintTemplates를 준비하고 Gatekeeper를 설치할 때 저장소에 추가합니다. 그렇지 않으면 정책 컨트롤러를 삭제한 후 ConstraintTemplates가 더 이상 존재하지 않으므로 제약조건이 적용되지 않습니다.

  4. 정책 컨트롤러 삭제의 단계에 따라 정책 컨트롤러를 삭제합니다. 정책 컨트롤러를 계속 실행하는 클러스터에는 게이트키퍼를 설치하지 마세요. 둘 다 gatekeeper-system 네임스페이스, 동일한 CustomResourceDefinitions, 동일한 웹훅 이름을 사용합니다.

  5. 다음 섹션의 정책 컨트롤러와 다른 Gatekeeper 설정 표에서 선택한 설정을 사용하여 Helm을 통해 Gatekeeper를 설치합니다. 게이트키퍼를 설치하는 방법에 대한 자세한 내용은 게이트키퍼 문서의 설치를 참조하세요.

    Autopilot 클러스터에서는 GKE가 변형 웹훅에서 와일드 카드 규칙을 거부하므로 기본 Helm 차트 설치가 실패합니다. disableMutation: true Helm 값을 설정하거나 mutatingWebhookCustomRules Helm 값을 설정하여 변형자가 타겟팅하는 특정 리소스만 나열합니다. nodes, persistentvolumes, certificatesigningrequests 또는 tokenreviews 리소스를 포함하지 마세요.

  6. 백업 파일에서 다시 적용할 각 리소스의 다음 필드, 라벨, 주석을 삭제합니다.

    • status 필드
    • metadata 섹션의 resourceVersion, uid, creationTimestamp, generation, managedFields, ownerReferences 필드
    • kubectl.kubernetes.io/last-applied-configuration 주석
    • app.kubernetes.io/managed-by: anthospolicycontroller.googleapis.com 라벨 Fleet 수준 기본 구성 등으로 클러스터에서 정책 컨트롤러가 다시 사용 설정되면 이 라벨이 있는 리소스를 관리하고 수정하거나 삭제할 수 있습니다.
    • 키에 policycontroller. 프리픽스가 있는 라벨 및 주석

  7. 제약조건에서 사용하는 ConstraintTemplates를 적용한 후 게이트키퍼가 각 템플릿에 대해 CustomResourceDefinition을 만들었는지 확인합니다.

    kubectl get constrainttemplates \
    -o custom-columns='NAME:.metadata.name,CREATED:.status.created'

    모든 템플릿의 CREATED 열에 true 값이 표시되면 제약조건을 적용합니다.

정책 컨트롤러와 다른 Gatekeeper 설정

Gatekeeper를 설치하기 전에 Gatekeeper Helm 차트 기본값이 정책 컨트롤러와 다른 다음 표의 설정을 검토하세요.

정책 컨트롤러 기본값과 Gatekeeper Helm 차트 기본값 비교
설정 정책 컨트롤러 기본값 Gatekeeper Helm 차트 기본값 추천
변형 사용 설정하지 않는 한 사용 중지됨 사용 변형을 사용하지 않는 경우 disableMutation: true Helm 값을 설정합니다. Autopilot 클러스터에서는 disableMutation: true Helm 값을 설정하거나 와일드 카드 또는 제한된 리소스 없이 mutatingWebhookCustomRules Helm 값을 구성해야 합니다. 이러한 값 중 하나를 지정하지 않으면 GKE가 설치를 거부합니다.
네임스페이스 제외 gatekeeper-system 네임스페이스 및 exemptableNamespaces 목록의 네임스페이스 Gatekeeper가 설치된 네임스페이스 제외된 네임스페이스를 controllerManager.exemptNamespaces Helm 값에 추가합니다. Gatekeeper는 admission.gatekeeper.sh/ignore 라벨이 있는 네임스페이스가 예외가 아닌 한 해당 네임스페이스에 대한 변경사항을 거부합니다.
참조 데이터 참조 번들에 대해 자동으로 동기화됨 동기화되지 않음 참조 템플릿이 읽는 종류를 나열하는 Gatekeeper 구성 또는 SyncSet를 만듭니다. 이러한 종류가 data.inventory 객체에 동기화될 때까지 충돌 검사에서 위반 요청을 허용하고 K8sRequireNamespaceNetworkPolicies ConstraintTemplate과 같은 존재 검사에서 필수 리소스가 있는 경우에도 일치하는 모든 요청을 거부합니다.
ValidatingAdmissionPolicy 생성 사용 불가 CEL 코드가 포함된 템플릿에 사용 설정됨 정책 컨트롤러 템플릿에는 Rego만 포함되므로 ConstraintTemplates에 CEL을 추가하는 경우에만 Gatekeeper가 ValidatingAdmissionPolicies를 생성합니다. 웹훅에서 시행을 유지하려면 defaultCreateVAPForTemplates: false 및 defaultCreateVAPBindingForConstraints: false Helm 값을 설정합니다. 자세한 내용은 Gatekeeper 문서의 Kubernetes 검증 허용 정책과 통합을 참조하세요.
복제본 및 리소스 각 구성요소에 대한 복제본 1개, 메모리 한도 1,024MiB 리소스 한도가 다른 웹훅 복제본 3개 현재 사용량을 기준으로 복제본 수와 리소스 한도를 구성합니다.
이미지 Google 관리 레지스트리에서 가져옴 Docker Hub에서 가져옴(openpolicyagent/gatekeeper, openpolicyagent/gatekeeper-crds, curlimages/curl 이미지) 비공개 클러스터 또는 Binary Authorization을 시행하는 클러스터의 경우 세 이미지를 모두 Artifact Registry에 미러링하고 차트에서 이미지 값을 재정의합니다. curlimages/curl 이미지를 미러링하지 않는 경우 웹훅 프로브 작업을 사용 중지합니다.

기본적으로 게이트키퍼는 Prometheus 측정항목만 노출하며, 측정항목 이름은 정책 컨트롤러가 Cloud Monitoring으로 전송하는 이름과 다릅니다. 정책 컨트롤러 측정항목을 사용하는 대시보드 및 알림을 업데이트합니다.

변형 정책 마이그레이션

정책 컨트롤러에서 변형을 사용 설정한 경우 변형자를 나열합니다.

kubectl get assign,assignmetadata,assignimage,modifyset

각 변형자에 대해 다음 옵션 중 하나를 선택합니다.

  • MutatingAdmissionPolicy: GKE 버전 1.36 이상에서 MutatingAdmissionPolicy를 사용할 수 있습니다. ValidatingAdmissionPolicy와 마찬가지로 MutatingAdmissionPolicy는 CEL 표현식을 사용하며 웹훅 없이 API 서버에서 실행됩니다. Kubernetes는 ValidatingAdmissionPolicies 전에 모든 MutatingAdmissionPolicies를 실행하므로 함께 테스트하여 변형으로 인해 ValidatingAdmissionPolicy가 유효한 매니페스트를 거부하지 않는지 확인합니다. Autopilot 클러스터에서 GKE는 MutatingAdmissionPolicies에서 관리형 네임스페이스를 제외합니다. 변형 정책에 대한 자세한 내용은 Kubernetes 문서의 변형 허용 정책을 참조하세요.
  • 자체 관리형 Gatekeeper: Standard 클러스터에서 Gatekeeper는 기본적으로 변형을 사용 설정하므로 변형자가 변경 없이 작동합니다. Autopilot 클러스터에서는 게이트키퍼 차트에서 mutatingWebhookCustomRules Helm 값을 설정하여 와일드 카드 규칙 대신 변형자가 타겟팅하는 특정 리소스를 나열해야 합니다. 자세한 내용은 GKE Autopilot 보안 조치를 참조하세요. Gatekeeper를 설치한 후 제약조건과 마찬가지로 변형자 백업 파일에서 정책 컨트롤러 메타데이터를 삭제하고 변형자를 다시 적용합니다.

빌드 파이프라인의 정책 검사 업데이트

빌드 파이프라인은 배포 전에 정책 컨트롤러 제약조건에 따라 매니페스트를 확인할 수 있습니다. 예를 들어 파이프라인은 kpt의 gatekeeper 함수 또는 gator 명령줄 도구를 사용할 수 있습니다. 자세한 내용은 CI 파이프라인에서 회사 정책에 따라 앱 유효성 검사를 참조하세요.

파이프라인에서 매니페스트를 확인하는 경우 대체 항목에 맞게 업데이트합니다.

  • Gatekeeper를 사용하는 경우 파이프라인을 유지할 수 있습니다. 정리된 Gatekeeper ConstraintTemplate 및 제약조건 매니페스트가 포함된 저장소 또는 디렉터리를 참조하도록 gator 또는 kpt 명령어의 파일 또는 디렉터리 경로를 업데이트합니다.

  • ValidatingAdmissionPolicies를 사용하는 경우 이러한 도구는 정책을 평가하지 않습니다. 대신 Deny 작업을 사용하는 ValidatingAdmissionPolicies 및 ValidatingAdmissionPolicyBindings가 있는 테스트 클러스터에 대해 서버 측 드라이 런을 실행합니다.

    kubectl apply --dry-run=server -f MANIFEST_DIRECTORY

    MANIFEST_DIRECTORY을 매니페스트가 포함된 디렉터리로 바꿉니다. ValidatingAdmissionPolicy가 매니페스트를 거부하면 명령어가 실패합니다.

위반 신고 대체

ValidatingAdmissionPolicy에는 대시보드가 포함되지 않으며 클러스터에 이미 있는 리소스를 감사하지 않습니다. 대신 다음 메서드를 사용하세요.

  • 경고: ValidatingAdmissionPolicyBinding에서 Warn 작업을 사용하는 경우 API 서버는 요청을 보낸 클라이언트(예: kubectl 명령줄 도구)에 경고를 반환합니다. 배포의 포드와 같이 컨트롤러가 만드는 포드의 경우 컨트롤러가 경고를 수신합니다.

  • 감사 로그: ValidatingAdmissionPolicyBinding이 Audit 작업을 사용하는 경우 API 서버는 실패한 각 검증에 대해 감사 로그 항목에 주석을 추가합니다. GKE는 Cloud Logging의 관리자 활동 감사 로그에 생성, 업데이트, 삭제 요청을 작성합니다. 실패한 검증을 찾으려면 로그 탐색기에서 다음 쿼리를 실행합니다.

    resource.type="k8s_cluster"
logName:"cloudaudit.googleapis.com%2Factivity"
labels."validation.policy.admission.k8s.io/validation_failure":*

기존 리소스에 대한 규정 준수 보고서로 dryrun 시정 조치가 있는 제약조건을 사용하는 경우 ValidatingAdmissionPolicies는 해당 보고서를 대체할 수 없습니다. 자체 관리형 게이트키퍼에 정책을 유지합니다. 이 게이트키퍼의 감사 컨트롤러는 일정에 따라 기존 리소스를 확인합니다.

정책 컨트롤러 삭제

클러스터에서 정책 컨트롤러를 삭제하기 전에 다음 작업을 완료하세요.

  • ValidatingAdmissionPolicies 또는 포드 보안 허용으로 마이그레이션한 정책이 적용되고 ConstraintTemplates, 제약조건, 변형자의 백업이 있는지 확인합니다. 정책 컨트롤러를 삭제하면 CustomResourceDefinition이 삭제되며, 이로 인해 사용자가 만든 것을 포함하여 클러스터의 모든 ConstraintTemplate, 제약조건, 변형자가 삭제됩니다.
  • 구성 동기화 또는 Argo CD와 같은 GitOps 도구를 사용하여 Git 저장소에서 제약조건을 배포하는 경우 저장소에서 대체된 제약조건을 삭제합니다. 제약조건이 클러스터에서 삭제되었는지 확인합니다.
  • 선택사항: 정책 컨트롤러 웹훅에 종속되는 항목이 없는지 확인하려면 먼저 정책 컨트롤러를 정지합니다. 정지하면 웹훅 구성만 삭제되며 복원할 수 있습니다.

정책 컨트롤러를 삭제하려면 다음 단계를 따르세요.

  1. 클러스터에서 정책 컨트롤러를 제거합니다.

    gcloud container fleet policycontroller disable \
    --memberships=MEMBERSHIP_NAME \
    --project=PROJECT_ID

    다음을 바꿉니다.

    • MEMBERSHIP_NAME: 정책 컨트롤러를 제거할 등록된 클러스터의 멤버십 이름입니다. 여러 클러스터에서 정책 컨트롤러를 제거하려면 쉼표로 구분된 멤버십 이름 목록을 지정하거나 --memberships=MEMBERSHIP_NAME 플래그를 --all-memberships 플래그로 바꿉니다.
    • PROJECT_ID: Fleet 호스트 프로젝트의 ID입니다.

  2. 정책 컨트롤러가 클러스터에서 제거되었는지 확인합니다.

    gcloud container fleet policycontroller describe \
    --memberships=MEMBERSHIP_NAME \
    --project=PROJECT_ID \
    --format="yaml(membershipStates)"

    각 멤버십의 최상위 policycontroller.state 필드 값이 DECOMMISSIONING가 아닌 NOT_INSTALLED가 될 때까지 기다립니다. CustomResourceDefinition 삭제가 완료되기 전에 개별 componentStates 항목이 NOT_INSTALLED 상태에 도달합니다.

    자체 관리형 Gatekeeper를 설치하려면 gatekeeper-system 네임스페이스가 더 이상 존재하지 않는지 확인합니다.

    kubectl get namespace gatekeeper-system

    gatekeeper-system 네임스페이스를 찾을 수 없다는 출력이 표시될 때까지 기다립니다.

  3. 선택사항: 나중에 등록하는 클러스터에 정책 컨트롤러가 적용되지 않도록 하려면 Fleet 수준 기본 구성을 삭제합니다.

    gcloud container fleet policycontroller enable \
    --no-fleet-default-member-config \
    --project=PROJECT_ID

    이 명령어는 기본 구성만 삭제합니다. 클러스터에 정책 컨트롤러를 설치하지 않습니다.

Fleet 외부의 클러스터에서 정책 컨트롤러 삭제

gcloud container fleet policycontroller disable 명령어는 Fleet에서 관리하는 클러스터에서만 정책 컨트롤러를 삭제합니다. 클러스터는 다음과 같은 경우 Fleet 관리 없이 정책 컨트롤러를 실행할 수 있습니다.

  • ConfigManagement Operator를 사용하여 정책 컨트롤러를 설치했습니다.
  • 정책 컨트롤러가 제거를 완료하기 전에 Fleet에서 클러스터를 등록 취소했거나 gcloud container fleet policycontroller detach 명령어를 실행했습니다.

이러한 클러스터에서 정책 컨트롤러를 삭제하려면 클러스터를 Fleet 관리로 전환한 후 정책 컨트롤러를 제거합니다.

  1. 정책 인벤토리 및 분류에 설명된 대로 ConstraintTemplates, 제약조건, 동기화 구성, 변형자를 백업합니다. ConfigManagement Operator 설치에서 가져온 백업에서 메타데이터를 삭제할 때 ownerReferences 필드 및 policycontroller.* 메타데이터 외에도 configmanagement.gke.io/* 및 k8s-app: kubernetes-config-management 라벨을 삭제합니다.

  2. ConfigManagement Operator를 사용하여 정책 컨트롤러를 설치한 경우 클러스터의 ConfigManagement 커스텀 리소스에서 policyController 필드를 삭제합니다. 조정이 완료될 때까지 기다립니다. 조정에는 약 2분 정도 걸릴 수 있습니다. 그런 다음 gatekeeper-system 네임스페이스가 여전히 있는지 확인합니다.

    kubectl get namespace gatekeeper-system

    ConfigManagement Operator 버전 1.17 이하에서는 policyController 필드를 삭제하면 정책 컨트롤러가 자동으로 제거됩니다. gatekeeper-system 네임스페이스를 찾을 수 없으면 이 섹션의 나머지 단계를 건너뜁니다. ConfigManagement Operator 버전 1.18 이상에서는 gatekeeper-system 네임스페이스가 클러스터에 남아 있으므로 다음 단계를 진행합니다.

  3. 클러스터가 Fleet에 등록되지 않은 경우 등록합니다. 자세한 내용은 Google Cloud 의 클러스터를 Fleet에 등록을 참조하세요.

  4. 클러스터에서 변형이 사용 설정되어 있는지 확인합니다.

    kubectl get mutatingwebhookconfiguration \
    gatekeeper-mutating-webhook-configuration

  5. 클러스터 멤버십에서 정책 컨트롤러를 사용 설정하여 Fleet에서 기존 설치 관리를 인계받도록 합니다. 위 명령어가 gatekeeper-mutating-webhook-configuration 리소스를 반환한 경우 Fleet에서 클러스터 범위 변형 리소스를 채택하고 나중에 삭제하도록 --mutation 플래그를 포함합니다.

    gcloud container fleet policycontroller enable \
    --memberships=MEMBERSHIP_NAME \
    --project=PROJECT_ID

    다음을 바꿉니다.

    • MEMBERSHIP_NAME: 등록된 클러스터의 멤버십 이름입니다.
    • PROJECT_ID: Fleet 호스트 프로젝트의 ID입니다.

  6. 멤버십의 policycontroller.state 필드 값이 ACTIVE가 될 때까지 기다립니다.

    gcloud container fleet policycontroller describe \
    --memberships=MEMBERSHIP_NAME \
    --project=PROJECT_ID \
    --format="yaml(membershipStates)"

  7. 정책 컨트롤러 삭제의 단계에 따라 정책 컨트롤러를 제거합니다. 자체 관리형 Gatekeeper를 설치하지 않는 경우 gatekeeper-system 네임스페이스가 삭제된 후 남아 있는 제약조건 CustomResourceDefinitions를 삭제합니다.

    kubectl get crd -o name \
    | grep '\.constraints\.gatekeeper\.sh$' \
    | xargs -r kubectl delete

  8. 선택사항: 이 절차를 완료하기 위해서만 클러스터를 등록한 경우 describe 명령어가 멤버십의 NOT_INSTALLED 상태를 표시한 후 등록을 취소합니다. --enable-fleet 플래그를 사용하여 등록한 클러스터의 경우 gcloud container fleet memberships unregister 명령어 대신 --clear-fleet-project 플래그와 함께 gcloud container clusters update 명령어를 실행합니다. 자세한 내용은 클러스터 등록 취소를 참조하세요.

다음 단계