2.2. Format d’emballage du cadre opérateur

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

Le bundle comprend un CSV par répertoire et généralement les CRD qui définissent les API appartenant au CSV dans son répertoire /manifestes.

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

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 en option dans le répertoire /manifestes d’un bundle:

Lorsque ces objets optionnels sont inclus dans un paquet, Operator Lifecycle Manager (OLM) peut les créer à partir du paquet et gérer leur cycle de vie avec le CSV:

Le bundle inclut également un fichier annotations.yaml dans son répertoire /metadata. Ce fichier définit des données agrégées de niveau supérieur qui aident à décrire le format et les informations du paquet sur la façon dont le paquet devrait être ajouté dans un index de paquets:

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

annotations:
  operators.operatorframework.io.bundle.mediatype.v1: "registry+v1" 

  operators.operatorframework.io.bundle.manifests.v1: "manifests/" 

  operators.operatorframework.io.bundle.metadata.v1: "metadata/" 

  operators.operatorframework.io.bundle.package.v1: "test-operator" 

  operators.operatorframework.io.bundle.channels.v1: "beta,stable" 

  operators.operatorframework.io.bundle.channel.default.v1: "stable" 

Les dépendances d’un opérateur sont listées dans un fichier de dépendances.yaml dans le dossier métadonnées d’un bundle. Ce fichier est facultatif et actuellement utilisé uniquement pour spécifier des dépendances explicites de version d’opérateur.

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

Dans l’exemple suivant, les dépendances sont spécifiées pour un opérateur Prometheus et 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

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 Opm CLI est fourni par le Cadre d’opérateur pour une utilisation avec le format de paquet Opm. Cet outil vous permet de créer et de maintenir des catalogues d’opérateurs à partir d’une liste de paquets d’opérateurs similaires aux référentiels de logiciels. Le résultat est une image de conteneur qui peut être stockée dans un registre de conteneurs puis installée sur un cluster.

Le catalogue contient une base de données de pointeurs vers l’opérateur manifeste du contenu qui peut être interrogé via une API incluse qui est servie lorsque l’image du conteneur est exécutée. Dans Red Hat OpenShift Service sur AWS, Operator Lifecycle Manager (OLM) peut référencer l’image dans une source de catalogue, définie par un objet CatalogSource, qui sonne l’image à intervalles réguliers pour permettre des mises à jour fréquentes aux 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. L’opm CLI charge le catalogue en marchant le répertoire racine et en récursant dans des sous-répertoires. Le CLI tente de charger tous les fichiers qu’il trouve et échoue si des erreurs se produisent.

Les fichiers non catalog peuvent être ignorés en utilisant les fichiers .indexignore, qui ont les mêmes règles pour les modèles et la préséance que les fichiers .gitignore.

Ignore everything except non-object .json and .yaml files

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

Les responsables du catalogue ont la flexibilité de choisir la disposition souhaitée, mais il est recommandé de stocker les blobs de catalogue de chaque paquet dans des sous-répertoires distincts. Chaque fichier individuel peut être soit JSON ou YAML; il n’est pas nécessaire que chaque fichier d’un catalogue utilise le même format.

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

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

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 les opérations triviales de système de fichiers triviales de composition, de découverte et de navigation du catalogue. 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 _Meta CUE suivant 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
}

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

Le catalogue de gestion du cycle de vie de l’opérateur (OLM) utilise actuellement trois schémas (olm.package, olm.channel et olm.bundle), qui correspondent aux concepts de paquets et de paquets existants d’OLM.

Chaque paquet Opérateur dans 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
  }
}

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

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

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

schema: olm.deprecations
package: my-operator 
entries:
  - reference:
      schema: olm.package 
    message: | 
    The 'my-operator' package is end of life. Please use the
    'my-operator-new' package for support.
  - reference:
      schema: olm.channel
      name: alpha 
    message: |
    The 'alpha' channel is no longer supported. Please switch to the
    'stable' channel.
  - reference:
      schema: olm.bundle
      name: my-operator.v1.68.0 
    message: |
    my-operator.v1.68.0 is deprecated. Uninstall my-operator.v1.68.0 and
    install my-operator.v1.72.0 for support.

schema: olm.deprecations
package: my-operator 

entries:
  - reference:
      schema: olm.package 

    message: | 

    The 'my-operator' package is end of life. Please use the
    'my-operator-new' package for support.
  - reference:
      schema: olm.channel
      name: alpha 

    message: |
    The 'alpha' channel is no longer supported. Please switch to the
    'stable' channel.
  - reference:
      schema: olm.bundle
      name: my-operator.v1.68.0 

    message: |
    my-operator.v1.68.0 is deprecated. Uninstall my-operator.v1.68.0 and
    install my-operator.v1.72.0 for support.

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

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

Les propriétés sont des morceaux arbitraires de métadonnées qui peuvent être attachés à des schémas de catalogue basés sur des fichiers. Le champ type est une chaîne qui spécifie efficacement la signification sémantique et syntaxique du champ de valeur. La valeur peut être tout JSON ou YAML arbitraire.

L’OLM définit une poignée de types de propriétés, encore une fois en utilisant le préfixe Olm.* réservé.

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

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

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

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

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

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

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

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

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

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

Considérez les directives suivantes lors de la maintenance des catalogues basés sur des fichiers.

En ce qui concerne les instructions concernant la création de catalogues basés sur des fichiers à l’aide de l’opm CLI, voir Gérer les catalogues personnalisés. En ce qui concerne la documentation de référence sur les commandes opm CLI liées à la gestion des catalogues basés sur des fichiers, consultez les outils CLI.

Les auteurs d’opérateurs et les responsables du catalogue sont encouragés à automatiser la maintenance de leur catalogue avec des flux de travail CI/CD. Les mainteneurs de catalogues peuvent encore s’améliorer à ce sujet en construisant l’automatisation GitOps pour accomplir les tâches suivantes: