Skip to content

Commit 771ee82

Browse files
adellapeadellape
authored
Merge pull request #33483 from adellape/catalog-build-push
2 parents 72be77e + 1c16fee commit 771ee82

File tree

10 files changed

+282
-43
lines changed

10 files changed

+282
-43
lines changed

modules/osdk-bundle-deploy-olm.adoc renamed to modules/osdk-bundle-operator.adoc

Lines changed: 5 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,18 @@ ifeval::["{context}" == "osdk-working-bundle-images"]
1212
:golang:
1313
endif::[]
1414

15-
[id="osdk-bundle-deploy-olm_{context}"]
16-
= Bundling an Operator and deploying with Operator Lifecycle Manager
15+
[id="osdk-bundle-operator_{context}"]
16+
= Bundling an Operator
1717

18-
Operator Lifecycle Manager (OLM) helps you to install, update, and generally manage the lifecycle of Operators and their associated services on a Kubernetes cluster. OLM is installed by default on {product-title} and runs as a Kubernetes extension so that you can use the web console and the OpenShift CLI (`oc`) for all Operator lifecycle management functions without any additional tools.
19-
20-
The Operator bundle format is the default packaging method for Operator SDK and OLM. You can get your Operator ready for OLM by using the Operator SDK to build, push, validate, and run a bundle image with OLM.
18+
The Operator bundle format is the default packaging method for Operator SDK and Operator Lifecycle Manager (OLM). You can get your Operator ready for use on OLM by using the Operator SDK to build and push your Operator project as a bundle image.
2119

2220
.Prerequisites
2321

2422
- Operator SDK CLI installed on a development workstation
2523
- OpenShift CLI (`oc`) v{product-version}+ installed
26-
- Operator Lifecycle Manager (OLM) installed on a Kubernetes-based cluster (v1.16.0 or later if you use `apiextensions.k8s.io/v1` CRDs, for example {product-title} {product-version})
27-
- Logged into the cluster with `oc` using an account with `cluster-admin` permissions
2824
- Operator project initialized by using the Operator SDK
2925
ifdef::golang[]
30-
- If your Operator is Go-based, your project must have been updated to use supported images for running on {product-title}
26+
- If your Operator is Go-based, your project must be updated to use supported images for running on {product-title}
3127
endif::[]
3228

