4장. 카탈로그


4.1. 파일 기반 카탈로그

중요

OLM(Operator Lifecycle Manager) v1은 기술 프리뷰 기능 전용입니다. 기술 프리뷰 기능은 Red Hat 프로덕션 서비스 수준 계약(SLA)에서 지원되지 않으며 기능적으로 완전하지 않을 수 있습니다. 따라서 프로덕션 환경에서 사용하는 것은 권장하지 않습니다. 이러한 기능을 사용하면 향후 제품 기능을 조기에 이용할 수 있어 개발 과정에서 고객이 기능을 테스트하고 피드백을 제공할 수 있습니다.

Red Hat 기술 프리뷰 기능의 지원 범위에 대한 자세한 내용은 기술 프리뷰 기능 지원 범위를 참조하십시오.

OpenShift Container Platform의 OLM(Operator Lifecycle Manager) v1은 클러스터에서 Operator를 포함한 클러스터 확장 검색 및 소싱을 위해 파일 기반 카탈로그 를 지원합니다.

중요

현재 OLM(Operator Lifecycle Manager) v1은 Red Hat 제공 Operator 카탈로그와 같은 프라이빗 레지스트리를 인증할 수 없습니다. 이것은 확인된 문제입니다. 결과적으로 Red Hat Operator 카탈로그를 설치하는 데 사용하는 OLM v1 절차가 작동하지 않습니다. (OCPBUGS-36364)

4.1.1. 주요 사항

파일 기반 카탈로그는 OLM(Operator Lifecycle Manager) 카탈로그 형식의 최신 버전입니다. 일반 텍스트 기반(JSON 또는 YAML)과 이전 SQLite 데이터베이스 형식의 선언적 구성 진화이며 완전히 이전 버전과 호환됩니다. 이 형식의 목표는 Operator 카탈로그 편집, 구성 가능성 및 확장성을 활성화하는 것입니다.

편집

파일 기반 카탈로그를 사용하면 카탈로그 내용과 상호 작용하는 사용자가 형식을 직접 변경하고 변경 사항이 유효한지 확인할 수 있습니다. 이 형식은 일반 텍스트 JSON 또는 YAML이므로 카탈로그 유지 관리자는 jq CLI와 같이 널리 알려진 지원되는 JSON 또는 YAML 툴을 사용하여 카탈로그 메타데이터를 쉽게 조작할 수 있습니다.

이 편집 기능을 사용하면 다음과 같은 기능 및 사용자 정의 확장 기능을 사용할 수 있습니다.

  • 기존 번들을 새 채널로 승격
  • 패키지의 기본 채널 변경
  • 업그레이드 에지 추가, 업데이트 및 제거를 위한 사용자 정의 알고리즘
호환성

파일 기반 카탈로그는 카탈로그 구성이 가능한 임의의 디렉터리 계층 구조에 저장됩니다. 예를 들어 별도의 파일 기반 카탈로그 디렉터리인 catalogAcatalogB를 고려해 보십시오. 카탈로그 관리자는 새 디렉토리 catalogC를 만들고 catalogAcatalogB를 복사하여 새로 결합된 카탈로그를 만들 수 있습니다.

이 구성 가능성을 통해 분산된 카탈로그를 사용할 수 있습니다. 이 형식을 사용하면 Operator 작성자가 Operator별 카탈로그를 유지 관리할 수 있으며 유지 관리자가 개별 Operator 카탈로그로 구성된 카탈로그를 단순하게 빌드할 수 있습니다. 파일 기반 카탈로그는 하나의 카탈로그의 하위 집합을 추출하거나 두 개의 카탈로그를 조합하여 다른 여러 카탈로그를 결합하여 구성할 수 있습니다.

참고

패키지 내의 중복 패키지 및 중복 번들은 허용되지 않습니다. opm validate 명령은 중복이 발견되면 오류를 반환합니다.

