2.2. Operator 프레임워크 패키지 형식

번들 매니페스트는 Operator의 배포 및 RBAC 모델을 정의하는 Kubernetes 매니페스트 세트를 나타냅니다.

번들에는 디렉터리당 하나의 CSV와 일반적으로 /manifests 디렉터리에서 CSV의 고유 API를 정의하는 CRD가 포함됩니다.

etcd
├── manifests
│   ├── etcdcluster.crd.yaml
│   └── etcdoperator.clusterserviceversion.yaml
│   └── secret.yaml
│   └── configmap.yaml
└── metadata
    └── annotations.yaml
    └── dependencies.yaml

추가 지원 오브젝트

다음과 같은 오브젝트 유형도 번들의 /manifests 디렉터리에 선택적으로 포함될 수 있습니다.

이러한 선택적 오브젝트가 번들에 포함된 경우 OLM(Operator Lifecycle Manager)은 번들에서 해당 오브젝트를 생성하고 CSV와 함께 해당 라이프사이클을 관리할 수 있습니다.

번들의 /metadata 디렉터리에는 annotations.yaml 파일도 포함되어 있습니다. 이 파일에서는 번들을 번들 인덱스에 추가하는 방법에 대한 형식 및 패키지 정보를 설명하는 데 도움이 되는 고급 집계 데이터를 정의합니다.

annotations:
  operators.operatorframework.io.bundle.mediatype.v1: "registry+v1" 1
  operators.operatorframework.io.bundle.manifests.v1: "manifests/" 2
  operators.operatorframework.io.bundle.metadata.v1: "metadata/" 3
  operators.operatorframework.io.bundle.package.v1: "test-operator" 4
  operators.operatorframework.io.bundle.channels.v1: "beta,stable" 5
  operators.operatorframework.io.bundle.channel.default.v1: "stable" 6

Operator의 종속 항목은 번들의 metadata/ 폴더에 있는 dependencies.yaml 파일에 나열되어 있습니다. 이 파일은 선택 사항이며 현재는 명시적인 Operator 버전 종속 항목을 지정하는 데만 사용됩니다.

종속성 목록에는 종속성의 유형을 지정하기 위해 각 항목에 대한 type 필드가 포함되어 있습니다. 다음과 같은 유형의 Operator 종속 항목이 지원됩니다.

다음 예제에서는 Prometheus Operator 및 etcd CRD에 대한 종속 항목을 지정합니다.

dependencies:
  - type: olm.package
    value:
      packageName: prometheus
      version: ">0.27.0"
  - type: olm.gvk
    value:
      group: etcd.database.coreos.com
      kind: EtcdCluster
      version: v1beta2

opm CLI 툴은 Operator 번들 형식과 함께 사용할 수 있도록 Operator 프레임워크에서 제공합니다. 이 툴을 사용하면 소프트웨어 리포지토리와 유사한 Operator 번들 목록에서 Operator 카탈로그를 생성하고 유지 관리할 수 있습니다. 결과적으로 컨테이너 레지스트리에 저장한 다음 클러스터에 설치할 수 있는 컨테이너 이미지가 생성됩니다.

카탈로그에는 컨테이너 이미지가 실행될 때 제공되는 포함된 API를 통해 쿼리할 수 있는 Operator 매니페스트 콘텐츠에 대한 포인터 데이터베이스가 포함되어 있습니다. OpenShift Container Platform에서 OLM(Operator Lifecycle Manager)은 CatalogSource 오브젝트에서 정의한 카탈로그 소스의 이미지를 참조할 수 있으며 주기적으로 이미지를 폴링하여 클러스터에 설치된 Operator를 자주 업데이트할 수 있습니다.

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

비카탈로그 파일은 .gitignore 파일과 패턴 및 우선 순위에 대해 동일한 규칙이 있는 .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

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

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

_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
}

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

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

#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
  }
}

#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 & !=""
}

#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 & !=""
}

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

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

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

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

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

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

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

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

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

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

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

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

