2.2. Format d'emballage du cadre de l'opérateur

Les manifestes de paquets font référence à un ensemble de manifestes Kubernetes qui définissent le déploiement et le modèle RBAC de l'opérateur.

Un bundle comprend un CSV par répertoire et généralement les CRD qui définissent les API propres au CSV dans son répertoire /manifests.

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

Autres objets pris en charge

Les types d'objets suivants peuvent également être inclus de manière facultative dans le répertoire /manifests d'une liasse :

Lorsque ces objets facultatifs sont inclus dans une liasse, Operator Lifecycle Manager (OLM) peut les créer à partir de la liasse et gérer leur cycle de vie en même temps que le CSV :

Une liasse comprend également un fichier annotations.yaml dans son répertoire /metadata. Ce fichier définit des données agrégées de plus haut niveau qui aident à décrire le format et les informations sur la manière dont l'offre groupée doit être ajoutée à un index d'offres groupées :

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

Les dépendances d'un Opérateur sont listées dans un fichier dependencies.yaml dans le dossier metadata/ d'un bundle. Ce fichier est facultatif et n'est actuellement utilisé que pour spécifier les dépendances explicites de la version de l'opérateur.

La liste des dépendances contient un champ type pour chaque élément afin de spécifier de quel type de dépendance il s'agit. Les types de dépendances de l'opérateur suivants sont pris en charge :

Dans l'exemple suivant, des dépendances sont spécifiées pour un opérateur Prometheus et des CRD etcd :

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

L'outil CLI opm est fourni par Operator Framework pour être utilisé avec le format Operator bundle. Cet outil vous permet de créer et de maintenir des catalogues d'opérateurs à partir d'une liste de bundles d'opérateurs qui sont similaires à des dépôts de logiciels. Le résultat est une image de conteneur qui peut être stockée dans un registre de conteneurs et ensuite installée sur un cluster.

Un catalogue contient une base de données de pointeurs vers le contenu du manifeste de l'opérateur qui peut être interrogé par le biais d'une API incluse qui est servie lorsque l'image du conteneur est exécutée. Sur OpenShift Container Platform, Operator Lifecycle Manager (OLM) peut référencer l'image dans une source de catalogue, définie par un objet CatalogSource, qui interroge l'image à intervalles réguliers pour permettre des mises à jour fréquentes des opérateurs installés sur le cluster.

Les catalogues basés sur des fichiers peuvent être stockés et chargés à partir de systèmes de fichiers basés sur des répertoires. Le CLI de opm charge le catalogue en parcourant le répertoire racine et en revenant sur les sous-répertoires. Il tente de charger tous les fichiers qu'il trouve et échoue en cas d'erreur.

Les fichiers hors catalogue peuvent être ignorés à l'aide des fichiers .indexignore, qui obéissent aux mêmes règles que les fichiers .gitignore en ce qui concerne les motifs et la priorité.

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

Les responsables des catalogues ont la possibilité de choisir la disposition qu'ils souhaitent, mais il est recommandé de stocker les blobs de catalogue basés sur les fichiers de chaque paquet dans des sous-répertoires distincts. Chaque fichier individuel peut être au format JSON ou YAML ; il n'est pas nécessaire que tous les fichiers d'un catalogue utilisent le même format.

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

Cette structure recommandée a la propriété que chaque sous-répertoire de la hiérarchie des répertoires est un catalogue autonome, ce qui rend la composition, la découverte et la navigation dans le catalogue des opérations triviales du système de fichiers. Le catalogue peut également être inclus dans un catalogue parent en le copiant dans le répertoire racine du catalogue parent.

Les catalogues basés sur des fichiers utilisent un format, basé sur la spécification du langage CUE, qui peut être étendu avec des schémas arbitraires. Le schéma CUE suivant ( _Meta ) définit le format auquel tous les blobs de catalogues basés sur des fichiers doivent adhérer :

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

Un catalogue Operator Lifecycle Manager (OLM) utilise actuellement trois schémas (olm.package, olm.channel, et olm.bundle), qui correspondent aux concepts existants de paquet et de liasse d'OLM.

