Skip to content

Commit 2d62321

Browse files
adellapeadellape
authored
Merge pull request #63086 from adellape/plainv0_proc
2 parents 7d61aef + d357c10 commit 2d62321

File tree

10 files changed

+377
-0
lines changed

10 files changed

+377
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1869,6 +1869,16 @@ Topics:
18691869
Distros: openshift-origin
18701870
- Name: Cluster Operators reference
18711871
File: operator-reference
1872+
- Name: OLM v1 (Technology Preview)
1873+
Dir: olm_v1
1874+
Distros: openshift-origin,openshift-enterprise
1875+
Topics:
1876+
- Name: About OLM v1
1877+
File: index
1878+
- Name: Packaging format
1879+
File: olmv1-packaging-format
1880+
- Name: Managing catalogs
1881+
File: olmv1-managing-catalogs
18721882
---
18731883
Name: CI/CD
18741884
Dir: cicd

‎modules/olm-rukpak-about.adoc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,17 @@
44

55
:_content-type: CONCEPT
66
[id="olm-rukpak-about_{context}"]
7+
ifeval::["{context}" == "olm-packaging-format"]
78
= RukPak (Technology Preview)
89

910
:FeatureName: RukPak
1011
include::snippets/technology-preview.adoc[]
1112

1213
{product-title} 4.12 introduces the _platform Operator_ type as a Technology Preview feature. The platform Operator mechanism relies on the RukPak component, also introduced in {product-title} 4.12, and its resources to manage content.
14+
endif::[]
15+
ifeval::["{context}" == "olmv1-packaging-format"]
16+
= RukPak
17+
endif::[]
1318

1419
RukPak consists of a series of controllers, known as _provisioners_, that install and manage content on a Kubernetes cluster. RukPak also provides two primary APIs: `Bundle` and `BundleDeployment`. These components work together to bring content onto the cluster and install it, generating resources within the cluster.
1520