RukPak Bundle 오브젝트는 클러스터의 다른 사용자가 사용할 수 있도록 콘텐츠를 나타냅니다. 포드를 사용하려면 컨테이너 이미지의 콘텐츠를 가져와서 압축 해제해야 하는 것과 마찬가지로 Bundle 오브젝트는 가져와서 압축 해제해야 하는 콘텐츠를 참조하는 데 사용됩니다. 이러한 점에서 번들은 이미지 개념을 일반화하고 모든 유형의 콘텐츠를 나타내는 데 사용할 수 있습니다.

번들은 자체적으로 아무것도 수행할 수 없습니다. 프로비저닝 프로그램이 클러스터에서 콘텐츠를 사용할 수 있도록 압축을 풀고 사용할 수 있도록 해야 합니다. 프로비저너 Pod에 마운트된 디렉터리의 tar.gz 파일과 같은 임의의 스토리지 미디어에 압축을 해제할 수 있습니다. 각 Bundle 오브젝트에는 특정 번들 유형을 감시하고 압축 해제하는 Provisioner 오브젝트를 나타내는 관련 spec.provisionerClassName 필드가 있습니다.

apiVersion: core.rukpak.io/v1alpha1
kind: Bundle
metadata:
  name: my-bundle
spec:
  source:
    type: image
    image:
      ref: my-bundle@sha256:xyz123
  provisionerClassName: core-rukpak-io-plain

$ oc apply -f -<<EOF
apiVersion: core.rukpak.io/v1alpha1
kind: Bundle
metadata:
  name: combo-tag-ref
spec:
  source:
    type: git
    git:
      ref:
        tag: v0.0.2
      repository: https://github.com/operator-framework/combo
  provisionerClassName: core-rukpak-io-plain
EOF

bundle.core.rukpak.io/combo-tag-ref created

$ oc patch bundle combo-tag-ref --type='merge' -p '{"spec":{"source":{"git":{"ref":{"tag":"v0.0.3"}}}}}'

Error from server (bundle.spec is immutable): admission webhook "vbundles.core.rukpak.io" denied the request: bundle.spec is immutable

manifests
├── namespace.yaml
├── cluster_role.yaml
├── role.yaml
├── serviceaccount.yaml
├── cluster_role_binding.yaml
├── role_binding.yaml
└── deployment.yaml

RukPak BundleDeployment API는 Bundle 오브젝트를 가리키며 활성화되어 있어야 함을 나타냅니다. 여기에는 이전 버전의 활성 번들에서 피벗하는 작업이 포함됩니다. BundleDeployment 오브젝트에는 원하는 번들에 대한 임베디드 사양도 포함될 수 있습니다.

Pod가 컨테이너 이미지의 인스턴스를 생성하는 것과 마찬가지로 번들 배포는 배포된 버전의 번들을 생성합니다. 번들 배포는 Pod 개념의 일반화로 볼 수 있습니다.

번들 배포에서 참조된 번들을 기반으로 클러스터를 변경하는 방법에 대한 세부 사항은 번들 배포를 모니터링하도록 구성된 프로비저너에 의해 정의됩니다.

apiVersion: core.rukpak.io/v1alpha1
kind: BundleDeployment
metadata:
  name: my-bundle-deployment
spec:
  provisionerClassName: core-rukpak-io-plain
  template:
    metadata:
      labels:
        app: my-bundle
    spec:
      source:
        type: image
        image:
          ref: my-bundle@sha256:xyz123
      provisionerClassName: core-rukpak-io-plain

RukPak 프로비전 프로그램은 BundleDeployment 및 Bundle API를 이해하고 조치를 취할 수 있는 컨트롤러입니다. 각 프로비저너에는 고유한 ID가 할당되며 해당 ID와 일치하는 spec.provisionerClassName 필드를 사용하여 Bundle 및 BundleDeployment 오브젝트를 조정합니다.

예를 들어 일반 프로비저너는 지정된 plain+v0 번들을 클러스터에 압축한 다음 인스턴스화하여 클러스터에서 번들 내용을 사용할 수 있도록 할 수 있습니다.