Merge pull request #53795 from michaelryanpeter/osdocs-4624-olm-4.12-catalog-source-psa

OSDOCS-4624: [OLM][4.12] Document PSA changes to the CatalogSource

Author: michaelryanpeter

modules/olm-accessing-images-private-registries.adoc

@@ -128,6 +128,8 @@ spec:
   secrets: <1>
   - "<secret_name_1>"
   - "<secret_name_2>"
+  grpcPodConfig:
+    securityContextConfig: <security_mode> <2>
   image: <registry>:<port>/<namespace>/<image>:<tag>
   displayName: My Operator Catalog
   publisher: <publisher_name>
@@ -136,6 +138,7 @@ spec:
       interval: 30m
 ----
 <1> Add a `spec.secrets` section and specify any required secrets.
+<2> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`.
 
 . If any Operator or Operand images that are referenced by a subscribed Operator require access to a private registry, you can either provide access to all namespaces in the cluster, or individual target tenant namespaces.
 

modules/olm-catalog-source-and-psa.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-managing-custom-catalogs.adoc
+
+:_content-type: CONCEPT
+[id="olm-catalog-sources-and-psa_{context}"]
+= Catalog sources and pod security admission
+
+_Pod security admission_ was introduced in {product-title} 4.11 to ensure pod security standards. Catalog sources built using the SQLite-based catalog format and a version of the `opm` CLI tool released before {product-title} 4.11 cannot run under restricted pod security enforcement.
+
+In {product-title} {product-version}, namespaces do not have restricted pod security enforcement by default and the default catalog source security mode is set to `legacy`.  
+
+Default restricted enforcement for all namespaces is planned for inclusion in a future {product-title} release. When restricted enforcement occurs, the security context of the pod specification for catalog source pods must match the restricted pod security standard. If your catalog source image requires a different pod security standard, the pod security admissions label for the namespace must be explicitly set.
+
+[NOTE]
+====
+If you do not want to run your SQLite-based catalog source pods as restricted, you do not need to update your catalog source in {product-title} {product-version}.
+
+However, it is recommended that you take action now to ensure your catalog sources run under restricted pod security enforcement. If you do not take action to ensure your catalog sources run under restricted pod security enforcement, your catalog sources might not run in future {product-title} releases.
+====
+
+As a catalog author, you can enable compatibility with restricted pod security enforcement by completing either of the following actions:
+
+* Migrate your catalog to the file-based catalog format.
+* Update your catalog image with a version of the `opm` CLI tool released with {product-title} 4.11 or later.
+
+[NOTE]
+====
+The SQLite database catalog format is deprecated, but still supported by Red Hat. In a future release, the SQLite database format will not be supported, and catalogs will need to migrate to the file-based catalog format. As of {product-title} 4.11, the default Red Hat-provided Operator catalog is released in the file-based catalog format. File-based catalogs are compatible with restricted pod security enforcement.
+====
+
+If you do not want to update your SQLite database catalog image or migrate your catalog to the file-based catalog format, you can configure your catalog to run with elevated permissions.

modules/olm-catalogsource.adoc

@@ -41,16 +41,18 @@ spec:
   priority: -400 <6>
   publisher: Example Org
   sourceType: grpc <7>
+  grpcPodConfig:
+    securityContextConfig: <security_mode> <8>
   updateStrategy:
-    registryPoll: <8>
+    registryPoll: <9>
       interval: 30m0s
 status:
   connectionState:
     address: example-catalog.{global_ns}.svc:50051
     lastConnect: 2021-08-26T18:14:31Z
-    lastObservedState: READY <9>
-  latestImageRegistryPoll: 2021-08-26T18:46:25Z <10>
-  registryService: <11>
+    lastObservedState: READY <10>
+  latestImageRegistryPoll: 2021-08-26T18:46:25Z <11>
+  registryService: <12>
     createdAt: 2021-08-26T16:16:37Z
     port: 50051
     protocol: grpc
@@ -72,8 +74,9 @@ Set the `olm.catalogImageTemplate` annotation to your index image name and use o
 * `grpc` with an `address` field: OLM attempts to contact the gRPC API at the given address. This should not be used in most cases.
 * `configmap`: OLM parses config map data and runs a pod that can serve the gRPC API over it.
 --
-<8> Automatically check for new versions at a given interval to stay up-to-date.
-<9> Last observed state of the catalog connection. For example:
+<8> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`.
+<9> Automatically check for new versions at a given interval to stay up-to-date.
+<10> Last observed state of the catalog connection. For example:
 +
 --
 * `READY`: A connection is successfully established.
