5.4. 사용자 정의 리소스 정의(CRD) 업그레이드 안전


클러스터 확장 프로그램에서 제공하는 사용자 지정 리소스 정의(CRD)를 업데이트하면 Operator Lifecycle Manager(OLM) v1이 CRD 업그레이드 안전 사전 검사를 실행하여 해당 CRD의 이전 버전과의 하위 호환성을 보장합니다. CRD 업데이트는 변경 사항이 클러스터에서 진행되기 전에 유효성 검사를 통과해야 합니다.

5.4.1. 금지된 CRD 업그레이드 변경

기존 사용자 정의 리소스 정의(CRD)에 대한 다음과 같은 변경 사항은 CRD 업그레이드 안전 사전 검사에서 발견되어 업그레이드가 방지됩니다.

  • 기존 CRD 버전에 새로운 필수 필드가 추가되었습니다.
  • 기존 버전의 CRD에서 기존 필드가 제거되었습니다.
  • 기존 버전의 CRD에서 기존 필드 유형이 변경되었습니다.
  • 이전에 기본값이 없었던 필드에 새로운 기본값이 추가되었습니다.
  • 필드의 기본값이 변경됩니다
  • 필드의 기존 기본값이 제거됩니다.
  • 이전에 열거형 제한이 없었던 기존 필드에 새로운 열거형 제한이 추가됩니다.
  • 기존 필드의 기존 enum 값이 제거됩니다.
  • 기존 필드의 최소값이 기존 버전에서 증가합니다.
  • 기존 버전에서는 기존 필드의 최대값이 감소합니다.
  • 최소 또는 최대 필드 제약 조건이 이전에 제약 조건이 없었던 필드에 추가되었습니다.
참고

최소값과 최대값 변경 규칙은 minimum , minLength , minProperties , minItems , maximum , maxLength , maxPropertiesmaxItems 제약 조건에 적용됩니다.

기존 CRD에 대한 다음과 같은 변경 사항은 CRD 업그레이드 안전 사전 검사에서 보고되며 업그레이드를 방지하지만 해당 작업은 기술적으로 Kubernetes API 서버에서 처리합니다.

  • 범위가 클러스터 에서 네임스페이스 로 또는 네임스페이스 에서 클러스터 로 변경됩니다.
  • 저장된 CRD의 기존 버전이 제거됩니다.

CRD 업그레이드 안전 사전 검사에서 금지된 업그레이드 변경 사항 중 하나를 발견하면 CRD 업그레이드에서 감지된 각 금지된 변경 사항에 대한 오류가 기록됩니다.

작은 정보

CRD 변경 사항이 금지된 변경 범주에 속하지 않지만 허용된 변경 사항으로 적절히 감지할 수 없는 경우, CRD 업그레이드 안전 사전 검사에서 업그레이드가 차단되고 "알 수 없는 변경 사항"에 대한 오류가 기록됩니다.

5.4.2. 허용된 CRD 업그레이드 변경 사항

기존 사용자 정의 리소스 정의(CRD)에 대한 다음 변경 사항은 이전 버전과의 호환성을 위해 안전하며 CRD 업그레이드 안전 사전 검사로 인해 업그레이드가 중단되지 않습니다.

  • 필드에서 허용되는 열거형 값 목록에 새 열거형 값 추가
  • 기존 필수 필드가 기존 버전에서 선택 사항으로 변경되었습니다.
  • 기존 버전에서 기존 필드의 최소값이 감소합니다.
  • 기존 버전에서 기존 필드의 최대값이 증가합니다.
  • 기존 버전을 수정하지 않고 새 버전의 CRD가 추가되었습니다.

5.4.3. CRD 업그레이드 안전 사전 비행 확인 비활성화

사용자 정의 리소스 정의(CRD) 업그레이드 안전 사전 검사를 비활성화할 수 있습니다. CRD를 제공하는 ClusterExtension 개체에서 install.preflight.crdUpgradeSafety.enforcement 필드를 None 값으로 설정합니다.

주의

CRD 업그레이드 안전 사전 검사를 비활성화하면 저장된 CRD 버전과의 하위 호환성이 끊어질 수 있으며 클러스터에서 다른 의도치 않은 결과가 발생할 수 있습니다.

개별 필드 검증기를 비활성화할 수 없습니다. CRD 업그레이드 안전 사전 검사를 비활성화하면 모든 필드 검증기가 비활성화됩니다.

참고

Operator Lifecycle Manager(OLM) v1에서 CRD 업그레이드 안전 사전 검사를 비활성화해도 Kubernetes API 서버는 여전히 다음 작업을 차단합니다.

  • 클러스터 에서 네임스페이스 로 또는 네임스페이스 에서 클러스터 로 범위 변경
  • CRD의 기존 저장된 버전 제거

