Initial implementation

class/defaults.yml

@@ -1,4 +1,13 @@
 parameters:
   openshift4_operators:
     =_metadata: {}
-    namespace: syn-openshift4-operators
+    multi_instance: true
+    namespace: ${_instance}
+    defaultInstallPlanApproval: Automatic
+    defaultSourceNamespace: openshift-marketplace
+
+  openshift_operators:
+    defaultSource: certified-operators
+
+  openshift_operators_redhat:
+    defaultSource: redhat-operators

component/main.jsonnet

@@ -1,10 +1,33 @@
 // main template for openshift4-operators
 local kap = import 'lib/kapitan.libjsonnet';
 local kube = import 'lib/kube.libjsonnet';
+local operatorlib = import 'lib/openshift4-operators.libsonnet';
 local inv = kap.inventory();
-// The hiera parameters for the component
 local params = inv.parameters.openshift4_operators;
 
-// Define outputs below
+
+local namespace = operatorlib.validateInstance(params.namespace);
+
 {
+  [namespace]: [
+    kube.Namespace(namespace) {
+      metadata+: {
+        annotations+: {
+          'openshift.io/node-selector': '',
+        },
+        labels+: {
+          // enable cluster monitoring when instantiating to manage
+          // namespace openshift-operators-redhat
+          'openshift.io/cluster-monitoring':
+            namespace == 'openshift-operators-redhat',
+        },
+      },
+    },
+    // Create cluster-scoped OperatorGroup
+    operatorlib.OperatorGroup(namespace) {
+      metadata+: {
+        namespace: namespace,
+      },
+    },
+  ],
 }

docs/modules/ROOT/pages/how-tos/getting-started.adoc

@@ -0,0 +1,113 @@
+= Getting started
+
+This guide will help you to get started to use this component to configure cluster-scoped operator subscriptions.
+
+== Prerequisites
+
+* You have an OpenShift 4 cluster on which you want to configure a cluster-scoped operator subscription from a Commodore component
+* You are able to compile the cluster catalog locally
+
+== Steps
+
+[TIP]
+====
+We recommend creating an empty directory and following these steps after changing to that directory.
+
+[source,bash]
+----
+work_dir=$(mktemp -d)
+pushd "${work_dir}"
+----
+====
+
+. Make a note of the cluster and tenant IDs
++
+[source,bash]
+----
+export CLUSTER_ID=c-the-cluster-1234 <1>
+export TENANT_ID=t-the-tenant-1234 <2>
+----
+<1> Replace `c-the-cluster-1234` with the ID of your cluster
+<2> Replace `t-the-tenant-1234` with the ID of your cluster's tenant
+
+. Compile the cluster catalog so you can make changes locally
++
+[source,bash]
+----
+commodore catalog compile "${CLUSTER_ID}"
+----
+
+. Determine whether you want to deploy the operator into namespace `openshift-operators` or `openshift-operators-redhat`.
++
+[source,bash]
+----
+export INSTANCE="openshift-operators" <1>
+----
+<1> Generally, community operators should be deployed in `openshift-operators`, while official RedHat operators should be deployed in `openshift-operators-redhat`.
+If you're not sure, it's best to choose `openshift-operators`.
+
+. Ensure the component is instantiated correctly for the cluster.
++
+[source,bash]
+----
+if [ ! -f "inventory/targets/${INSTANCE}.yml" ]; then
+  yq eval -i ".applications += [\"openshift4-operators as ${INSTANCE}\"]" \
+    "inventory/classes/${TENANT_ID}/${CLUSTER_ID}.yml" <1>
+  (cd "inventory/classes/${TENANT_ID}"; git commit -av; git push origin master) <2>
+fi
+----
+<1> Configure component instance
+<2> Commit and push cluster configuration change
+
+. Now you can create a cluster-scoped operator subscription in your component's Jsonnet code
++
+[source,jsonnet]
+----
+local operatorlib = import 'lib/openshift4-operators.libsonnet';
+
+{
+  subscription: operatorlib.managedSubscription(
+    'openshift-operators', <1>
+    'elasticsearch-eck-operator-certfied', <2>
+    'stable', <3>
+  )
+}
+----
+<1> The namespace in which the subscription should be created.
+Use the same value as you've selected for `${INSTANCE}` in the 3rd step.
+<2> The name of the operator to install
+<3> The update channel for the subscription
++
+TIP: See the xref:references/component-library.adoc[component library] reference documentation for full documentation of the functions provided by the library.
+
+. Compile the catalog locally to check your changes
++
+[source,bash]
+----
+commodore catalog compile "${CLUSTER_ID}" --local
+----
++
+You should see the following YAML added to your component's catalog directory
++
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  annotations: {}
+  labels:
+    name: elasticsearch-eck-operator-certified
+  name: elasticsearch-eck-operator-certified
+  namespace: openshift-operators
+spec:
+  channel: stable
+  installPlanApproval: Automatic <1>
+  name: elasticsearch-eck-operator-certified
+  source: certified-operators <2>
+  sourceNamespace: openshift-marketplace <3>
+----
+<1> The value of this field can be changed by providing optional parameter `installPlanApproval` when calling function `registerSubscription`.
+<2> The value of this field can be changed by providing optional parameter `source` when calling function `registerSubscription`.
+<3> The value of this field can be changed by providing optional parameter `sourceNamespace` when calling function `registerSubscription`.
++
+If the component hasn't previously been instantiated for `openshift-operators`, you'll also see new YAML files in the catalog in directory `openshift4-operators`.

