Skip to content
This repository has been archived by the owner on Aug 12, 2024. It is now read-only.

Commit

Permalink
(docs): Update plain bundle docs
Browse files Browse the repository at this point in the history 
Signed-off-by: Bryce Palmer <[email protected]>
  • Loading branch information
@everettraven
everettraven committed Jun 21, 2023
1 parent 079b611 commit b1eec41
Show file tree
Hide file tree
Showing 2 changed files with 152 additions and 239 deletions.
168 changes: 152 additions & 16 deletions docs/bundles/plain.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,52 @@

## Overview

This document is meant to define the `plain` bundle format as a reference for those publishing `plain` bundles
for use with RukPak. For more information on the concept of a bundle, click [here](https://github.com/operator-framework/rukpak#bundle).
This document is meant to define the plain bundle format as a reference for those publishing plain bundles for use with
RukPak. A bundle is a collection of Kubernetes resources that are packaged together for the purposes of installing onto
a Kubernetes cluster. A bundle can be unpacked onto a running cluster, where controllers can then create the underlying
content embedded in the bundle. The bundle can be used as the underlying `spec.source` for
a [`Bundle`](https://github.com/operator-framework/rukpak#bundle) resource.

A plain bundle is simply a collection of static, arbitrary, Kubernetes YAML manifests in a given directory.
A plain bundle is a static collection of arbitrary Kubernetes YAML manifests. A plain bundle is contained in a directory
that can be packaged in a container image layer , a `git` repository or any other content source that the
[plain bundle provisioner](../provisioners/plain.md) supports.

Supported source types for a plain bundle currently include the following:

* A directory in a [container image](../sources/image.md)
* A directory in a [`git` repository](../sources/git.md)
* A set of keys in a [`ConfigMap`](../sources/local.md)
* An [upload](../sources/upload.md)
* A `.tgz` file returned by a [http endpoint](../sources/http.md)

Additional source types (such as a local volume or a generic URI-based resource) are on the roadmap. These source types all present the same content: a directory containing static Kubernetes YAML manifests

The currently implemented plain bundle format is the `plain+v0` format. The name of the bundle format, `plain+v0`
combines the type of bundle (plain) with the current schema version (v0).
combines the type of bundle (plain) with the current schema version (v0). The
[plain bundle provisioner](../provisioners/plain.md) is able to source
`plain+v0` bundles and install them onto a Kubernetes cluster.

> Note: the plain+v0 bundle format is at schema version v0, which means it's an experimental format that is subject
> Note: the `plain+v0` bundle format is at schema version v0, which means it's an experimental format that is subject
> to change.
## Common Terminology

* *bundle* is a collection of files that define content to be deployed to a cluster
* *bundle image* is a container image that contains a bundle within its filesystem
* *bundle git repo* is a git repository that contains a bundle within a directory

## Example

For example, below is an example of a file tree in a `plain+v0` bundle. It must have a `manifests` directory contains
the Kubernetes resources required to deploy an application.
For example, below is a minimal example of a Dockerfile that builds a `plain+v0` bundle image from a directory containing static Kubernetes manifests.

```dockerfile
FROM scratch
COPY /manifests /manifests
```

where the given `manifests` directory contains the Kubernetes resources required to deploy an application, for example:

```tree
```bash
manifests
├── namespace.yaml
├── cluster_role.yaml
Expand All @@ -29,16 +58,123 @@ manifests
└── deployment.yaml
```

For a bundle `git` repo, any directory that contains only static Kubernetes manifests checked into a `git` repository
accessible via a remote URL (HTTP or SSH) can be considered a plain bundle and sourced by the plain provisioner. For
more information on bundles backed by `git` repositories, see the [`git` based bundles doc](../sources/git.md).

> Note: there must be at least one resource in the manifests directory in order for the bundle to be a valid
> plain+v0 bundle.
> `plain+v0` bundle.
## Technical Details

* The static manifests must be located in the /manifests directory for the bundle to be a
valid `plain+v0` bundle that the provisioner can unpack. A plain bundle image without a /manifests directory is
invalid and will not be successfully unpacked onto the cluster.
* The static manifests must be located in the root-level `/manifests` directory in a bundle image for the bundle to be a
valid `plain+v0` bundle that the provisioner can unpack. A plain bundle image without a `/manifests` directory is
invalid and will not be successfully unpacked onto the cluster.
* For a bundle `git` repo, the manifests directory can be anywhere in the repository, not just at the root-level. The
location can be specified via `spec.source.git.directory`. There must be a flat directory consisting of Kubernetes YAML manifests at the provided location in order to have a valid bundle git repo. If a specific directory is not provided, it is assumed to be `./manifests` in a bundle git repo.
* The manifests directory should be flat: all manifests should be at the top-level with no subdirectories.
* Including any content in the /manifests directory of a plain bundle that is not static manifests will result in
a failure when creating content on-cluster from that bundle. Essentially, any file that would not
successfully `kubectl apply` will result in an error, but multi-object YAML files, or JSON files, are fine. There will
be validation tooling provided that can determine whether a given artifact is a valid bundle.
* The plain bundle image can be built from any base image, but `scratch` is recommended as it keeps the resulting bundle
image a minimal size.
* It is required that `kubectl apply` is able to process all .yaml files in the directory that make up a plain bundle. For example, multi-object YAML files are acceptable, but Ansible playbooks would not be.

## Building a plain bundle
### Prerequisites

In order to create a plain bundle for Rukpak, ensure your Kubernetes manifests are in a flat directory at the root of
your project called `manifests/`. This allows the contents to be sourced and unpacked by the
[plain provisioner](..provisioners/plain.md). It should look similar to:

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

If you are using [kustomize](https://kustomize.io/) for building your manifests from a template, redirect the output into a single file under the `manifests/` directory. For example:
```bash
$ tree templates
templates
├── namespace.yaml
├── service_account.yaml
├── cluster_role.yaml
├── cluster_role_binding.yaml
├── deployment.yaml.yaml
└── kustomization.yaml
```

```bash
kustomize build templates > manifests/manifests.yaml
```

### Git source

For using the bundle with a [`git` source](../sources/git.md), commit your `manifests/` directory to your `git` repository.

### HTTP source

For using the bundle with a [HTTP source](../sources/http.md), create a `.tgz` file that contains the `manifests/` directory and it's manifests. This `.tgz` file should be served when hitting the HTTP endpoint.

### Image source

For using the bundle with an [image source](../sources/image.md), follow the below steps:

1. Create a Dockerfile at the root of the project
```bash
touch Dockerfile.plainbundle
```

2. Edit the Dockerfile to include the following:
```bash
cat <<EOF >Dockerfile.plainbundle
FROM scratch
COPY manifests /manifests
EOF
```

> Note: The Dockerfile can have any `FROM ...` directive, but it is recommended to use the `FROM scratch`
> directive to keep the resulting image size minimal
3. Build an OCI-compliant image using any build tooling you prefer. Use an image tag that references a repository that you have push access to. For example,

```bash
docker build -f Dockerfile.plainbundle -t quay.io/operator-framework/rukpak:example .
```

4. Push the image to the remote registry

```bash
docker push quay.io/operator-framework/rukpak:example
```

If you are looking to use a private image registry for sourcing your bundle content, see the ["Private image registries" section of the image source documentation](../sources/image.md#private-image-registries)

### Upload source

For using the bundle with an [upload source](../sources/upload.md), follow the below steps:

1. Download the `rukpakctl` CLI tool
```bash
go install github.com/operator-framework/rukpak/cmd/rukpakctl
```

2. Ensure rukpak is running. For more info on how to install rukpak on your cluster see the [Installation section of the README](../../README.md#installation)

3. Use `rukpakctl` to create a `BundleDeployment` using the `manifests/` directory
```bash
rukpakctl run <bundle-name> .
```

### ConfigMap source

For using the bundle with a [`ConfigMap` source (also known as a local source)](../sources/local.md), follow the below steps:

1. Ensure rukpak is running. For more info on how to install rukpak on your cluster see the [Installation section of the README](../../README.md#installation)

2. Create a `ConfigMap` from the `manifests/` directory
```bash
kubectl create configmap my-configmap --from-file=manifests -n rukpak-system
```
Loading

0 comments on commit b1eec41

Please sign in to comment.