@@ -82,8 +85,8 @@ Set the `olm.catalogImageTemplate` annotation to your index image name and use o
 --
 +
 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.
-<10> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
-<11> Status information for the catalog's Operator Registry service.
+<11> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
+<12> Status information for the catalog's Operator Registry service.
 ====
 
 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

@@ -50,18 +50,21 @@ metadata:
   namespace: {namespace} <2>
 spec:
   sourceType: grpc
-  image: <registry>/<namespace>/{index-image}:{tag} <3>
+  grpcPodConfig:
+    securityContextConfig: <security_mode> <3>
+  image: <registry>/<namespace>/{index-image}:{tag} <4>
   displayName: My Operator Catalog
-  publisher: <publisher_name> <4>
+  publisher: <publisher_name> <5>
   updateStrategy:
-    registryPoll: <5>
+    registryPoll: <6>
       interval: 30m
 ----
 <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.
 <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.
-<3> Specify your index image.
-<4> Specify your name or an organization name publishing the catalog.
-<5> Catalog sources can automatically check for new versions to keep up to date.
+<3> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`.
+<4> Specify your index image.
+<5> Specify your name or an organization name publishing the catalog.
+<6> Catalog sources can automatically check for new versions to keep up to date.
 endif::[]
 ifndef::olm-restricted-networks[]
 [source,yaml,subs="attributes+"]
@@ -76,18 +79,21 @@ metadata:
       "<registry>/<namespace>/<index_image_name>:v{kube_major_version}.{kube_minor_version}.{kube_patch_version}"
 spec:
   sourceType: grpc
-  image: <registry>/<namespace>/<index_image_name>:<tag> <3>
+  grpcPodConfig:
+    securityContextConfig: <security_mode> <3>
+  image: <registry>/<namespace>/<index_image_name>:<tag> <4>
   displayName: My Operator Catalog
-  publisher: <publisher_name> <4>
+  publisher: <publisher_name> <5>
   updateStrategy:
-    registryPoll: <5>
+    registryPoll: <6>
       interval: 30m
 ----
 <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.
 <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.
-<3> Specify your index image.
-<4> Specify your name or an organization name publishing the catalog.
-<5> Catalog sources can automatically check for new versions to keep up to date.
+<3> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`.
+<4> Specify your index image.
+<5> Specify your name or an organization name publishing the catalog.
+<6> Catalog sources can automatically check for new versions to keep up to date.
 endif::[]
 
 .. Use the file to create the `CatalogSource` object:

modules/olm-dependency-resolution-preferences.adoc

@@ -22,10 +22,13 @@ metadata:
   namespace: "operators"
 spec:
   sourceType: grpc
+  grpcPodConfig:
+    securityContextConfig: <security_mode> <1>
   image: example.com/my/operator-index:v1
   displayName: "My Operators"
   priority: 100
 ----