3329
.Procedure
@@ -78,7 +74,7 @@ These files are then automatically validated by using `operator-sdk bundle valid
7874

7975
. Build and push your bundle image by running the following commands. OLM consumes Operator bundles using an index image, which reference one or more bundle images.
8076

81-
.. Build the bundle image. Set `BUNDLE_IMAGE` with the details for the registry, user namespace, and image tag where you intend to push the image:
77+
.. Build the bundle image. Set `BUNDLE_IMG` with the details for the registry, user namespace, and image tag where you intend to push the image:
8278
+
8379
[source,terminal]
8480
----
@@ -92,32 +88,6 @@ $ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>
9288
$ docker push <registry>/<user>/<bundle_image_name>:<tag>
9389
----
9490

95-
. Check the status of OLM on your cluster by using the following Operator SDK command:
96-
+
97-
[source,terminal]
98-
----
99-
$ operator-sdk olm status \
100-
--olm-namespace=openshift-operator-lifecycle-manager
101-
----
102-
103-
. Run the Operator on your cluster by using the OLM integration in Operator SDK:
104-
+
105-
[source,terminal]
106-
----
107-
$ operator-sdk run bundle \
108-
[-n <namespace>] \//<1>
109-
<registry>/<user>/<bundle_image_name>:<tag>
110-
----
111-
<1> By default, the command installs the Operator in the currently active project in your `~/.kube/config` file. You can add the `-n` flag to set a different namespace scope for the installation.
112-
+
113-
This command performs the following actions:
114-
+
115-
--
116-
* Create an index image with your bundle image injected.
117-
* Create a catalog source that points to your new index image, which enables OperatorHub to discover your Operator.
118-
* Deploy your Operator to your cluster by creating an Operator group, subscription, install plan, and all other required objects, including RBAC.
119-
--
120-
12191
ifeval::["{context}" == "osdk-golang-tutorial"]
12292
:!golang:
12393
endif::[]

‎modules/osdk-common-prereqs.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ ifdef::ansible[]
3131
- link:https://pypi.org/project/openshift/[OpenShift Python client] version v0.11.2+
3232
endif::[]
3333
- Logged into an {product-title} {product-version} cluster with `oc` with an account that has `cluster-admin` permissions
34-
- To allow the cluster pull the image, the repository where you push your image must be set as public, or you must configure an image pull secret.
34+
- To allow the cluster pull the image, the repository where you push your image must be set as public, or you must configure an image pull secret
3535

3636
ifeval::["{context}" == "osdk-ansible-quickstart"]
3737
:!ansible:

‎modules/osdk-deploy-olm.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
4+
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
5+
// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
6+
// * operators/operator_sdk/osdk-working-bundle-images.adoc
7+
8+
ifeval::["{context}" == "osdk-golang-tutorial"]
9+
:golang:
10+
endif::[]
11+
ifeval::["{context}" == "osdk-working-bundle-images"]
12+
:golang:
13+
endif::[]
14+
15+
[id="osdk-deploy-olm_{context}"]
16+
= Deploying an Operator with Operator Lifecycle Manager
17+
18+
Operator Lifecycle Manager (OLM) helps you to install, update, and manage the lifecycle of Operators and their associated services on a Kubernetes cluster. OLM is installed by default on {product-title} and runs as a Kubernetes extension so that you can use the web console and the OpenShift CLI (`oc`) for all Operator lifecycle management functions without any additional tools.
19+
20+
The Operator bundle format is the default packaging method for Operator SDK and OLM. You can use the Operator SDK to quickly run a bundle image on OLM to ensure that it runs properly.
21+
22+
.Prerequisites
23+
24+
- Operator SDK CLI installed on a development workstation
25+
- Operator bundle image built and pushed to a registry
26+
- OLM installed on a Kubernetes-based cluster (v1.16.0 or later if you use `apiextensions.k8s.io/v1` CRDs, for example {product-title} {product-version})
27+
- Logged in to the cluster with `oc` using an account with `cluster-admin` permissions
28+
ifdef::golang[]
29+
- If your Operator is Go-based, your project must be updated to use supported images for running on {product-title}
30+
endif::[]
31+
32+
.Procedure
33+
34+
. Check the status of OLM on your cluster by using the following Operator SDK command:
35+
+
36+
[source,terminal]
37+
----
38+
$ operator-sdk olm status \
39+
--olm-namespace=openshift-operator-lifecycle-manager
40+
----
41+
42+
. Run the Operator on your cluster by using the OLM integration in Operator SDK:
43+
+
44+
[source,terminal]
45+
----
46+
$ operator-sdk run bundle \
47+
[-n <namespace>] \//<1>
48+
<registry>/<user>/<bundle_image_name>:<tag>
49+
----
50+
<1> By default, the command installs the Operator in the currently active project in your `~/.kube/config` file. You can add the `-n` flag to set a different namespace scope for the installation.
51+
+
52+
This command performs the following actions:
53+
+
54+
--
55+
* Create an index image referencing your bundle image. The index image is opaque and ephemeral, but accurately reflects how a bundle would be added to a catalog in production.
56+
* Create a catalog source that points to your new index image, which enables OperatorHub to discover your Operator.
57+
* Deploy your Operator to your cluster by creating an `OperatorGroup`, `Subscription`, `InstallPlan`, and all other required objects, including RBAC.
58+
--
59+
60+
ifeval::["{context}" == "osdk-golang-tutorial"]
61+
:!golang:
62+
endif::[]
63+
ifeval::["{context}" == "osdk-working-bundle-images"]
64+
:!golang:
65+
endif::[]

‎modules/osdk-publish-catalog.adoc‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-working-bundle-images.adoc
4+
5+
[id="osdk-publish-catalog_{context}"]
6+
= Publishing a catalog containing a bundled Operator
7+
8+
To install and manage Operators, Operator Lifecycle Manager (OLM) requires that Operator bundles are listed in an index image, which is referenced by a catalog on the cluster. As an Operator author, you can use the Operator SDK to create an index containing the bundle for your Operator and all of its dependencies. This is useful for testing on remote clusters and publishing to container registries.
9+
10+
[NOTE]
11+
====
12+
The Operator SDK uses the `opm` CLI to facilitate index image creation. Experience with the `opm` command is not required. For advanced use cases, the `opm` command can be used directly instead of the Operator SDK.
13+
====
14+
15+
.Prerequisites
16+
17+
- Operator SDK CLI installed on a development workstation
18+
- Operator bundle image built and pushed to a registry
19+
- OLM installed on a Kubernetes-based cluster (v1.16.0 or later if you use `apiextensions.k8s.io/v1` CRDs, for example {product-title} {product-version})
20+
- Logged in to the cluster with `oc` using an account with `cluster-admin` permissions
21+
22+
.Procedure
23+
24+
. Run the following `make` command in your Operator project directory to build an index image containing your Operator bundle:
25+
+
26+
[source,terminal]
27+
----
28+
$ make catalog-build CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>
29+
----
30+
+
31+
where the `CATALOG_IMG` argument references a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io.
32+
33+
. Push the built index image to a repository:
34+
+
35+
[source,terminal]
36+
----
37+
$ make catalog-push CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>
38+
----
39+
+
40+
[TIP]
41+
====
42+
You can use Operator SDK `make` commands together if you would rather perform multiple actions in sequence at once. For example, if you had not yet built a bundle image for your Operator project, you can build and push both a bundle image and an index image with the following syntax:
43+
44+
[source,terminal]
45+
----
46+
$ make bundle-build bundle-push catalog-build catalog-push \
47+
BUNDLE_IMG=<bundle_image_pull_spec> \
48+
CATALOG_IMG=<index_image_pull_spec>
49+
----
50+
51+
Alternatively, you can set the `IMAGE_TAG_BASE` field in your `Makefile` to an existing repository:
52+
53+
[source,terminal]
54+
----
55+
IMAGE_TAG_BASE=quay.io/example/my-operator
56+
----
57+
58+
You can then use the following syntax to build and push images with automatically-generated names, such as `quay.io/example/my-operator-bundle:v0.0.1` for the bundle image and `quay.io/example/my-operator-catalog:v0.0.1` for the index image:
59+
60+
[source,terminal]
61+
----
62+
$ make bundle-build bundle-push catalog-build catalog-push
63+
----
64+
====
65+
66+
. Define a `CatalogSource` object that references the index image you just generated, and then create the object by using the `oc apply` command or web console:
67+
+
68+
.Example `CatalogSource` YAML
69+
[source,yaml]
70+
----
71+
apiVersion: operators.coreos.com/v1alpha1
72+
kind: CatalogSource
73+
metadata:
74+
name: cs-memcached
75+
namespace: default
76+
spec:
77+
displayName: My Test
78+
publisher: Company
79+
sourceType: grpc
80+
image: quay.io/example/memcached-catalog:v0.0.1 <1>
81+
updateStrategy:
82+
registryPoll:
83+
interval: 10m
84+
----
85+
<1> Set `image` to the image pull spec you used previously with the `CATALOG_IMG` argument.
86+
87+
. Check the catalog source:
88+
+
89+
[source,terminal]
90+
----
91+
$ oc get catalogsource
92+
----
93+
+
94+
.Example output
95+
[source,terminal]
96+
----
97+
NAME DISPLAY TYPE PUBLISHER AGE
98+
cs-memcached My Test grpc Company 4h31m
99+
----
100+
101+
.Verification
102+
103+
. Install the Operator using your catalog:
104+
105+
.. Define an `OperatorGroup` object and create it by using the `oc apply` command or web console:
106+
+
107+
.Example `OperatorGroup` YAML
108+
[source,yaml]
109+
----
110+
apiVersion: operators.coreos.com/v1
111+
kind: OperatorGroup
112+
metadata:
113+
name: my-test
114+
namespace: default
115+
spec:
116+
targetNamespaces:
117+
- default
118+
----
119+
120+
.. Define a `Subscription` object and create it by using the `oc apply` command or web console:
121+
+
122+
.Example `Subscription` YAML
123+
[source,yaml]
124+
----
125+
apiVersion: operators.coreos.com/v1alpha1
126+
kind: Subscription
127+
metadata:
128+
name: catalogtest
129+
namespace: default
130+
spec:
131+
channel: "alpha"
132+
installPlanApproval: Manual
133+
name: catalog
134+
source: cs-memcached
135+
sourceNamespace: default
136+
startingCSV: memcached-operator.v0.0.1
137+
----
138+
139+
. Verify the installed Operator is running:
140+
141+
.. Check the Operator group:
142+
+
143+
[source,terminal]
144+
----
145+
$ oc get og
146+
----
147+
+
148+
.Example output
149+
[source,terminal]
150+
----
151+
NAME AGE
152+
my-test 4h40m
153+
----
154+
155+
.. Check the cluster service version (CSV):
156+
+
157+
[source,terminal]
158+
----
159+
$ oc get csv
160+
----
161+
+
162+
.Example output
163+
[source,terminal]
164+
----
165+
NAME DISPLAY VERSION REPLACES PHASE
166+
memcached-operator.v0.0.1 Test 0.0.1 Succeeded
167+
----
168+
169+
.. Check the pods for the Operator:
170+
+
171+
[source,terminal]
172+
----
173+
$ oc get pods
174+
----
175+
+
176+
.Example output
177+
[source,terminal]
178+
----
179+
NAME READY STATUS RESTARTS AGE
180+
9098d908802769fbde8bd45255e69710a9f8420a8f3d814abe88b68f8ervdj6 0/1 Completed 0 4h33m
181+
catalog-controller-manager-7fd5b7b987-69s4n 2/2 Running 0 4h32m
182+
cs-memcached-7622r 1/1 Running 0 4h33m
183+
----

‎operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,12 @@ include::modules/osdk-run-operator.adoc[leveloffset=+1]
3434
include::modules/osdk-run-locally.adoc[leveloffset=+2]
3535
include::modules/osdk-prepare-supported-images.adoc[leveloffset=+2]
3636
include::modules/osdk-run-deployment.adoc[leveloffset=+2]
37-
include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+2]
37+
38+
[id="osdk-bundle-deploy-olm_{context}"]
39+
=== Bundling an Operator and deploying with Operator Lifecycle Manager
40+
41+
include::modules/osdk-bundle-operator.adoc[leveloffset=+4]
42+
include::modules/osdk-deploy-olm.adoc[leveloffset=+4]
3843

3944
include::modules/osdk-create-cr.adoc[leveloffset=+1]
4045

‎operators/operator_sdk/golang/osdk-golang-tutorial.adoc‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,12 @@ include::modules/osdk-run-operator.adoc[leveloffset=+1]
4343
include::modules/osdk-run-locally.adoc[leveloffset=+2]
4444
include::modules/osdk-prepare-supported-images.adoc[leveloffset=+2]
4545
include::modules/osdk-run-deployment.adoc[leveloffset=+2]
46-
include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+2]
46+
47+
[id="osdk-bundle-deploy-olm_{context}"]
48+
=== Bundling an Operator and deploying with Operator Lifecycle Manager
49+
50+
include::modules/osdk-bundle-operator.adoc[leveloffset=+4]
51+
include::modules/osdk-deploy-olm.adoc[leveloffset=+4]
4752

4853
include::modules/osdk-create-cr.adoc[leveloffset=+1]
4954

‎operators/operator_sdk/helm/osdk-helm-tutorial.adoc‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,12 @@ include::modules/osdk-run-operator.adoc[leveloffset=+1]
3636
include::modules/osdk-run-locally.adoc[leveloffset=+2]
3737
include::modules/osdk-prepare-supported-images.adoc[leveloffset=+2]
3838
include::modules/osdk-run-deployment.adoc[leveloffset=+2]
39-
include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+2]
39+
40+
[id="osdk-bundle-deploy-olm_{context}"]
41+
=== Bundling an Operator and deploying with Operator Lifecycle Manager
42+
43+
include::modules/osdk-bundle-operator.adoc[leveloffset=+4]
44+
include::modules/osdk-deploy-olm.adoc[leveloffset=+4]
4045

4146
include::modules/osdk-create-cr.adoc[leveloffset=+1]
4247

‎operators/operator_sdk/osdk-cli-ref.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ include::modules/osdk-cli-ref-generate.adoc[leveloffset=+1]
2323
include::modules/osdk-cli-ref-generate-bundle.adoc[leveloffset=+2]
2424
.Additional resources
2525

26-
* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-deploy-olm_osdk-working-bundle-images[Bundling an Operator and deploying with Operator Lifecycle Manager] for a full procedure that includes using the `make bundle` command to call the `generate bundle` subcommand.
26+
* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-operator_osdk-working-bundle-images[Bundling an Operator] for a full procedure that includes using the `make bundle` command to call the `generate bundle` subcommand.
2727

2828
include::modules/osdk-cli-ref-generate-kustomize.adoc[leveloffset=+2]
2929

‎operators/operator_sdk/osdk-generating-csvs.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ A CSV-generating command removes the responsibility of Operator authors having i
1414
include::modules/osdk-how-csv-gen-works.adoc[leveloffset=+1]
1515
.Additional resources
1616

17-
* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-deploy-olm_osdk-working-bundle-images[Bundling an Operator and deploying with Operator Lifecycle Manager] for a full procedure that includes generating a bundle and CSV.
17+
* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-operator_osdk-working-bundle-images[Bundling an Operator] for a full procedure that includes generating a bundle and CSV.
1818

1919
include::modules/osdk-csv-bundle-files.adoc[leveloffset=+2]
2020
include::modules/osdk-csv-ver.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)