Skip to content

Commit bca2bfb

Browse files
rashmigottipatirashmigottipati
authoredJul 25, 2023
(plain bundle usage) Documentation on how to add a plain bundle image to a file-based catalog (#1127)
* Documentation on how to add a plain bundle to a file-based catalog Signed-off-by: Rashmi Gottipati <[email protected]> * Address review feedback Signed-off-by: Rashmi Gottipati <[email protected]> * Clarify regular bundle to be of registry+v1 format Signed-off-by: Rashmi Gottipati <[email protected]> * Address review feedback #1 Signed-off-by: Rashmi Gottipati <[email protected]> * Address review feedback #2 Signed-off-by: Rashmi Gottipati <[email protected]> * Address review feedback #3 Signed-off-by: Rashmi Gottipati <[email protected]> * Add an example for the desired channel name and link to OLM best practices for channel naming conventions Signed-off-by: Rashmi Gottipati <[email protected]> --------- Signed-off-by: Rashmi Gottipati <[email protected]>
·
v1.51.0v1.29.0
1 parent 82a91fa commit bca2bfb

File tree

1 file changed

+286
-0
lines changed

1 file changed

+286
-0
lines changed
 

‎docs/design/bundle-sources.md

+286
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# Building a file-based catalog from a plain bundle image
2+
3+
> **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.
4+
5+
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.
6+
7+
For more information, see the [Plain Bundle Specification](https://github.com/operator-framework/rukpak/blob/main/docs/bundles/plain.md) in the RukPak repository.
8+
9+
To build a file-based catalog from a plain bundle image, you must complete the following steps:
10+
11+
* Create a plain bundle image
12+
* Create a file-based catalog
13+
* Add the plain bundle image to your file-based catalog
14+
* Build your catalog as an image
15+
* Publish your catalog image
16+
17+
## Building a plain bundle image from an image source
18+
19+
Currently, the Operator Controller only supports installing plain bundles created from a plain bundle image.
20+
21+
<h3 id="prereqs-building-plain-bundle-from-image">
22+
Prerequisites
23+
</h3>
24+
25+
* [`opm` CLI tool](https://github.com/operator-framework/operator-registry/releases)
26+
* Docker or Podman
27+
* Push access to a container registry, such as [Quay](https://quay.io)
28+
29+
<h3 id="proc-building-plain-bundle-from-image">
30+
Procedure
31+
</h3>
32+
33+
1. Verify that your Kubernetes manifests are in a flat directory at the root of your project similar to the following example:
34+
35+
```sh
36+
tree manifests
37+
manifests
38+
├── namespace.yaml
39+
├── service_account.yaml
40+
├── cluster_role.yaml
41+
├── cluster_role_binding.yaml
42+
└── deployment.yaml
43+
```
44+
45+
* If you are using [kustomize](https://kustomize.io) to build your manifests from templates, you must redirect the output to one or more files under the `manifests/` directory. For example:
46+
47+
```sh
48+
kustomize build templates > manifests/manifests.yaml
49+
```
50+
51+
For more information, see [Building a plain bundle > Prerequisites](https://github.com/operator-framework/rukpak/blob/main/docs/bundles/plain.md#prerequisites).
52+
53+
1. Create a Dockerfile at the root of your project:
54+
55+
```sh
56+
touch plainbundle.Dockerfile
57+
```
58+
59+
1. Make the following changes to your Dockerfile:
60+
61+
*Example Dockerfile*
62+
63+
```sh
64+
FROM scratch
65+
ADD manifests /manifests
66+
```
67+
68+
> **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.
69+
70+
1. 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.
71+
72+
*Example build command*
73+
74+
```sh
75+
docker build -f plainbundle.Dockerfile -t \
76+
quay.io/<organization_name>/<repository_name>:<image_tag> .
77+
```
78+
79+
1. Push the image to your remote registry:
80+
81+
```sh
82+
docker push quay.io/<organization_name>/<repository_name>:<image_tag>
83+
```
84+
85+
### Additional resources
86+
87+
* [File-based catalog bundle schema](https://github.com/operator-framework/olm-docs/blob/master/content/en/docs/Reference/file-based-catalogs.md)
88+
* [OCI image specification](https://github.com/opencontainers/image-spec#oci-image-format-specification)
89+
* [RukPak > Building a plain bundle > Image source](https://github.com/operator-framework/rukpak/blob/main/docs/bundles/plain.md#image-source)
90+
* [RukPak > Sources > Images > Private image registries](https://github.com/operator-framework/rukpak/blob/main/docs/sources/image.md#private-image-registries)
91+
92+
## Creating a file-based catalog
93+
94+
If you do not have a file-based catalog, you must perform the following steps to initialize the catalog.
95+
96+
<h3 id="prereqs-creating-a-fbc">
97+
Prerequisites
98+
</h3>
99+
100+
* `opm` CLI tool
101+
* Docker or Podman
102+
103+
<h3 id="proc-creating-a-fbc">
104+
Procedure
105+
</h3>
106+
107+
1. Create a directory for the catalog by running the following command:
108+
109+
```sh
110+
mkdir <catalog_dir>
111+
```
112+
113+
1. In the same directory level, create a Dockerfile that can build a catalog image:
114+
115+
```sh
116+
touch Dockerfile
117+
```
118+
119+
* The Dockerfile must be in the same parent directory as the catalog directory that you created in the previous step:
120+
*Example directory structure*
121+
122+
```sh
123+
.
124+
├── <catalog_dir>
125+
└── <catalog_dir>.Dockerfile
126+
```
127+
128+
1. Make the following changes to your Dockerfile:
129+
130+
*Example Dockerfile*
131+
132+
```sh
133+
FROM scratch
134+
ADD <catalog_dir> /configs
135+
```
136+
137+
> **Note:** Use the `FROM scratch` directive to make the size of the image smaller.
138+
139+
1. Populate the catalog with the package definition for your Operator by running the `opm init` command:
140+
141+
```sh
142+
opm init <operator_name> \
143+
--output json \
144+
> <catalog_dir>/index.json
145+
```
146+
147+
This command generates an `olm.package` declarative config blob in the specified catalog configuration file.
148+
149+
## Adding a plain bundle to your file-based catalog
150+
151+
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.
152+
153+
<h3 id="prereqs-adding-a-plain-bundle-to-fbc">
154+
Prerequisites
155+
</h3>
156+
157+
* `opm` CLI tool
158+
* A plain bundle image
159+
* A file-based catalog
160+
* Push access to a container registry, such as [Quay](https://quay.io)
161+
* Docker or Podman
162+
163+
<h3 id="proc-adding-a-plain-bundle-to-fbc">
164+
Procedure
165+
</h3>
166+
167+
1. Verify that your catalog's `index.json` or `index.yaml` file is similar to the following example:
168+
169+
*Example `<catalog_dir>/index.json` file*
170+
171+
```json
172+
{
173+
{
174+
"schema": "olm.package",
175+
"name": "<operator_name>",
176+
}
177+
}
178+
```
179+
180+
1. To create an `olm.bundle` blob, edit your `index.json` or `index.yaml` file, similar to the following example:
181+
182+
*Example `<catalog_dir>/index.json` file*
183+
184+
```json
185+
{
186+
"schema": "olm.bundle",
187+
"name": "<operator_name>.v<version>",
188+
"package": "<operator_name>",
189+
"image": "quay.io/<organization_name>/<repository_name>:<image_tag>",
190+
"properties": [
191+
{
192+
"type": "olm.package",
193+
"value": {
194+
"packageName": "<operator_name>",
195+
"version": "<bundle_version>"
196+
}
197+
},
198+
{
199+
"type": "olm.bundle.mediatype",
200+
"value": "plain+v0"
201+
}
202+
]
203+
}
204+
```
205+
206+
1. To create an `olm.channel` blob, edit your `index.json` or `index.yaml` file, similar to the following example:
207+
208+
*Example `<catalog_dir>/index.json` file*
209+
210+
```json
211+
{
212+
"schema": "olm.channel",
213+
"name": "<desired_channel_name>",
214+
"package": "<operator_name>",
215+
"entries": [
216+
{
217+
"name": "<operator_name>.v<version>"
218+
}
219+
]
220+
}
221+
```
222+
223+
> **Note:** Please refer to [channel naming conventions](https://olm.operatorframework.io/docs/best-practices/channel-naming/) for choosing the <desired_channel_name>. An example of the <desired_channel_name> is `candidate-v0`.
224+
225+
<h3 id="verify-adding-a-plain-bundle-to-fbc">
226+
Verification
227+
</h3>
228+
229+
1. Open your `index.json` or `index.yaml` file and ensure it is similar to the following example:
230+
231+
*Example `index.json` file*
232+
233+
```json
234+
{
235+
"schema": "olm.package",
236+
"name": "example-operator",
237+
}
238+
{
239+
"schema": "olm.bundle",
240+
"name": "example-operator.v0.0.1",
241+
"package": "example-operator",
242+
"image": "quay.io/rashmigottipati/example-operator-bundle:v0.0.1",
243+
"properties": [
244+
{
245+
"type": "olm.package",
246+
"value": {
247+
"packageName": "example-operator",
248+
"version": "v0.0.1"
249+
}
250+
},
251+
{
252+
"type": "olm.bundle.mediatype",
253+
"value": "plain+v0"
254+
}
255+
]
256+
}
257+
{
258+
"schema": "olm.channel",
259+
"name": "preview",
260+
"package": "example-operator",
261+
"entries": [
262+
{
263+
"name": "example-operator.v0.0.1"
264+
}
265+
]
266+
}
267+
```
268+
269+
## Building and publishing a file-based catalog
270+
271+
<h3 id="proc-building-and-publishing-a-fbc">
272+
Procedure
273+
</h3>
274+
275+
1. Run the following command to build your catalog as an image:
276+
277+
```sh
278+
docker build -f <catalog_dir>.Dockerfile -t \
279+
quay.io/<organization_name>/<repository_name>:<image_tag> .
280+
```
281+
282+
1. Run the following command to push the catalog image:
283+
284+
```sh
285+
docker push quay.io/<organization_name>/<repository_name>:<image_tag>
286+
```

0 commit comments

Comments
 (0)
Please sign in to comment.