Migrating package manifest projects to bundle format

Support for the legacy package manifest format for Operators is removed in OKD 4.8 and later. If you have an Operator project that was initially created using the package manifest format, you can use the Operator SDK to migrate the project to the bundle format. The bundle format is the preferred packaging format for Operator Lifecycle Manager (OLM) starting in OKD 4.6.

About packaging format migration

The Operator SDK pkgman-to-bundle command helps in migrating Operator Lifecycle Manager (OLM) package manifests to bundles. The command takes an input package manifest directory and generates bundles for each of the versions of manifests present in the input directory. You can also then build bundle images for each of the generated bundles.

For example, consider the following packagemanifests/ directory for a project in the package manifest format:

Example package manifest format layout

  1. packagemanifests/
  2. └── etcd
  3.     ├── 0.0.1
  4.     │   ├── etcdcluster.crd.yaml
  5.     │   └── etcdoperator.clusterserviceversion.yaml
  6.     ├── 0.0.2
  7.     │   ├── etcdbackup.crd.yaml
  8.     │   ├── etcdcluster.crd.yaml
  9.     │   ├── etcdoperator.v0.0.2.clusterserviceversion.yaml
  10.     │   └── etcdrestore.crd.yaml
  11.     └── etcd.package.yaml

After running the migration, the following bundles are generated in the bundle/ directory:

Example bundle format layout

  1. bundle/
  2. ├── bundle-0.0.1
  3. │   ├── bundle.Dockerfile
  4. │   ├── manifests
  5. │   │   ├── etcdcluster.crd.yaml
  6. │   │   ├── etcdoperator.clusterserviceversion.yaml
  7. │   ├── metadata
  8. │   │   └── annotations.yaml
  9. │   └── tests
  10. │       └── scorecard
  11. │           └── config.yaml
  12. └── bundle-0.0.2
  13.     ├── bundle.Dockerfile
  14.     ├── manifests
  15.     │   ├── etcdbackup.crd.yaml
  16.     │   ├── etcdcluster.crd.yaml
  17.     │   ├── etcdoperator.v0.0.2.clusterserviceversion.yaml
  18.     │   ├── etcdrestore.crd.yaml
  19.     ├── metadata
  20.     │   └── annotations.yaml
  21.     └── tests
  22.         └── scorecard
  23.             └── config.yaml

Based on this generated layout, bundle images for both of the bundles are also built with the following names:

  • quay.io/example/etcd:0.0.1

  • quay.io/example/etcd:0.0.2

Additional resources

Migrating a package manifest project to bundle format

Operator authors can use the Operator SDK to migrate a package manifest format Operator project to a bundle format project.

Prerequisites

  • Operator SDK CLI installed

  • Operator project initially generated using the Operator SDK in package manifest format

Procedure

  • Use the Operator SDK to migrate your package manifest project to the bundle format and generate bundle images:

    1. $ operator-sdk pkgman-to-bundle <package_manifests_dir> \ (1)
    2.     [--output-dir <directory>] \ (2)
    3.     --image-tag-base <image_name_base> (3)
    1Specify the location of the package manifests directory for the project, such as packagemanifests/ or manifests/.
    2Optional: By default, the generated bundles are written locally to disk to the bundle/ directory. You can use the —output-dir flag to specify an alternative location.
    3Set the —image-tag-base flag to provide the base of the image name, such as quay.io/example/etcd, that will be used for the bundles. Provide the name without a tag, because the tag for the images will be set according to the bundle version. For example, the full bundle image names are generated in the format <image_name_base>:<bundle_version>.

Verification

  • Verify that the generated bundle image runs successfully:

    1. $ operator-sdk run bundle <bundle_image_name>:<tag>

    Example output

    1. INFO[0025] Successfully created registry pod: quay-io-my-etcd-0-9-4
    2. INFO[0025] Created CatalogSource: etcd-catalog
    3. INFO[0026] OperatorGroup "operator-sdk-og" created
    4. INFO[0026] Created Subscription: etcdoperator-v0-9-4-sub
    5. INFO[0031] Approved InstallPlan install-5t58z for the Subscription: etcdoperator-v0-9-4-sub
    6. INFO[0031] Waiting for ClusterServiceVersion "default/etcdoperator.v0.9.4" to reach 'Succeeded' phase
    7. INFO[0032]   Waiting for ClusterServiceVersion "default/etcdoperator.v0.9.4" to appear
    8. INFO[0048]   Found ClusterServiceVersion "default/etcdoperator.v0.9.4" phase: Pending
    9. INFO[0049]   Found ClusterServiceVersion "default/etcdoperator.v0.9.4" phase: Installing
    10. INFO[0064]   Found ClusterServiceVersion "default/etcdoperator.v0.9.4" phase: Succeeded
    11. INFO[0065] OLM has successfully installed "etcdoperator.v0.9.4"