‎modules/olmv1-catalog-plain.adoc

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/olm_v1/olmv1-managing-catalogs.adoc
4+
5+
ifdef::openshift-origin[]
6+
:registry-image: quay.io/operator-framework/opm:latest
7+
endif::[]
8+
ifndef::openshift-origin[]
9+
:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v{product-version}
10+
endif::[]
11+
12+
:_content-type: PROCEDURE
13+
14+
[id="olmv1-building-plain-bundle-image-source_{context}"]
15+
= Building a plain bundle image from an image source
16+
17+
The Operator Controller currently supports installing plain bundles created only from a _plain bundle image_.
18+
19+
.Prequisites
20+
21+
* You have Kubernetes manifests for your bundle in a flat directory at the root of your project similar to the following structure:
22+
+
23+
.Example directory structure
24+
[source,terminal]
25+
----
26+
manifests
27+
├── namespace.yaml
28+
├── service_account.yaml
29+
├── cluster_role.yaml
30+
├── cluster_role_binding.yaml
31+
└── deployment.yaml
32+
----
33+
34+
.Procedure
35+
36+
. At the root of your project, create a Dockerfile that can build a bundle image:
37+
+
38+
.Example `plainbundle.Dockerfile`
39+
[source,docker]
40+
----
41+
FROM scratch <1>
42+
ADD manifests /manifests
43+
----
44+
<1> Use the `FROM scratch` directive to make the size of the image smaller. No other files or directories are required in the bundle image.
45+
46+
. Build an OCI-compliant image using your preferred build tool, similar to the following example:
47+
+
48+
[source,terminal]
49+
----
50+
$ podman build -f plainbundle.Dockerfile -t \
51+
quay.io/<organization_name>/<repository_name>:<image_tag> . <1>
52+
----
53+
<1> Use an image tag that references a repository where you have push access privileges.
54+
55+
. Push the image to your remote registry:
56+
+
57+
[source,terminal]
58+
----
59+
$ podman push quay.io/<organization_name>/<repository_name>:<image_tag>
60+
----
61+
62+
[id="olmv1-creating-fbc_{context}"]
63+
= Creating a file-based catalog
64+
65+
If you do not have a file-based catalog, you must perform the following steps to initialize the catalog.
66+
67+
.Procedure
68+
69+
. Create a directory for the catalog by running the following command:
70+
+
71+
[source,terminal]
72+
----
73+
$ mkdir <catalog_dir>
74+
----
75+
76+
. Generate a Dockerfile that can build a catalog image by running the `opm generate dockerfile` command in the same directory level as the previous step:
77+
+
78+
[source,terminal,subs="attributes+"]
79+
----
80+
ifdef::openshift-origin[]
81+
$ opm generate dockerfile <catalog_dir>
82+
endif::[]
83+
ifndef::openshift-origin[]
84+
$ opm generate dockerfile <catalog_dir> \
85+
-i {registry-image} <1>
86+
endif::[]
87+
----
88+
ifndef::openshift-origin[]
89+
<1> Specify the official Red Hat base image by using the `-i` flag, otherwise the Dockerfile uses the default upstream image.
90+
endif::[]
91+
+
92+
[NOTE]
93+
====
94+
The generated Dockerfile must be in the same parent directory as the catalog directory that you created in the previous step:
95+
96+
.Example directory structure
97+
[source,terminal]
98+
----
99+
.
100+
├── <catalog_dir>
101+
└── <catalog_dir>.Dockerfile
102+
----
103+
====
104+
105+
. Populate the catalog with the package definition for your extension by running the `opm init` command:
106+
+
107+
[source,terminal]
108+
----
109+
$ opm init <extension_name> \
110+
--output json \
111+
> <catalog_dir>/index.json
112+
----
113+
+
114+
This command generates an `olm.package` declarative config blob in the specified catalog configuration file.
115+
116+
[id="olmv1-adding-plain-bundle-to-fbc_{context}"]
117+
= Adding a plain bundle to a file-based catalog
118+
119+
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 procedure.
120+
121+
.Procedure
122+
123+
. Verify that your catalog's `index.json` or `index.yaml` file is similar to the following example:
124+
+
125+
.Example `<catalog_dir>/index.json` file
126+
[source,json]
127+
----
128+
{
129+
{
130+
"schema": "olm.package",
131+
"name": "<extension_name>",
132+
"defaultChannel": ""
133+
}
134+
}
135+
----
136+
137+
. To create an `olm.bundle` blob, edit your `index.json` or `index.yaml` file, similar to the following example:
138+
+
139+
.Example `<catalog_dir>/index.json` file with `olm.bundle` blob
140+
[source,json]
141+
----
142+
{
143+
"schema": "olm.bundle",
144+
"name": "<extension_name>.v<version>",
145+
"package": "<extension_name>",
146+
"image": "quay.io/<organization_name>/<repository_name>:<image_tag>",
147+
"properties": [
148+
{
149+
"type": "olm.package",
150+
"value": {
151+
"packageName": "<extension_name>",
152+
"version": "<bundle_version>"
153+
}
154+
},
155+
{
156+
"type": "olm.bundle.mediatype",
157+
"value": "plain+v0"
158+
}
159+
]
160+
}
161+
----
162+
163+
. To create an `olm.channel` blob, edit your `index.json` or `index.yaml` file, similar to the following example:
164+
+
165+
.Example `<catalog_dir>/index.json` file with `olm.channel` blob
166+
[source,json]
167+
----
168+
{
169+
"schema": "olm.channel",
170+
"name": "<desired_channel_name>",
171+
"package": "<extension_name>",
172+
"entries": [
173+
{
174+
"name": "<extension_name>.v<version>"
175+
}
176+
]
177+
}
178+
----
179+
180+
// 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`.
181+
182+
.Verification
183+
184+
* Open your `index.json` or `index.yaml` file and ensure it is similar to the following example:
185+
+
186+
.Example `<catalog_dir>/index.json` file
187+
[source,json]
188+
----
189+
{
190+
"schema": "olm.package",
191+
"name": "example-extension",
192+
}
193+
{
194+
"schema": "olm.bundle",
195+
"name": "example-extension.v0.0.1",
196+
"package": "example-extension",
197+
"image": "quay.io/rashmigottipati/example-extension-bundle:v0.0.1",
198+
"properties": [
199+
{
200+
"type": "olm.package",
201+
"value": {
202+
"packageName": "example-extension",
203+
"version": "v0.0.1"
204+
}
205+
},
206+
{
207+
"type": "olm.bundle.mediatype",
208+
"value": "plain+v0"
209+
}
210+
]
211+
}
212+
{
213+
"schema": "olm.channel",
214+
"name": "preview",
215+
"package": "example-extension",
216+
"entries": [
217+
{
218+
"name": "example-extension.v0.0.1"
219+
}
220+
]
221+
}
222+
----
223+
224+
[id="olmv1-publishing-fbc_{context}"]
225+
= Building and publishing a file-based catalog
226+
227+
.Procedure
228+
229+
. Build your file-bsaed catalog as an image by running the following command:
230+
+
231+
[source,terminal]
232+
----
233+
$ podman build -f <catalog_dir>.Dockerfile -t \
234+
quay.io/<organization_name>/<repository_name>:<image_tag> .
235+
----
236+
237+
. Push your catalog image by running the following command:
238+
+
239+
[source,terminal]
240+
----
241+
$ podman push quay.io/<organization_name>/<repository_name>:<image_tag>
242+
----
243+
244+
:!registry-image:

‎operators/olm_v1/_attributes

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../_attributes/

‎operators/olm_v1/images

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../images/

‎operators/olm_v1/index.adoc

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
:_content-type: ASSEMBLY
2+
[id="olmv1-about"]
3+
= About Operator Lifecycle Manager v1 (Technology Preview)
4+
include::_attributes/common-attributes.adoc[]
5+
:context: olmv1-about
6+
7+
toc::[]
8+
9+
{product-title} 4.14 introduces components for a next-generation iteration of Operator Lifecycle Manager (OLM) as a Technology Preview feature. Known during this phase as OLM v1, the updated framework evolves many of the concepts that have been part of the version of OLM included since the release of {product-title} 4.
10+
11+
:FeatureName: OLM v1
12+
include::snippets/technology-preview.adoc[]
13+
14+
During this Technology Preview phase of OLM v1 in {product-title} 4.14, administrators can use file-based catalogs to install and manage the following:
15+
16+
* OLM-based Operators, similar to the existing OLM experience
17+
* Plain bundles, which are static collections of arbitrary Kubernetes manifests
18+
19+
[id="olmv1-about-purpose"]
20+
== Purpose
21+
22+
The mission of Operator Lifecycle Manager (OLM) has been to manage the lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose has always been to make installing, running, and updating functional extensions to the cluster easy, safe, and reproducible for cluster administrators and platform-as-a-service (PaaS) administrators, throughout the lifecycle of the underlying cluster.
23+
24+
The existing version of OLM, which launched with {product-title} 4 and is included by default, was focused on providing unique support for these specific needs for a particular type of cluster extension, which have been referred as Operators. Operators are classified as one or more Kubernetes controllers, shipping with one or more API extensions (`CustomResourceDefinition` objects) to provide additional functionality to the cluster.
25+
26+
After running OLM in production clusters for many releases, it became apparent that there is a desire to deviate from this coupling of CRDs and controllers to encompass the lifecycling of extensions that are not just Operators.
27+
28+
Some of the goals of OLM v1 over the upcoming releases include improving Operator and extension lifecycle management in the following areas:
29+
30+
* Tenant isolation
31+
* Dependencies and constraints
32+
* Simplified packaging models

‎operators/olm_v1/modules

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../modules/

‎operators/olm_v1/olmv1-managing-catalogs.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
:_content-type: ASSEMBLY
2+
[id="olmv1-managing-catalogs"]
3+
= Managing catalogs for OLM v1 (Technology Preview)
4+
include::_attributes/common-attributes.adoc[]
5+
:context: olmv1-managing-catalogs
6+
7+
toc::[]
8+
9+
In OLM v1, a _plain bundle_ is a static collection of arbitrary Kubernetes manifests in YAML format. The experimental `olm.bundle.mediatype` property of the `olm.bundle` schema object differentiates a plain bundle (`plain+v0`) from a regular (`registry+v1`) bundle.
10+
11+
:FeatureName: OLM v1
12+
include::snippets/technology-preview.adoc[]
13+
14+
// For more information, see the [Plain Bundle Specification](https://github.com/operator-framework/rukpak/blob/main/docs/bundles/plain.md) in the RukPak repository.
15+
16+
As a cluster administrator, you can build and publish a file-based catalog that includes a plain bundle image by completing the following procedures:
17+
18+
. Build a plain bundle image.
19+
. Create a file-based catalog.
20+
. Add the plain bundle image to your file-based catalog.
21+
. Build your catalog as an image.
22+
. Publish your catalog image.
23+
24+
[role="_additional-resources"]
25+
.Additional resources
26+
27+
* xref:../../operators/olm_v1/olmv1-packaging-format.adoc#olmv1-packaging-format[RukPak component and packaging format]
28+
29+
[id="prerequisites_olmv1-plain-bundles"]
30+
== Prerequisites
31+
32+
- Access to an {product-title} cluster using an account with `cluster-admin` permissions
33+
- The `TechPreviewNoUpgrades` feature set enabled on the cluster
34+
+
35+
[WARNING]
36+
====
37+
Enabling the `TechPreviewNoUpgrade` feature set cannot be undone and prevents minor version updates. These feature sets are not recommended on production clusters.
38+
====
39+
- The `oc` command installed on your workstation
40+
- `opm` CLI tool
41+
- Docker or Podman
42+
- Push access to a container registry, such as link:https://quay.io[Quay]
43+
44+
[role="_additional-resources"]
45+
.Additional resources
46+
47+
* xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
48+
49+
// - Only the `redhat-operators` catalog source enabled on the cluster. This is a restriction during the Technology Preview release.
50+
51+
include::modules/olmv1-catalog-plain.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)