사전 요구 사항

  • 클러스터 확장이 설치되어 있습니다.

프로세스

  1. CRD의 ClusterExtension 객체를 편집합니다.

    $ oc edit clusterextension <clusterextension_name>
    Copy to Clipboard Toggle word wrap
  2. install.preflight.crdUpgradeSafety.enforcement 필드를 없음 으로 설정합니다.

    ClusterExtension 오브젝트의 예

    apiVersion: olm.operatorframework.io/v1
    kind: ClusterExtension
    metadata:
      name: clusterextension-sample
    spec:
      namespace: default
      serviceAccount:
        name: sa-example
      source:
        sourceType: "Catalog"
        catalog:
          packageName: argocd-operator
          version: 0.6.0
      install:
        preflight:
          crdUpgradeSafety:
            enforcement: None
    Copy to Clipboard Toggle word wrap

5.4.4. 안전하지 않은 CRD 변경의 예

다음 예제에서는 CRD 업그레이드 안전 사전 검사에서 발견될 수 있는 사용자 정의 리소스 정의(CRD) 섹션의 특정 변경 사항을 보여줍니다.

다음 예제에서는 다음 시작 상태의 CRD 객체를 고려합니다.

예 5.19. CRD 객체 예

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.13.0
  name: example.test.example.com
spec:
  group: test.example.com
  names:
    kind: Sample
    listKind: SampleList
    plural: samples
    singular: sample
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        properties:
          apiVersion:
            type: string
          kind:
            type: string
          metadata:
            type: object
          spec:
            type: object
          status:
            type: object
          pollInterval:
            type: string
        type: object
    served: true
    storage: true
    subresources:
      status: {}
Copy to Clipboard Toggle word wrap

5.4.4.1. 범위 변경

다음 사용자 정의 리소스 정의(CRD) 예에서 범위 필드는 네임스페이스 에서 클러스터 로 변경되었습니다.

예 5.20. CRD의 범위 변경 예

    spec:
      group: test.example.com
      names:
        kind: Sample
        listKind: SampleList
        plural: samples
        singular: sample
      scope: Cluster
      versions:
      - name: v1alpha1
Copy to Clipboard Toggle word wrap

예 5.21. 오류 출력 예

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "NoScopeChange" validation failed: scope changed from "Namespaced" to "Cluster"
Copy to Clipboard Toggle word wrap

5.4.4.2. 저장된 버전 제거

다음 사용자 정의 리소스 정의(CRD) 예에서는 기존에 저장된 버전인 v1alpha1 이 제거됩니다.

예 5.22. CRD에 저장된 버전 제거 예

      versions:
      - name: v1alpha2
        schema:
          openAPIV3Schema:
            properties:
              apiVersion:
                type: string
              kind:
                type: string
              metadata:
                type: object
              spec:
                type: object
              status:
                type: object
              pollInterval:
                type: string
            type: object
Copy to Clipboard Toggle word wrap

예 5.23. 오류 출력 예

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "NoStoredVersionRemoved" validation failed: stored version "v1alpha1" removed
Copy to Clipboard Toggle word wrap

5.4.4.3. 기존 필드 제거

다음 사용자 정의 리소스 정의(CRD) 예에서 pollInterval 속성 필드는 v1alpha1 스키마에서 제거되었습니다.

예 5.24. CRD에서 기존 필드 제거 예

      versions:
      - name: v1alpha1
        schema:
          openAPIV3Schema:
            properties:
              apiVersion:
                type: string
              kind:
                type: string
              metadata:
                type: object
              spec:
                type: object
              status:
                type: object
            type: object
Copy to Clipboard Toggle word wrap

예 5.25. 오류 출력 예

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "NoExistingFieldRemoved" validation failed: crd/test.example.com version/v1alpha1 field/^.spec.pollInterval may not be removed
Copy to Clipboard Toggle word wrap

5.4.4.4. 필수 필드 추가

다음 사용자 정의 리소스 정의(CRD) 예에서 pollInterval 속성은 필수 필드로 변경되었습니다.

예 5.26. CRD에 필수 필드 추가 예시

      versions:
      - name: v1alpha2
        schema:
          openAPIV3Schema:
            properties:
              apiVersion:
                type: string
              kind:
                type: string
              metadata:
                type: object
              spec:
                type: object
              status:
                type: object
              pollInterval:
                type: string
            type: object
            required:
            - pollInterval
Copy to Clipboard Toggle word wrap

예 5.27. 오류 출력 예

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "ChangeValidator" validation failed: version "v1alpha1", field "^": new required fields added: [pollInterval]
Copy to Clipboard Toggle word wrap
맨 위로 이동
Red Hat logoGithubredditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2025 Red Hat