Operator 작성자는 Operator, 해당 종속 항목 및 업그레이드 호환성에 가장 익숙하므로 자체 Operator별 카탈로그를 유지 관리하고 해당 콘텐츠를 직접 제어할 수 있습니다. Operator 작성자는 파일 기반 카탈로그를 사용하여 카탈로그에서 패키지를 빌드하고 유지 관리하는 작업을 소유합니다. 그러나 복합 카탈로그 유지 관리자만 카탈로그의 패키지를 큐레이션하고 카탈로그를 사용자에게 게시하는 작업만 소유합니다.

확장성

파일 기반 카탈로그 사양은 카탈로그의 하위 수준 형식입니다. 카탈로그 유지 관리자는 낮은 수준의 형식으로 직접 유지 관리할 수 있지만, 카탈로그 유지 관리자는 고유한 사용자 지정 툴링에서 원하는 수의 변경을 수행할 수 있는 확장 기능을 구축할 수 있습니다.

예를 들어 툴은 에지 업그레이드를 위해 높은 수준의 API (예:(mode=semver)를 낮은 수준의 파일 기반 카탈로그 형식으로 변환할 수 있습니다. 또는 카탈로그 유지 관리자는 특정 기준을 충족하는 번들에 새 속성을 추가하여 모든 번들 메타데이터를 사용자 지정해야 할 수 있습니다.

이러한 확장성을 통해 향후 OpenShift Container Platform 릴리스를 위해 하위 수준 API에서 추가 공식 툴을 개발할 수 있지만, 카탈로그 유지 관리자도 이러한 기능을 사용할 수 있다는 것이 가장 큰 장점입니다.

4.1.2. 디렉토리 구조

디렉토리 기반 파일 시스템에서 파일 기반 카탈로그를 저장하고 로드할 수 있습니다. opm CLI는 루트 디렉토리로 이동하고 하위 디렉토리로 재귀하여 카탈로그를 로드합니다. CLI는 발견한 모든 파일을 로드 시도하여 오류가 발생하면 실패합니다.

비카탈로그 파일은 .gitignore 파일과 패턴 및 우선 순위에 대해 동일한 규칙이 있는 .indexignore 파일을 사용하여 무시할 수 있습니다.

.indexignore 파일의 예

# Ignore everything except non-object .json and .yaml files
**/*
!*.json
!*.yaml
**/objects/*.json
**/objects/*.yaml

카탈로그 유지 관리자는 원하는 레이아웃을 선택할 수 있는 유연성을 가지지만 각 패키지의 파일 기반 카탈로그 Blob을 별도의 하위 디렉터리에 저장하는 것이 좋습니다. 각 개별 파일은 JSON 또는 YAML일 수 있습니다. 카탈로그의 모든 파일에서 동일한 형식을 사용할 필요는 없습니다.

기본 권장 구조

catalog
├── packageA
│   └── index.yaml
├── packageB
│   ├── .indexignore
│   ├── index.yaml
│   └── objects
│       └── packageB.v0.1.0.clusterserviceversion.yaml
└── packageC
    └── index.json
    └── deprecations.yaml

이 권장 구조에는 디렉터리 계층 구조의 각 하위 디렉터리가 자체 포함된 카탈로그이므로 카탈로그 구성, 검색 및 탐색 간단한 파일 시스템 작업이 가능합니다. 카탈로그는 상위 카탈로그의 루트 디렉터리에 복사하여 상위 카탈로그에 포함할 수도 있습니다.

4.1.3. 스키마

파일 기반 카탈로그는 임의의 스키마로 확장할 수 있는 CUE 언어 사양을 기반으로 하는 형식을 사용합니다. 다음 _Meta CUE 스키마는 모든 파일 기반 카탈로그 Blob이 준수해야 하는 형식을 정의합니다.

_Meta 스키마

_Meta: {
  // schema is required and must be a non-empty string
  schema: string & !=""

  // package is optional, but if it's defined, it must be a non-empty string
  package?: string & !=""

  // properties is optional, but if it's defined, it must be a list of 0 or more properties
  properties?: [... #Property]
}

#Property: {
  // type is required
  type: string & !=""

  // value is required, and it must not be null
  value: !=null
}

참고

이 사양에 나열된 CUE 스키마는 완전한 것으로 간주되어서는 안 됩니다. opm validate 명령에는 CUE에서 간결하게 표현하기가 어렵거나 불가능한 추가 유효성 검사가 있습니다.

OLM(Operator Lifecycle Manager) 카탈로그에서는 현재 OLM의 기존 패키지 및 번들 개념에 해당하는 3개의 스키마 (olm.package, olm.channel, olm.bundle)를 사용합니다.

카탈로그의 각 Operator 패키지에는 정확히 하나의 olm.package blob, 하나 이상의 olm.channel blob, 하나 이상의 olm.bundle blob이 필요합니다.

참고

모든 olm.* 스키마는 OLM 정의 스키마용으로 예약됩니다. 사용자 지정 스키마는 소유한 도메인과 같이 고유한 접두사를 사용해야 합니다.

4.1.3.1. olm.package 스키마

olm.package 스키마는 Operator에 대한 패키지 수준 메타데이터를 정의합니다. 이에는 이름, 설명, 기본 채널 및 아이콘이 포함됩니다.

예 4.1. olm.package 스키마

#Package: {
  schema: "olm.package"

  // Package name
  name: string & !=""

  // A description of the package
  description?: string

  // The package's default channel
  defaultChannel: string & !=""

  // An optional icon
  icon?: {
    base64data: string
    mediatype:  string
  }
}

4.1.3.2. olm.channel 스키마

olm.channel 스키마는 패키지 내의 채널, 채널의 멤버인 번들 항목 및 해당 번들의 업그레이드 에지를 정의합니다.

번들 항목이 여러 olm.channel blob의 에지를 나타내는 경우 채널당 한 번만 표시될 수 있습니다.

항목의 값이 이 카탈로그 또는 다른 카탈로그에서 찾을 수 없는 다른 번들 이름을 참조하는 것은 유효합니다. 그러나 여러 헤드가 없는 채널과 같이 다른 모든 채널 불변성은 true를 유지해야 합니다.

예 4.2. olm.channel 스키마

#Channel: {
  schema: "olm.channel"
  package: string & !=""
  name: string & !=""
  entries: [...#ChannelEntry]
}

#ChannelEntry: {
  // name is required. It is the name of an `olm.bundle` that
  // is present in the channel.
  name: string & !=""

  // replaces is optional. It is the name of bundle that is replaced
  // by this entry. It does not have to be present in the entry list.
  replaces?: string & !=""

  // skips is optional. It is a list of bundle names that are skipped by
  // this entry. The skipped bundles do not have to be present in the
  // entry list.
  skips?: [...string & !=""]

  // skipRange is optional. It is the semver range of bundle versions
  // that are skipped by this entry.
  skipRange?: string & !=""
}
주의

skipRange 필드를 사용하는 경우 건너뛰는 Operator 버전이 업데이트 그래프에서 정리되며 Subscription 오브젝트의 spec.startingCSV 속성이 있는 사용자가 더 오래 설치할 수 있습니다.

skipRangereplaces 필드를 모두 사용하여 향후 설치를 위해 사용자가 이전에 설치한 버전을 사용할 수 있는 동안 Operator를 점진적으로 업데이트할 수 있습니다. replaces 필드가 해당 Operator 버전의 즉시 이전 버전을 가리키는지 확인합니다.

4.1.3.3. olm.bundle 스키마

예 4.3. olm.bundle 스키마

#Bundle: {
  schema: "olm.bundle"
  package: string & !=""
  name: string & !=""
  image: string & !=""
  properties: [...#Property]
  relatedImages?: [...#RelatedImage]
}

#Property: {
  // type is required
  type: string & !=""

  // value is required, and it must not be null
  value: !=null
}

#RelatedImage: {
  // image is the image reference
  image: string & !=""

  // name is an optional descriptive name for an image that
  // helps identify its purpose in the context of the bundle
  name?: string & !=""
}

4.1.3.4. olm.deprecations 스키마

선택적 olm.deprecations 스키마는 카탈로그의 패키지, 번들 및 채널에 대한 사용 중단 정보를 정의합니다. Operator 작성자는 이 스키마를 사용하여 카탈로그에서 해당 Operator를 실행하는 사용자에게 지원 상태 및 권장 업그레이드 경로와 같은 Operator에 대한 관련 메시지를 제공할 수 있습니다.

이 스키마가 정의되면 OpenShift Container Platform 웹 콘솔은 OperatorHub의 사전 및 설치 후 페이지에서 사용자 정의 사용 중단 메시지를 포함하여 Operator의 영향을 받는 요소에 대한 경고 배지를 표시합니다.

olm.deprecations 스키마 항목에는 사용 중단 범위를 나타내는 다음 참조 유형 중 하나 이상이 포함되어 있습니다. Operator가 설치되면 지정된 메시지를 관련 Subscription 오브젝트에서 상태 조건으로 볼 수 있습니다.

표 4.1. 사용 중단 참조 유형
유형범위상태 조건

olm.package

전체 패키지를 나타냅니다.

PackageDeprecated

olm.channel

하나의 채널을 나타냅니다.

ChannelDeprecated

olm.bundle

하나의 번들 버전을 나타냅니다.

BundleDeprecated

참조 유형에는 다음 예에 설명된 대로 자체 요구 사항이 있습니다.

예 4.4. 각 참조 유형이 있는 olm.deprecations 스키마의 예

schema: olm.deprecations
package: my-operator 1
entries:
  - reference:
      schema: olm.package 2
    message: | 3
    The 'my-operator' package is end of life. Please use the
    'my-operator-new' package for support.
  - reference:
      schema: olm.channel
      name: alpha 4
    message: |
    The 'alpha' channel is no longer supported. Please switch to the
    'stable' channel.
  - reference:
      schema: olm.bundle
      name: my-operator.v1.68.0 5
    message: |
    my-operator.v1.68.0 is deprecated. Uninstall my-operator.v1.68.0 and
    install my-operator.v1.72.0 for support.
1
각 사용 중단 스키마에는 패키지 값이 있어야 하며 해당 패키지 참조는 카탈로그 전체에서 고유해야 합니다. 연결된 이름 필드가 없어야 합니다.
2
olm.package 스키마는 스키마의 앞부분에서 정의한 package 필드에 의해 결정되므로 name 필드를 포함하지 않아야 합니다.
3
모든 참조 유형에 대한 모든 메시지 필드는 0이 아닌 길이이고 불투명 텍스트 Blob으로 표현되어야 합니다.
4
olm.channel 스키마의 name 필드가 필요합니다.
5
olm.bundle 스키마의 name 필드가 필요합니다.
참고

사용 중단 기능은 중복 사용 중단(예: 패키지 대 채널 대 번들)을 고려하지 않습니다.

Operator 작성자는 olm.deprecations 스키마 항목을 패키지의 index.yaml 파일과 동일한 디렉터리에 deprecations.yaml 파일로 저장할 수 있습니다.

사용 중단이 있는 카탈로그의 디렉터리 구조 예

my-catalog
└── my-operator
    ├── index.yaml
    └── deprecations.yaml

4.1.4. 속성

속성은 파일 기반 카탈로그 스키마에 연결할 수 있는 임의 메타데이터입니다. type 필드는 value 필드의 의미 및 구문 의미를 효과적으로 지정하는 문자열입니다. 이 값은 임의의 JSON 또는 YAML일 수 있습니다.

OLM은 예약된 olm.* 접두사를 사용하여 몇 가지 속성 유형을 다시 정의합니다.

4.1.4.1. olm.package 속성

olm.package 속성은 패키지 이름과 버전을 정의합니다. 이는 번들의 필수 속성이며, 이러한 속성 중 정확히 하나가 있어야 합니다. packageName 필드는 번들의 최상위 package 필드와 일치해야 하며 version 필드는 유효한 의미 체계 버전이어야 합니다.

예 4.5. olm.package 속성

#PropertyPackage: {
  type: "olm.package"
  value: {
    packageName: string & !=""
    version: string & !=""
  }
}

4.1.4.2. olm.gvk 속성

olm.gvk 속성은 이 번들에서 제공하는 Kubernetes API의 GVK(그룹/버전/종류)를 정의합니다. 이 속성은 OLM에서 이 속성이 포함된 번들을 필수 API와 동일한 GVK를 나열하는 다른 번들의 종속성으로 확인하는 데 사용됩니다. GVK는 Kubernetes GVK 검증을 준수해야 합니다.

예 4.6. olm.gvk 속성

#PropertyGVK: {
  type: "olm.gvk"
  value: {
    group: string & !=""
    version: string & !=""
    kind: string & !=""
  }
}

4.1.4.3. olm.package.required

olm.package.required 속성은 이 번들에 필요한 다른 패키지의 패키지 이름 및 버전 범위를 정의합니다. 번들 목록이 필요한 모든 패키지 속성에 대해 OLM은 나열된 패키지 및 필수 버전 범위에 대한 클러스터에 Operator가 설치되어 있는지 확인합니다. versionRange 필드는 유효한 의미 버전(semver) 범위여야 합니다.

예 4.7. olm.package.required 속성

#PropertyPackageRequired: {
  type: "olm.package.required"
  value: {
    packageName: string & !=""
    versionRange: string & !=""
  }
}

4.1.4.4. olm.gvk.required

olm.gvk.required 속성은 이 번들에 필요한 Kubernetes API의 GVK(그룹/버전/종류)를 정의합니다. 번들 목록이 필요한 모든 GVK 속성에 대해 OLM은 이를 제공하는 클러스터에 Operator가 설치되어 있는지 확인합니다. GVK는 Kubernetes GVK 검증을 준수해야 합니다.

예 4.8. olm.gvk.required 속성

#PropertyGVKRequired: {
  type: "olm.gvk.required"
  value: {
    group: string & !=""
    version: string & !=""
    kind: string & !=""
  }
}

4.1.5. 카탈로그의 예

파일 기반 카탈로그를 사용하면 카탈로그 유지 관리자가 Operator 큐레이션 및 호환성에 중점을 둘 수 있습니다. Operator 작성자는 Operator에 대한 Operator별 카탈로그를 이미 생성했기 때문에 카탈로그 유지 관리자는 각 Operator 카탈로그를 카탈로그의 루트 디렉터리의 하위 디렉터리에 렌더링하여 카탈로그를 빌드할 수 있습니다.

파일 기반 카탈로그를 구축하는 방법은 여러 가지가 있습니다. 다음 단계에서는 간단한 접근 방식을 간략하게 설명합니다.

  1. 카탈로그의 각 Operator에 대한 이미지 참조가 포함된 카탈로그의 단일 구성 파일을 유지 관리합니다.

    카탈로그 구성 파일 예

    name: community-operators
    repo: quay.io/community-operators/catalog
    tag: latest
    references:
    - name: etcd-operator
      image: quay.io/etcd-operator/index@sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
    - name: prometheus-operator
      image: quay.io/prometheus-operator/index@sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317

  2. 구성 파일을 구문 분석하고 참조에서 새 카탈로그를 생성하는 스크립트를 실행합니다.

    스크립트 예

    name=$(yq eval '.name' catalog.yaml)
    mkdir "$name"
    yq eval '.name + "/" + .references[].name' catalog.yaml | xargs mkdir
    for l in $(yq e '.name as $catalog | .references[] | .image + "|" + $catalog + "/" + .name + "/index.yaml"' catalog.yaml); do
      image=$(echo $l | cut -d'|' -f1)
      file=$(echo $l | cut -d'|' -f2)
      opm render "$image" > "$file"
    done
    opm generate dockerfile "$name"
    indexImage=$(yq eval '.repo + ":" + .tag' catalog.yaml)
    docker build -t "$indexImage" -f "$name.Dockerfile" .
    docker push "$indexImage"

4.1.6. 지침

파일 기반 카탈로그를 유지 관리할 때 다음 지침을 고려하십시오.

4.1.6.1. 변경할 수 없는 번들

OLM(Operator Lifecycle Manager)의 일반적인 지침은 번들 이미지 및 해당 메타데이터를 변경할 수 없음으로 간주해야 한다는 것입니다.

손상된 번들이 카탈로그로 푸시된 경우 사용자 중 한 명이 해당 번들로 업그레이드되었다고 가정해야 합니다. 이러한 가정에 따라 손상된 번들이 설치된 사용자에게 업그레이드를 수신하려면 손상된 번들에서 업그레이드 엣지를 사용하여 다른 번들을 릴리스해야 합니다. 해당 번들의 콘텐츠가 카탈로그에서 업데이트되는 경우 OLM은 설치된 번들을 다시 설치하지 않습니다.

그러나 카탈로그 메타데이터의 변경이 권장되는 몇 가지 사례가 있습니다.

  • 채널 승격: 번들을 이미 릴리스하고 나중에 다른 채널에 추가할 것을 결정한 경우, 다른 olm.channel blob에 번들에 대한 항목을 추가할 수 있습니다.
  • 새로운 업그레이드 에지: 새 1.2.z 번들 버전(예: 1.2.4)을 릴리스했지만 1.3.0이 이미 릴리스된 경우 1.3.0의 카탈로그 메타데이터를 업데이트하여 1.2.4를 건너뛸 수 있습니다.

4.1.6.2. 소스 제어

카탈로그 메타데이터는 소스 제어에 저장되고 정보 소스로 처리되어야 합니다. 카탈로그 이미지 업데이트에는 다음 단계가 포함되어야 합니다.

  1. 소스 제어 카탈로그 디렉터리를 새 커밋으로 업데이트합니다.
  2. 카탈로그 이미지를 빌드하고 내보냅니다. 사용자가 사용 가능하게 되면 카탈로그 업데이트를 수신할 수 있도록 :latest 또는 :<target_cluster_version>과 같은 일관된 태그 지정 용어를 사용합니다.

4.1.7. CLI 사용

opm CLI를 사용하여 파일 기반 카탈로그를 생성하는 방법에 대한 자세한 내용은 사용자 정의 카탈로그 관리를 참조하십시오.

파일 기반 카탈로그 관리와 관련된 opm CLI 명령에 대한 참조 문서는 CLI 툴 을 참조하십시오.

4.1.8. 자동화

Operator 작성자 및 카탈로그 유지 관리자는 CI/CD 워크플로를 사용하여 카탈로그 유지 관리를 자동화하는 것이 좋습니다. 카탈로그 유지 관리자는 다음 작업을 수행하도록 GitOps 자동화를 빌드하여 이 작업을 추가로 개선할 수 있습니다.

  • 예를 들어 패키지의 이미지 참조를 업데이트하여 해당 PR(pull request) 작성자가 요청된 변경을 수행할 수 있는지 확인합니다.
  • 카탈로그 업데이트가 opm validate 명령을 전달하는지 확인합니다.
  • 업데이트된 번들 또는 카탈로그 이미지 참조가 있는지, 카탈로그 이미지가 클러스터에서 성공적으로 실행되며 해당 패키지의 Operator가 성공적으로 설치될 수 있는지 확인합니다.
  • 이전 검사를 통과하는 PR을 자동으로 병합합니다.
  • 카탈로그 이미지를 자동으로 다시 빌드하고 다시 게시합니다.
Red Hat logoGithubRedditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

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

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

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

Red Hat 소개

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

© 2024 Red Hat, Inc.