Skip to content

Commit bef4743

Browse files
adellapeadellape
authored
Merge pull request #45140 from adellape/numbered_callouts
2 parents dfeb780 + 4454954 commit bef4743

6 files changed

+125
-117
lines changed

‎modules/olm-catalogsource.adoc

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -30,50 +30,50 @@ The `spec` of a `CatalogSource` object indicates how to construct a pod or how t
3030
kind: CatalogSource
3131
metadata:
3232
generation: 1
33-
name: example-catalog <.>
34-
namespace: {global_ns} <.>
33+
name: example-catalog <1>
34+
namespace: {global_ns} <2>
3535
annotations:
36-
olm.catalogImageTemplate: <.>
36+
olm.catalogImageTemplate: <3>
3737
"quay.io/example-org/example-catalog:v{kube_major_version}.{kube_minor_version}.{kube_patch_version}"
3838
spec:
39-
displayName: Example Catalog <.>
40-
image: quay.io/example-org/example-catalog:v1 <.>
41-
priority: -400 <.>
39+
displayName: Example Catalog <4>
40+
image: quay.io/example-org/example-catalog:v1 <5>
41+
priority: -400 <6>
4242
publisher: Example Org
43-
sourceType: grpc <.>
43+
sourceType: grpc <7>
4444
updateStrategy:
45-
registryPoll: <.>
45+
registryPoll: <8>
4646
interval: 30m0s
4747
status:
4848
connectionState:
4949
address: example-catalog.{global_ns}.svc:50051
5050
lastConnect: 2021-08-26T18:14:31Z
51-
lastObservedState: READY <.>
52-
latestImageRegistryPoll: 2021-08-26T18:46:25Z <.>
53-
registryService: <.>
51+
lastObservedState: READY <9>
52+
latestImageRegistryPoll: 2021-08-26T18:46:25Z <10>
53+
registryService: <11>
5454
createdAt: 2021-08-26T16:16:37Z
5555
port: 50051
5656
protocol: grpc
5757
serviceName: example-catalog
5858
serviceNamespace: {global_ns}
5959
----
60-
<.> Name for the `CatalogSource` object. This value is also used as part of the name for the related pod that is created in the requested namespace.
61-
<.> Namespace to create the catalog available. To make the catalog available cluster-wide in all namespaces, set this value to `{global_ns}`. The default Red Hat-provided catalog sources also use the `{global_ns}` namespace. Otherwise, set the value to a specific namespace to make the Operator only available in that namespace.
62-
<.> Optional: To avoid cluster upgrades potentially leaving Operator installations in an unsupported state or without a continued update path, you can enable automatically changing your Operator catalog's index image version as part of cluster upgrades.
60+
<1> Name for the `CatalogSource` object. This value is also used as part of the name for the related pod that is created in the requested namespace.
61+
<2> Namespace to create the catalog available. To make the catalog available cluster-wide in all namespaces, set this value to `{global_ns}`. The default Red Hat-provided catalog sources also use the `{global_ns}` namespace. Otherwise, set the value to a specific namespace to make the Operator only available in that namespace.
62+
<3> Optional: To avoid cluster upgrades potentially leaving Operator installations in an unsupported state or without a continued update path, you can enable automatically changing your Operator catalog's index image version as part of cluster upgrades.
6363
+
6464
Set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag. The annotation overwrites the `spec.image` field at run time. See the "Image template for custom catalog sources" section for more details.
65-
<.> Display name for the catalog in the web console and CLI.
66-
<.> Index image for the catalog. Optionally, can be omitted when using the `olm.catalogImageTemplate` annotation, which sets the pull spec at run time.
67-
<.> Weight for the catalog source. OLM uses the weight for prioritization during dependency resolution. A higher weight indicates the catalog is preferred over lower-weighted catalogs.
68-
<.> Source types include the following:
65+
<4> Display name for the catalog in the web console and CLI.
66+
<5> Index image for the catalog. Optionally, can be omitted when using the `olm.catalogImageTemplate` annotation, which sets the pull spec at run time.
67+
<6> Weight for the catalog source. OLM uses the weight for prioritization during dependency resolution. A higher weight indicates the catalog is preferred over lower-weighted catalogs.
68+
<7> Source types include the following:
6969
+
7070
--
7171
* `grpc` with an `image` reference: OLM pulls the image and runs the pod, which is expected to serve a compliant API.
7272
* `grpc` with an `address` field: OLM attempts to contact the gRPC API at the given address. This should not be used in most cases.
7373
* `configmap`: OLM parses config map data and runs a pod that can serve the gRPC API over it.
7474
--
75-
<.> Automatically check for new versions at a given interval to stay up-to-date.
76-
<.> Last observed state of the catalog connection. For example:
75+
<8> Automatically check for new versions at a given interval to stay up-to-date.
76+
<9> Last observed state of the catalog connection. For example:
7777
+
7878
--
7979
* `READY`: A connection is successfully established.
@@ -82,8 +82,8 @@ Set the `olm.catalogImageTemplate` annotation to your index image name and use o
8282
--
8383
+
8484
See link:https://grpc.github.io/grpc/core/md_doc_connectivity-semantics-and-api.html[States of Connectivity] in the gRPC documentation for more details.
85-
<.> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
86-
<.> Status information for the catalog's Operator Registry service.
85+
<10> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
86+
<11> Status information for the catalog's Operator Registry service.
8787
====
8888