docs/modules/ROOT/pages/index.adoc

@@ -1,5 +1,9 @@
 = openshift4-operators
 
-openshift4-operators is a Commodore component to manage openshift4-operators.
+openshift4-operators is a Commodore component to manage target namespaces for cluster-scoped OLM-managed operators on OpenShift 4.
 
-See the xref:references/parameters.adoc[parameters] reference for further details.
+The component provides a Jsonnet library which allows other components to create cluster-scoped operator subscriptions.
+
+See the xref:how-tos/getting-started.adoc[getting started guide] to get started with the component.
+
+See the xref:references/parameters.adoc[parameters] reference for configurable options of the component.

docs/modules/ROOT/pages/references/component-library.adoc

@@ -0,0 +1,85 @@
+= Component library
+
+The component provides a component library to make creating Operator Lifecycle Manager (OLM) resources easier.
+This page documents the provided library functions.
+
+== `OperatorGroup`
+
+This function provides a wrapper to create `operatorgroups.operators.coreos.com` resources.
+
+The result of this function can be used in the same way as resources created by `kube.libjsonnet`.
+
+--
+.Arguments
+`name`:: The name of the resource. Used as `.metadata.name`.
+--
+
+== `validateInstance`
+
+This function takes an instance name and validates it against the supported instance names.
+Optionally the instance name is also validated against the instances which are present in the cluster catalog.
+
+If the validation is successful, the function returns the instance name unmodified.
+Otherwise it throws an error during catalog compilation.
+
+--
+.Arguments
+`instance`:: The instance name to validate.
+`checkTargets`:: Whether to validate the instance against configured component instances.
+`checkSource`:: An arbitrary string included in the error output when checking against configured component instances.
+This is included in the error in the following sentence `"Unknown instance '<instance>' for <checkSource>"`.
+--
+
+== `managedSubscription`
+
+This function creates a `subscriptions.operators.coreos.com` resource in a namespace managed by this component.
+
+The result of this function can be used in the same way as resources created by `kube.libjsonnet`.
+
+--
+.Arguments
+`instance`:: Name of the component instance in which to create the subscription
+`name`:: Name of the operator to install.
+Used as `.metadata.name` and `.spec.name` of the resulting `Subscription` object.
+`channel`:: The channel for the subscription.
+`source`:: The source (`CatalogSource`) for the operator.
+Defaults to `parameters.<instance>.defaultSource`.
+This argument can be omitted.
+`sourceNamespace`:: The namespace holding the `CatalogSource`.
+Defaults to `parameters.<instance>.defaultSourceNamespace`.
+This argument can be omitted.
+`installPlanApproval`:: How to manage subscription updates.
+Valid options are `Automatic` and `Manual`.
+Defaults to `parameters.<instance>.defaultInstallPlanApproval`.
+This argument can be omitted.
+--
+
+Arguments `source`, `sourceNamespace` and `installPlanApproval` are optional and default to component instance parameters `defaultSource`, `defaultSourceNamespace` and `defaultInstallPlanApproval`.
+
+== `namespacedSubscription`
+
+This function creates a `subscriptions.operators.coreos.com` resource in an arbitrary namespace.
+When using this function, the caller is responsible to ensure that an `OperatorGroup` resource exists in the target namespace.
+
+The result of this function can be used in the same way as resources created by `kube.libjsonnet`.
+
+--
+.Arguments
+`instance`:: Name of the component instance in which to create the subscription
+`name`:: Name of the operator to install.
+Used as `.metadata.name` and `.spec.name` of the resulting `Subscription` object.
+`channel`:: The channel for the subscription.
+`source`:: The source (`CatalogSource`) for the operator.
+Defaults to `parameters.<instance>.defaultSource`.
+This argument can be omitted.
+`sourceNamespace`:: The namespace holding the `CatalogSource`.
+Defaults to `parameters.<instance>.defaultSourceNamespace`.
+This argument can be omitted.
+`installPlanApproval`:: How to manage subscription updates.
+Valid options are `Automatic` and `Manual`.
+Defaults to `parameters.<instance>.defaultInstallPlanApproval`.
+This argument can be omitted.
+--
+
+Arguments `source`, `sourceNamespace` and `installPlanApproval` are optional and default to component instance parameters `defaultSource`, `defaultSourceNamespace` and `defaultInstallPlanApproval`.
+

