Skip to content

Files

Latest commit

 

History

History
286 lines (215 loc) · 8.76 KB

bundle-sources.md

File metadata and controls

286 lines (215 loc) · 8.76 KB

Building a file-based catalog from a plain bundle image

Warning: Operator Lifecycle Manager (OLM) v1 features and components are still experimental. Early adopters and contributors should expect breaking changes. The following procedures are not recommended for use on production clusters.

You can build a static collection of arbitrary Kubernetes manifests in the YAML format, or plain bundle, and add the image to a file-based catalog (FBC). The experimental olm.bundle.mediatype property of the olm.bundle schema object differentiates a plain bundle from a regular (registry+v1) bundle. You must set the bundle media type property to plain+v0 to specify a plain bundle.

For more information, see the Plain Bundle Specification in the RukPak repository.

To build a file-based catalog from a plain bundle image, you must complete the following steps:

  • Create a plain bundle image
  • Create a file-based catalog
  • Add the plain bundle image to your file-based catalog
  • Build your catalog as an image
  • Publish your catalog image

Building a plain bundle image from an image source

Currently, the Operator Controller only supports installing plain bundles created from a plain bundle image.

Prerequisites

  • opm CLI tool
  • Docker or Podman
  • Push access to a container registry, such as Quay

Procedure

  1. Verify that your Kubernetes manifests are in a flat directory at the root of your project similar to the following example:

    tree manifests
manifests
├── namespace.yaml
├── service_account.yaml
├── cluster_role.yaml
├── cluster_role_binding.yaml
└── deployment.yaml

    • If you are using kustomize to build your manifests from templates, you must redirect the output to one or more files under the manifests/ directory. For example:

      kustomize build templates > manifests/manifests.yaml

    For more information, see Building a plain bundle > Prerequisites.

  2. Create a Dockerfile at the root of your project:

    touch plainbundle.Dockerfile

  3. Make the following changes to your Dockerfile:

    Example Dockerfile

        FROM scratch
    ADD manifests /manifests

    Note: Use the FROM scratch directive to make the size of the image smaller. No other files or directories are required in the bundle image.

  4. Build an OCI-compliant image using your preferred build tool, similar to the following example. You must use an image tag that references a repository where you have push access privileges.

    Example build command

    docker build -f plainbundle.Dockerfile -t \
quay.io/<organization_name>/<repository_name>:<image_tag> .

  5. Push the image to your remote registry:

    docker push quay.io/<organization_name>/<repository_name>:<image_tag>

Additional resources

Creating a file-based catalog

If you do not have a file-based catalog, you must perform the following steps to initialize the catalog.

Prerequisites

  • opm CLI tool
  • Docker or Podman

Procedure

  1. Create a directory for the catalog by running the following command:

    mkdir <catalog_dir>

  2. In the same directory level, create a Dockerfile that can build a catalog image:

    touch Dockerfile

    • The Dockerfile must be in the same parent directory as the catalog directory that you created in the previous step: Example directory structure

      .
├── <catalog_dir>
└── <catalog_dir>.Dockerfile

  3. Make the following changes to your Dockerfile:

    Example Dockerfile

        FROM scratch
    ADD <catalog_dir> /configs

    Note: Use the FROM scratch directive to make the size of the image smaller.

  4. Populate the catalog with the package definition for your Operator by running the opm init command:

    opm init <operator_name> \
--output json \
> <catalog_dir>/index.json

    This command generates an olm.package declarative config blob in the specified catalog configuration file.

Adding a plain bundle to your file-based catalog

Currently, the opm render command does not support adding plain bundles to catalogs. You must manually add plain bundles to your file-based catalog, as shown in the following example.

Prerequisites

  • opm CLI tool
  • A plain bundle image
  • A file-based catalog
  • Push access to a container registry, such as Quay
  • Docker or Podman

Procedure

  1. Verify that your catalog's index.json or index.yaml file is similar to the following example:

    Example <catalog_dir>/index.json file

    {   
    {
     "schema": "olm.package",
     "name": "<operator_name>",
    }    
}

  2. To create an olm.bundle blob, edit your index.json or index.yaml file, similar to the following example:

    Example <catalog_dir>/index.json file

    {
    "schema": "olm.bundle",
    "name": "<operator_name>.v<version>",
    "package": "<operator_name>",
    "image": "quay.io/<organization_name>/<repository_name>:<image_tag>", 
    "properties": [
        {
            "type": "olm.package",
            "value": {
            "packageName": "<operator_name>",
            "version": "<bundle_version>"
            }
        },
        {
            "type": "olm.bundle.mediatype",
            "value": "plain+v0"
        }
  ]
}

  3. To create an olm.channel blob, edit your index.json or index.yaml file, similar to the following example:

    Example <catalog_dir>/index.json file

    {
    "schema": "olm.channel",
    "name": "<desired_channel_name>",
    "package": "<operator_name>",
    "entries": [
        {
            "name": "<operator_name>.v<version>"
        }
    ]
}

    Note: Please refer to channel naming conventions for choosing the <desired_channel_name>. An example of the <desired_channel_name> is candidate-v0.

Verification

  1. Open your index.json or index.yaml file and ensure it is similar to the following example:

    Example index.json file

    {
    "schema": "olm.package",
    "name": "example-operator",
}
{
    "schema": "olm.bundle",
    "name": "example-operator.v0.0.1",
    "package": "example-operator",
    "image": "quay.io/rashmigottipati/example-operator-bundle:v0.0.1",
    "properties": [
        {
            "type": "olm.package",
            "value": {
            "packageName": "example-operator",
            "version": "v0.0.1"
            }
        },
        {
            "type": "olm.bundle.mediatype",
            "value": "plain+v0"
        }
    ]
}
{
    "schema": "olm.channel",
    "name": "preview",
    "package": "example-operator",
    "entries": [
        {
            "name": "example-operator.v0.0.1"
        }
    ]
}

Building and publishing a file-based catalog

Procedure

  1. Run the following command to build your catalog as an image:

    docker build -f <catalog_dir>.Dockerfile -t \
quay.io/<organization_name>/<repository_name>:<image_tag> .

  2. Run the following command to push the catalog image:

    docker push quay.io/<organization_name>/<repository_name>:<image_tag>