8989
Referencing the `name` of a `CatalogSource` object in a subscription instructs OLM where to search to find a requested Operator:

‎modules/olm-creating-catalog-from-index.adoc

Lines changed: 32 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -40,47 +40,55 @@ endif::[]
4040

4141
.. Modify the following to your specifications and save it as a `catalogSource.yaml` file:
4242
+
43+
ifdef::olm-restricted-networks[]
4344
[source,yaml,subs="attributes+"]
4445
----
4546
apiVersion: operators.coreos.com/v1alpha1
4647
kind: CatalogSource
4748
metadata:
48-
ifdef::olm-restricted-networks[]
49-
name: my-operator-catalog <.>
49+
name: my-operator-catalog <1>
50+
namespace: {namespace} <2>
51+
spec:
52+
sourceType: grpc
53+
image: <registry>/<namespace>/{index-image}:{tag} <3>
54+
displayName: My Operator Catalog
55+
publisher: <publisher_name> <4>
56+
updateStrategy:
57+
registryPoll: <5>
58+
interval: 30m
59+
----
60+
<1> If you mirrored content to local files before uploading to a registry, remove any backslash (`/`) characters from the `metadata.name` field to avoid an "invalid resource name" error when you create the object.
61+
<2> If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace.
62+
<3> Specify your index image.
63+
<4> Specify your name or an organization name publishing the catalog.
64+
<5> Catalog sources can automatically check for new versions to keep up to date.
5065
endif::[]
5166
ifndef::olm-restricted-networks[]
67+
[source,yaml,subs="attributes+"]
68+
----
69+
apiVersion: operators.coreos.com/v1alpha1
70+
kind: CatalogSource
71+
metadata:
5272
name: my-operator-catalog
53-
endif::[]
54-
namespace: {namespace} <.>
55-
ifndef::olm-restricted-networks[]
73+
namespace: {namespace} <1>
5674
annotations:
57-
olm.catalogImageTemplate: <.>
75+
olm.catalogImageTemplate: <2>
5876
"<registry>/<namespace>/<index_image_name>:v{kube_major_version}.{kube_minor_version}.{kube_patch_version}"
59-
endif::[]
6077
spec:
6178
sourceType: grpc
62-
ifdef::olm-restricted-networks[]
63-
image: <registry>/<namespace>/{index-image}:{tag} <.>
64-
endif::[]
65-
ifndef::olm-restricted-networks[]
66-
image: <registry>/<namespace>/<index_image_name>:<tag> <.>
67-
endif::[]
79+
image: <registry>/<namespace>/<index_image_name>:<tag> <3>
6880
displayName: My Operator Catalog
69-
publisher: <publisher_name> <.>
81+
publisher: <publisher_name> <4>
7082
updateStrategy:
71-
registryPoll: <.>
83+
registryPoll: <5>
7284
interval: 30m
7385
----
74-
<.> If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace.
75-
ifndef::olm-restricted-networks[]
76-
<.> Optional: Set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag.
77-
endif::[]
78-
ifdef::olm-restricted-networks[]
79-
<.> If you mirrored content to local files before uploading to a registry, remove any backslash (`/`) characters from the `metadata.name` field to avoid an "invalid resource name" error when you create the object.
86+
<1> If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace.
87+
<2> Optional: Set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag.
88+
<3> Specify your index image.
89+
<4> Specify your name or an organization name publishing the catalog.
90+
<5> Catalog sources can automatically check for new versions to keep up to date.
8091
endif::[]
81-
<.> Specify your index image.
82-
<.> Specify your name or an organization name publishing the catalog.
83-
<.> Catalog sources can automatically check for new versions to keep up to date.
8492