docs/modules/ROOT/pages/references/parameters.adoc

@@ -6,14 +6,39 @@ The parent key for all of the following parameters is `openshift4_operators`.
 
 [horizontal]
 type:: string
-default:: `syn-openshift4-operators`
+default:: `${_instance}`
 
-The namespace in which to deploy this component.
+The namespace to create for the component instance.
+The component is implemented in such a way that only instances (and therefore namespaces) `openshift-operators` and `openshift-operators-redhat` can be created.
+Generally, it shouldn't be necessary to override this parameter.
 
+== `defaultInstallPlanApproval`
 
-== Example
+[horizontal]
+type:: string
+default:: `Automatic`
+
+This parameter configures the default value for the optional parameter `installPlanApproval` of the component library function `registerSubscription`.
+
+== `defaultSourceNamespace`
+
+[horizontal]
+type:: string
+default:: `openshift-marketplace`
+
+This parameter configures the default value for the optional parameter `sourceNamespace` of the component library function `registerSubscription`.
+
+== `defaultSource`
+
+[horizontal]
+type:: string
+default::
++
+* `certified-operators` for instance `openshift-operators`
+* `redhat-operators` for instance `openshift-operators-redhat`
+
+This parameter configures the default value for the optional parameter `source` of the component library function `registerSubscription`.
 
-[source,yaml]
-----
-namespace: example-namespace
-----
+The component defaults to `certified-operators` for instance `openshift-operators`.
+This source provides community-maintained operators which are certified by RedHat.
+Alternatively, you can use `community-operators` for other community-maintained operators.

docs/modules/ROOT/partials/nav.adoc

@@ -1,2 +1,8 @@
 * xref:index.adoc[Home]
+
+.How-tos
+* xref:how-tos/getting-started.adoc[Getting started]
+
+.Reference
+* xref:references/component-library.adoc[Component library]
 * xref:references/parameters.adoc[Parameters]