+<1> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`.
 
 A `CatalogSource` object has a `priority` field, which is used by the resolver to know how to prefer options for a dependency.
 

modules/olm-migrating-sqlite-catalog-to-fbc.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-managing-custom-catalogs.adoc
+
+:_content-type: PROCEDURE
+[id="olm-migrating-sqlite-catalog-to-fbc_{context}"]
+= Migrating SQLite database catalogs to the file-based catalog format
+
+You can update your deprecated SQLite database format catalogs to the file-based catalog format.
+
+.Prerequisites
+
+* SQLite database catalog source
+* Cluster administrator permissions
+* Latest version of the `opm` CLI tool released with {product-title} {product-version} on workstation
+
+.Procedure
+
+. Migrate your SQLite database catalog to a file-based catalog by running the following command:
++
+[source,terminal]
+----
+$ opm migrate <registry_image> <fbc_directory>
+----
+
+. Generate a Dockerfile for your file-based catalog by running the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ opm generate dockerfile <fbc_directory> \
+  --binary-image \
+  registry.redhat.io/openshift4/ose-operator-registry:v{product-version}
+----
+
+.Next steps
+
+* The generated Dockerfile can be built, tagged, and pushed to your registry.

modules/olm-sqlite-catalog-configuring-elevated-permissions.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-managing-custom-catalogs.adoc
+
+:_content-type: PROCEDURE
+[id="olm-sqlite-catalog-elevated-privileges_{context}"]
+= Configuring catalogs to run with elevated permissions
+
+If you do not want to update your SQLite database catalog image or migrate your catalog to the file-based catalog format, you can perform the following actions to ensure your catalog source runs when the default pod security enforcement changes to restricted:
+
+* Manually set the catalog security mode to legacy in your catalog source definition. This action ensures your catalog runs with legacy permissions even if the default catalog security mode changes to restricted.
+* Label the catalog source namespace for baseline or privileged pod security enforcement.
+
+[NOTE]
+====
+The SQLite database catalog format is deprecated, but still supported by Red Hat. In a future release, the SQLite database format will not be supported, and catalogs will need to migrate to the file-based catalog format. File-based catalogs are compatible with restricted pod security enforcement.
+====
+
+.Prerequisites
+
+* SQLite database catalog source
+* Cluster administrator permissions
+* Target namespace that supports running pods with the elevated pod security admission standard of `baseline` or `privileged`
+
+.Procedure
+
+. Edit the `CatalogSource` definition by setting the `spec.grpcPodConfig.securityContextConfig` label to `legacy`, as shown in the following example:
++
+.Example `CatalogSource` definition
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: CatalogSource
+metadata:
+  name: my-catsrc
+  namespace: my-ns
+spec:
+  sourceType: grpc
+  grpcPodConfig:
+    securityContextConfig: legacy
+  image: my-image:latest
+----
++
+[TIP]
+====
+In {product-title} {product-version}, the `spec.grpcPodConfig.securityContextConfig` field is set to `legacy` by default. In a future release of {product-title}, it is planned that the default setting will change to `restricted`. If your catalog cannot run under restricted enforcement, it is recommended that you manually set this field to `legacy`.
+====
+
+. Edit your `<namespace>.yaml` file to add elevated pod security admission standards to your catalog source namespace, as shown in the following example:
++
+.Example `<namespace>.yaml` file
+[source,yaml]
+----
+apiVersion: v1
+kind: Namespace
+metadata:
+...
+  labels:
+    security.openshift.io/scc.podSecurityLabelSync: "false" <1>
+    openshift.io/cluster-monitoring: "true"
+    pod-security.kubernetes.io/enforce: baseline <2>
+  name: "<namespace_name>"
+----
+<1> Turn off pod security label synchronization by adding the `security.openshift.io/scc.podSecurityLabelSync=false` label to the namespace.
+<2> Apply the pod security admission `pod-security.kubernetes.io/enforce` label. Set the label to `baseline` or `privileged`. Use the `baseline` pod security profile unless other workloads in the namespace require a `privileged` profile.

modules/olm-updating-sqlite-catalog-to-a-new-opm-version.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-managing-custom-catalogs.adoc
+
+:_content-type: PROCEDURE
+[id="olm-updating-sqlite-catalog-to-a-new-opm-version_{context}"]
+= Rebuilding SQLite database catalog images
+
+You can rebuild your SQLite database catalog image with the latest version of the `opm` CLI tool that is released with your version of {product-title}.
+
+.Prerequisites
+
+* SQLite database catalog source
+* Cluster administrator permissions
+* Latest version of the `opm` CLI tool released with {product-title} {product-version} on workstation
+
+.Procedure
+
+* Run the following command to rebuild your catalog with a more recent version of the `opm` CLI tool:
++
+[source,terminal,subs="attributes+"]
+----
+$ opm index add --binary-image \
+  registry.redhat.io/openshift4/ose-operator-registry:v{product-version} \
+  --from-index <your_registry_image> \
+  --bundles "" -t \<your_registry_image>
+----

modules/osdk-publish-catalog.adoc

@@ -78,12 +78,15 @@ spec:
   displayName: My Test
   publisher: Company
   sourceType: grpc
-  image: quay.io/example/memcached-catalog:v0.0.1 <1>
+  grpcPodConfig:
+    securityContextConfig: <security_mode> <1>
+  image: quay.io/example/memcached-catalog:v0.0.1 <2>
   updateStrategy:
     registryPoll:
       interval: 10m
 ----
-<1> Set `image` to the image pull spec you used previously with the `CATALOG_IMG` argument.
+<1> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`.
+<2> Set `image` to the image pull spec you used previously with the `CATALOG_IMG` argument.
 
 . Check the catalog source:
 +

modules/sbo-deploying-a-postgresql-database-operator-power-z.adoc

@@ -82,4 +82,4 @@ $ oc get subs -n openshift-operators
 NAME                               PACKAGE                            SOURCE                  CHANNEL
 postgresql-operator-dev4devs-com   postgresql-operator-dev4devs-com   ibm-multiarch-catalog   alpha
 rh-service-binding-operator        rh-service-binding-operator        redhat-operators        stable
-----
+----