8593
.. Use the file to create the `CatalogSource` object:
8694
+

‎modules/olm-creating-fb-catalog-image.adoc

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -67,32 +67,32 @@ The Dockerfile must be in the same parent directory as the catalog directory tha
6767
+
6868
[source,terminal]
6969
----
70-
$ opm init <operator_name> \ <.>
71-
--default-channel=preview \ <.>
72-
--description=./README.md \ <.>
73-
--icon=./operator-icon.svg \ <.>
74-
--output yaml \ <.>
75-
> <operator_name>-index/index.yaml <.>
76-
----
77-
<.> Operator, or package, name.
78-
<.> Channel that subscription will default to if unspecified.
79-
<.> Path to the Operator's `README.md` or other documentation.
80-
<.> Path to the Operator's icon.
81-
<.> Output format: JSON or YAML.
82-
<.> Path for creating the catalog configuration file.
70+
$ opm init <operator_name> \ <1>
71+
--default-channel=preview \ <2>
72+
--description=./README.md \ <3>
73+
--icon=./operator-icon.svg \ <4>
74+
--output yaml \ <5>
75+
> <operator_name>-index/index.yaml <6>
76+
----
77+
<1> Operator, or package, name.
78+
<2> Channel that subscription will default to if unspecified.
79+
<3> Path to the Operator's `README.md` or other documentation.
80+
<4> Path to the Operator's icon.
81+
<5> Output format: JSON or YAML.
82+
<6> Path for creating the catalog configuration file.
8383
+
8484
This command generates an `olm.package` declarative config blob in the specified catalog configuration file.
8585

8686
. Add a bundle to the catalog:
8787
+
8888
[source,terminal]
8989
----
90-
$ opm render <registry>/<namespace>/<bundle_image_name>:<tag> \ <.>
90+
$ opm render <registry>/<namespace>/<bundle_image_name>:<tag> \ <1>
9191
--output=yaml \
92-
>> <operator_name>-index/index.yaml <.>
92+
>> <operator_name>-index/index.yaml <2>
9393
----
94-
<.> Pull spec for the bundle image.
95-
<.> Path to the catalog configuration file.
94+
<1> Pull spec for the bundle image.
95+
<2> Path to the catalog configuration file.
9696
+
9797
The `opm render` command generates a declarative config blob from the provided catalog images and bundle images.
9898
+
@@ -111,9 +111,9 @@ schema: olm.channel
111111
package: <operator_name>
112112
name: preview
113113
entries:
114-
- name: <operator_name>.v0.1.0 <.>
114+
- name: <operator_name>.v0.1.0 <1>
115115
----
116-
<.> Ensure that you include the period (`.`) after `<operator_name>` but before the `v` in the version. Otherwise, the entry will fail to pass the `opm validate` command.
116+
<1> Ensure that you include the period (`.`) after `<operator_name>` but before the `v` in the version. Otherwise, the entry will fail to pass the `opm validate` command.
117117
118118
. Validate the file-based catalog:
119119

‎modules/olm-enabling-operator-restricted-network.adoc

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,11 @@ spec:
4242
- /manager
4343
...
4444
env:
45-
- name: <related_image_environment_variable> <.>
46-
value: "<related_image_reference_with_tag>" <.>
45+
- name: <related_image_environment_variable> <1>
46+
value: "<related_image_reference_with_tag>" <2>
4747
----
48-
<.> Define the environment variable, such as `RELATED_IMAGE_MEMCACHED`.
49-
<.> Set the related image reference and tag, such as `docker.io/memcached:1.4.36-alpine`.
48+
<1> Define the environment variable, such as `RELATED_IMAGE_MEMCACHED`.
49+
<2> Set the related image reference and tag, such as `docker.io/memcached:1.4.36-alpine`.
5050
====
5151

5252
. Replace hard-coded image references with environment variables in the relevant file for your Operator project type:
@@ -64,16 +64,16 @@ spec:
6464