Chaque paquet d'opérateurs d'un catalogue nécessite exactement un blob olm.package, au moins un blob olm.channel et un ou plusieurs blobs olm.bundle.

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

Les propriétés sont des éléments arbitraires de métadonnées qui peuvent être attachés à des schémas de catalogues basés sur des fichiers. Le champ type est une chaîne qui spécifie effectivement la signification sémantique et syntaxique du champ value. La valeur peut être n'importe quel JSON ou YAML arbitraire.

OLM définit une poignée de types de propriétés, en utilisant à nouveau le préfixe réservé 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 & !=""
  }
}

Avec les catalogues basés sur des fichiers, les responsables des catalogues peuvent se concentrer sur la curation et la compatibilité des opérateurs. Comme les auteurs d'opérateurs ont déjà produit des catalogues spécifiques pour leurs opérateurs, les responsables de catalogues peuvent construire leur catalogue en rendant chaque catalogue d'opérateur dans un sous-répertoire du répertoire racine du catalogue.

Il existe de nombreuses façons de créer un catalogue basé sur des fichiers ; les étapes suivantes décrivent une approche simple :

Les lignes directrices suivantes doivent être prises en compte lors de la gestion de catalogues basés sur des fichiers.

Pour obtenir des instructions sur la création de catalogues basés sur des fichiers à l'aide de l'interface CLI de opm, reportez-vous à la section Gestion des catalogues personnalisés.

Pour obtenir une documentation de référence sur les commandes CLI de opm relatives à la gestion des catalogues basés sur des fichiers, voir Outils CLI.

Les auteurs d'opérateurs et les responsables de catalogues sont encouragés à automatiser la maintenance de leurs catalogues avec des flux de travail CI/CD. Les mainteneurs de catalogues peuvent encore améliorer cela en construisant une automatisation GitOps pour accomplir les tâches suivantes :

Un objet RukPak Bundle représente un contenu à mettre à la disposition d'autres consommateurs dans le cluster. Tout comme le contenu d'une image de conteneur doit être extrait et décompressé pour que le pod puisse commencer à l'utiliser, les objets Bundle sont utilisés pour référencer le contenu qui pourrait avoir besoin d'être extrait et décompressé. En ce sens, un bundle est une généralisation du concept d'image et peut être utilisé pour représenter n'importe quel type de contenu.

Les paquets ne peuvent rien faire par eux-mêmes ; ils ont besoin d'un provisionneur pour décompresser et rendre leur contenu disponible dans le cluster. Ils peuvent être décompressés sur n'importe quel support de stockage arbitraire, tel qu'un fichier tar.gz dans un répertoire monté dans les pods du provisionneur. Chaque objet Bundle est associé à un champ spec.provisionerClassName qui indique l'objet Provisioner qui surveille et décompresse ce type de paquet particulier.

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

L'API RukPak BundleDeployment pointe vers un objet Bundle et indique qu'il doit être actif. Cela permet notamment de pivoter à partir d'anciennes versions d'un ensemble actif. Un objet BundleDeployment peut également inclure une spécification intégrée pour un ensemble souhaité.

Tout comme les pods génèrent des instances d'images de conteneurs, un déploiement de bundle génère une version déployée d'un bundle. Le déploiement d'un bundle peut être considéré comme une généralisation du concept de pod.

Les spécificités de la manière dont un déploiement de bundle apporte des modifications à un cluster basé sur un bundle référencé sont définies par le provisionneur qui est configuré pour surveiller ce déploiement de bundle.

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

Un provisionneur RukPak est un contrôleur qui comprend les API BundleDeployment et Bundle et peut prendre des mesures. Chaque provisionneur se voit attribuer un identifiant unique et est chargé de rapprocher les objets Bundle et BundleDeployment avec un champ spec.provisionerClassName correspondant à cet identifiant particulier.

Par exemple, le "plain provisioner" est capable de décompresser un paquet plain v0 donné sur un cluster et de l'instancier, rendant ainsi le contenu du paquet disponible dans le cluster.