6565
Spec: corev1.PodSpec{
6666
Containers: []corev1.Container{{
67-
- Image: "memcached:1.4.36-alpine", <.>
68-
+ Image: os.Getenv("<related_image_environment_variable>"), <.>
67+
- Image: "memcached:1.4.36-alpine", <1>
68+
+ Image: os.Getenv("<related_image_environment_variable>"), <2>
6969
Name: "memcached",
7070
Command: []string{"memcached", "-m=64", "-o", "modern", "-v"},
7171
Ports: []corev1.ContainerPort{{
7272

7373
...
7474
----
75-
<.> Delete the image reference and tag.
76-
<.> Use the `os.Getenv` function to call the `<related_image_environment_variable>`.
75+
<1> Delete the image reference and tag.
76+
<2> Use the `os.Getenv` function to call the `<related_image_environment_variable>`.
7777
7878
[NOTE]
7979
=====
@@ -97,15 +97,15 @@ spec:
9797
- -o
9898
- modern
9999
- -v
100-
- image: "docker.io/memcached:1.4.36-alpine" <.>
101-
+ image: "{{ lookup('env', '<related_image_environment_variable>') }}" <.>
100+
- image: "docker.io/memcached:1.4.36-alpine" <1>
101+
+ image: "{{ lookup('env', '<related_image_environment_variable>') }}" <2>
102102
ports:
103103
- containerPort: 11211
104104

105105
...
106106
----
107-
<.> Delete the image reference and tag.
108-
<.> Use the `lookup` function to call the `<related_image_environment_variable>`.
107+
<1> Delete the image reference and tag.
108+
<2> Use the `lookup` function to call the `<related_image_environment_variable>`.
109109
====
110110
111111
* For Helm-based Operator projects, add the `overrideValues` field to the `watches.yaml` file as shown in the following example:
@@ -120,11 +120,11 @@ spec:
120120
version: v1alpha1
121121
kind: Memcached
122122
chart: helm-charts/memcached
123-
overrideValues: <.>
124-
relatedImage: ${<related_image_environment_variable>} <.>
123+
overrideValues: <1>
124+
relatedImage: ${<related_image_environment_variable>} <2>
125125
----
126-
<.> Add the `overrideValues` field.
127-
<.> Define the `overrideValues` field by using the `<related_image_environment_variable>`, such as `RELATED_IMAGE_MEMCACHED`.
126+
<1> Add the `overrideValues` field.
127+
<2> Define the `overrideValues` field by using the `<related_image_environment_variable>`, such as `RELATED_IMAGE_MEMCACHED`.
128128
====
129129
130130
.. Add the value of the `overrideValues` field to the `helm-charts/memchached/values.yaml` file as shown in the following example:
@@ -148,13 +148,13 @@ containers:
148148
securityContext:
149149
- toYaml {{ .Values.securityContext | nindent 12 }}
150150
image: "{{ .Values.image.pullPolicy }}
151-
env: <.>
152-
- name: related_image <.>
153-
value: "{{ .Values.relatedImage }}" <.>
151+
env: <1>
152+
- name: related_image <2>
153+
value: "{{ .Values.relatedImage }}" <3>
154154
----
155-
<.> Add the `env` field.
156-
<.> Name the environment variable.
157-
<.> Define the value of the environment variable.
155+
<1> Add the `env` field.
156+
<2> Name the environment variable.
157+
<3> Define the value of the environment variable.
158158
====
159159
160160
. Add the `BUNDLE_GEN_FLAGS` variable definition to your `Makefile` with the following changes:
@@ -174,13 +174,13 @@ containers:
174174

175175
...
176176

177-
- $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS) <.>
178-
+ $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle $(BUNDLE_GEN_FLAGS) <.>
177+
- $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS) <1>
178+
+ $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle $(BUNDLE_GEN_FLAGS) <2>
179179

180180
...
181181
----
182-
<.> Delete this line in the `Makefile`.
183-
<.> Replace the line above with this line.
182+
<1> Delete this line in the `Makefile`.
183+
<2> Replace the line above with this line.
184184
185185
. To update your Operator image to use a digest (SHA) and not a tag, run the `make bundle` command and set `USE_IMAGE_DIGESTS` to `true` :
186186
+

0 commit comments

Comments
 (0)