From 23accd643611ccabf6bba11fbbdd32151ce3acb3 Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Wed, 28 Jul 2021 15:15:29 +0200 Subject: [PATCH 01/10] Implement namespace creation for instances Restrict supported instances to 'openshift-operators' and 'openshift-operators-redhat'. --- class/defaults.yml | 3 ++- component/main.jsonnet | 20 ++++++++++++++++++-- lib/openshift4-operators.libsonnet | 21 ++++++++++++++++++++- 3 files changed, 40 insertions(+), 4 deletions(-) diff --git a/class/defaults.yml b/class/defaults.yml index 26d307d..69e6ca5 100644 --- a/class/defaults.yml +++ b/class/defaults.yml @@ -1,4 +1,5 @@ parameters: openshift4_operators: =_metadata: {} - namespace: syn-openshift4-operators + multi_instance: true + namespace: ${_instance} diff --git a/component/main.jsonnet b/component/main.jsonnet index 544c599..b461695 100644 --- a/component/main.jsonnet +++ b/component/main.jsonnet @@ -1,10 +1,26 @@ // 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', + }, + }, + }, } diff --git a/lib/openshift4-operators.libsonnet b/lib/openshift4-operators.libsonnet index 810854b..281fdbd 100644 --- a/lib/openshift4-operators.libsonnet +++ b/lib/openshift4-operators.libsonnet @@ -5,6 +5,25 @@ local kap = import 'lib/kapitan.libjsonnet'; local kube = import 'lib/kube.libjsonnet'; -// Export library functions here +local inv = kap.inventory(); + +local validateInstance(instance, checkTargets=false, checkSource='') = + local supported_instances = std.set([ + 'openshift-operators', + 'openshift-operators-redhat', + ]); + + assert + std.setMember(instance, supported_instances) : + "\n Invalid instance '%s' for component openshift4-operators." % [ + instance, + ] + + '\n Supported instances are %s' % [ + supported_instances, + ]; + + instance; + { + validateInstance: validateInstance, } From f555ea30e154790f5d76cff6fe4de1d0de4413e5 Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Wed, 28 Jul 2021 16:39:10 +0200 Subject: [PATCH 02/10] Create OperatorGroups for instances Create cluster-scoped OperatorGroup in instance namespace. --- component/main.jsonnet | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/component/main.jsonnet b/component/main.jsonnet index b461695..e0c42b2 100644 --- a/component/main.jsonnet +++ b/component/main.jsonnet @@ -9,7 +9,7 @@ local params = inv.parameters.openshift4_operators; local namespace = operatorlib.validateInstance(params.namespace); { - [namespace]: + [namespace]: [ kube.Namespace(namespace) { metadata+: { annotations+: { @@ -23,4 +23,11 @@ local namespace = operatorlib.validateInstance(params.namespace); }, }, }, + // Create cluster-scoped OperatorGroup + kube._Object('operators.coreos.com/v1', 'OperatorGroup', namespace) { + metadata+: { + namespace: namespace, + }, + }, + ], } From 1bf21fe54b5df97aa9a0c4acfc64b1b094150329 Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Wed, 28 Jul 2021 15:55:55 +0200 Subject: [PATCH 03/10] Implement library function to create subscription objects Reuse and extend instance verification function to produce an error if a user tries to create a subscription for an instance (== namespace) which isn't managed by the component. --- lib/openshift4-operators.libsonnet | 40 ++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/lib/openshift4-operators.libsonnet b/lib/openshift4-operators.libsonnet index 281fdbd..642144f 100644 --- a/lib/openshift4-operators.libsonnet +++ b/lib/openshift4-operators.libsonnet @@ -22,8 +22,48 @@ local validateInstance(instance, checkTargets=false, checkSource='') = supported_instances, ]; + local appentry = 'openshift4-operators as %s' % [ instance ]; + assert + !checkTargets || std.member(inv.applications, appentry) : + "\n Unknown openshift4-operators instance '%s' for %s." % [ + instance, + checkSource, + ] + + "\n Did you forget to configure application '%s'?" % [ + appentry, + ]; + instance; + +local registerSubscription = + function( + instance, + name, + channel, + source='redhat-operators', + sourceNamespace='openshift-marketplace', + installPlanApproval='Automatic' + ) + local _instance = validateInstance( + instance, + checkTargets=true, + checkSource='subscription %s' % [ name ] + ); + kube._Object('operators.coreos.com/v1alpha1', 'Subscription', name) { + metadata+: { + namespace: _instance, + }, + spec: { + channel: channel, + installPlanApproval: installPlanApproval, + source: source, + sourceNamespace: sourceNamespace, + name: name, + }, + }; + { + registerSubscription: registerSubscription, validateInstance: validateInstance, } From 1ccf98f5a030186a0105516ac5d810a0634e3f6b Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Wed, 28 Jul 2021 16:38:35 +0200 Subject: [PATCH 04/10] Update documentation * Update index.adoc * Add getting started guide * Document parameters --- .../ROOT/pages/how-tos/getting-started.adoc | 120 ++++++++++++++++++ docs/modules/ROOT/pages/index.adoc | 8 +- .../ROOT/pages/references/parameters.adoc | 14 +- docs/modules/ROOT/partials/nav.adoc | 1 + 4 files changed, 131 insertions(+), 12 deletions(-) create mode 100644 docs/modules/ROOT/pages/how-tos/getting-started.adoc diff --git a/docs/modules/ROOT/pages/how-tos/getting-started.adoc b/docs/modules/ROOT/pages/how-tos/getting-started.adoc new file mode 100644 index 0000000..10c35ea --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/getting-started.adoc @@ -0,0 +1,120 @@ += 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.registerSubscription( + 'openshift-operators', <1> + 'grafana-operator', <2> + 'alpha', <3> + source='community-operators', <4> + installPlanApproval='Automatic', <5> + sourceNamespace='openshift-marketplace', <6> + ) +} +---- +<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 subscription +<3> The update channel for the subscription +<4> The `CatalogSource` for the subscription. +For community operators, set this to `community-operators`. +For RedHat operators, this parameter can be omitted, as it defaults to `redhat-operators`. +<5> Whether installation and upgrades happen automatically. +In most cases, you don't have to specify this parameter. +If the parameter is omitted, it defaults to `Automatic`. +<6> The namespace in which to look for the `CatalogSource`. +In most cases, you don't have to specify this parameter. +If the parameter is omitted, it defaults to `openshift-marketplace`. + +. 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: grafana-operator + name: grafana-operator + namespace: openshift-operators +spec: + channel: alpha + installPlanApproval: Automatic + name: grafana-operator + source: community-operators + sourceNamespace: openshift-marketplace +---- ++ +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`. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 8d22085..c98898a 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/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. diff --git a/docs/modules/ROOT/pages/references/parameters.adoc b/docs/modules/ROOT/pages/references/parameters.adoc index 6479d14..c3c2a30 100644 --- a/docs/modules/ROOT/pages/references/parameters.adoc +++ b/docs/modules/ROOT/pages/references/parameters.adoc @@ -6,14 +6,8 @@ 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. - - -== Example - -[source,yaml] ----- -namespace: example-namespace ----- +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. diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index 08f9283..b66faf5 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -1,2 +1,3 @@ * xref:index.adoc[Home] +* xref:how-tos/getting-started.adoc[Getting started] * xref:references/parameters.adoc[Parameters] From 2263cd661099b87f90453e3851a67ffed26bc01b Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Wed, 28 Jul 2021 16:58:26 +0200 Subject: [PATCH 05/10] Make subscription function default params configurable Allow users to override default values for optional parameters of `registerSubscription` through the hierarchy. The component provides sensible defaults for both supported instances. --- class/defaults.yml | 8 ++++++ .../ROOT/pages/how-tos/getting-started.adoc | 21 +++++---------- .../ROOT/pages/references/parameters.adoc | 27 +++++++++++++++++++ lib/openshift4-operators.libsonnet | 12 ++++++--- 4 files changed, 50 insertions(+), 18 deletions(-) diff --git a/class/defaults.yml b/class/defaults.yml index 69e6ca5..5566d6e 100644 --- a/class/defaults.yml +++ b/class/defaults.yml @@ -3,3 +3,11 @@ parameters: =_metadata: {} multi_instance: true namespace: ${_instance} + defaultInstallPlanApproval: Automatic + defaultSourceNamespace: openshift-marketplace + + openshift_operators: + defaultSource: community-operators + + openshift_operators_redhat: + defaultSource: redhat-operators diff --git a/docs/modules/ROOT/pages/how-tos/getting-started.adoc b/docs/modules/ROOT/pages/how-tos/getting-started.adoc index 10c35ea..3e45595 100644 --- a/docs/modules/ROOT/pages/how-tos/getting-started.adoc +++ b/docs/modules/ROOT/pages/how-tos/getting-started.adoc @@ -70,9 +70,6 @@ local operatorlib = import 'lib/openshift4-operators.libsonnet'; 'openshift-operators', <1> 'grafana-operator', <2> 'alpha', <3> - source='community-operators', <4> - installPlanApproval='Automatic', <5> - sourceNamespace='openshift-marketplace', <6> ) } ---- @@ -80,15 +77,6 @@ local operatorlib = import 'lib/openshift4-operators.libsonnet'; Use the same value as you've selected for `${INSTANCE}` in the 3rd step. <2> The name of the subscription <3> The update channel for the subscription -<4> The `CatalogSource` for the subscription. -For community operators, set this to `community-operators`. -For RedHat operators, this parameter can be omitted, as it defaults to `redhat-operators`. -<5> Whether installation and upgrades happen automatically. -In most cases, you don't have to specify this parameter. -If the parameter is omitted, it defaults to `Automatic`. -<6> The namespace in which to look for the `CatalogSource`. -In most cases, you don't have to specify this parameter. -If the parameter is omitted, it defaults to `openshift-marketplace`. . Compile the catalog locally to check your changes + @@ -111,10 +99,13 @@ metadata: namespace: openshift-operators spec: channel: alpha - installPlanApproval: Automatic + installPlanApproval: Automatic <1> name: grafana-operator - source: community-operators - sourceNamespace: openshift-marketplace + source: community-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`. diff --git a/docs/modules/ROOT/pages/references/parameters.adoc b/docs/modules/ROOT/pages/references/parameters.adoc index c3c2a30..a553a70 100644 --- a/docs/modules/ROOT/pages/references/parameters.adoc +++ b/docs/modules/ROOT/pages/references/parameters.adoc @@ -11,3 +11,30 @@ default:: `${_instance}` 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` + +[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:: ++ +* `community-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`. diff --git a/lib/openshift4-operators.libsonnet b/lib/openshift4-operators.libsonnet index 642144f..43c6c98 100644 --- a/lib/openshift4-operators.libsonnet +++ b/lib/openshift4-operators.libsonnet @@ -2,11 +2,17 @@ * \file Library with public methods provided by component openshift4-operators. */ +local com = import 'lib/commodore.libjsonnet'; local kap = import 'lib/kapitan.libjsonnet'; local kube = import 'lib/kube.libjsonnet'; local inv = kap.inventory(); +local instanceParams(instance) = + local ikey = std.strReplace(instance, '-', '_'); + inv.parameters.openshift4_operators + + com.getValueOrDefault(inv.parameters, ikey, {}); + local validateInstance(instance, checkTargets=false, checkSource='') = local supported_instances = std.set([ 'openshift-operators', @@ -41,9 +47,9 @@ local registerSubscription = instance, name, channel, - source='redhat-operators', - sourceNamespace='openshift-marketplace', - installPlanApproval='Automatic' + source=instanceParams(instance).defaultSource, + sourceNamespace=instanceParams(instance).defaultSourceNamespace, + installPlanApproval=instanceParams(instance).defaultInstallPlanApproval ) local _instance = validateInstance( instance, From 5c70d48e0888a2cee3942acec3ba21171de01cae Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Wed, 28 Jul 2021 17:13:39 +0200 Subject: [PATCH 06/10] Provide additional library function for namespaced subscription Also rename `registerSubscription` to `globalSubscription`. --- lib/openshift4-operators.libsonnet | 43 +++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/lib/openshift4-operators.libsonnet b/lib/openshift4-operators.libsonnet index 43c6c98..7716fe3 100644 --- a/lib/openshift4-operators.libsonnet +++ b/lib/openshift4-operators.libsonnet @@ -8,10 +8,10 @@ local kube = import 'lib/kube.libjsonnet'; local inv = kap.inventory(); +local params = inv.parameters.openshift4_operators; local instanceParams(instance) = local ikey = std.strReplace(instance, '-', '_'); - inv.parameters.openshift4_operators + - com.getValueOrDefault(inv.parameters, ikey, {}); + params + com.getValueOrDefault(inv.parameters, ikey, {}); local validateInstance(instance, checkTargets=false, checkSource='') = local supported_instances = std.set([ @@ -42,7 +42,15 @@ local validateInstance(instance, checkTargets=false, checkSource='') = instance; -local registerSubscription = +local Subscription(name) = + kube._Object('operators.coreos.com/v1alpha1', 'Subscription', name) { + spec: { + name: name, + }, + }; + + +local globalSubscription = function( instance, name, @@ -56,20 +64,41 @@ local registerSubscription = checkTargets=true, checkSource='subscription %s' % [ name ] ); - kube._Object('operators.coreos.com/v1alpha1', 'Subscription', name) { + Subscription(name) { metadata+: { namespace: _instance, }, - spec: { + spec+: { + channel: channel, + installPlanApproval: installPlanApproval, + source: source, + sourceNamespace: sourceNamespace, + }, + }; + +local namespacedSubscription = + function( + namespace, + name, + channel, + source, + sourceNamespace=params.defaultSourceNamespace, + installPlanApproval=params.defaultInstallPlanApproval + ) + Subscription(name) { + metadata+: { + namespace: namespace, + }, + spec+: { channel: channel, installPlanApproval: installPlanApproval, source: source, sourceNamespace: sourceNamespace, - name: name, }, }; { - registerSubscription: registerSubscription, + globalSubscription: globalSubscription, + namespacedSubscription: namespacedSubscription, validateInstance: validateInstance, } From 77c869ddd5011161854010d9ca76335d6c26ba86 Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Wed, 28 Jul 2021 17:22:06 +0200 Subject: [PATCH 07/10] Add library function to create OperatorGroup objects --- component/main.jsonnet | 2 +- lib/openshift4-operators.libsonnet | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/component/main.jsonnet b/component/main.jsonnet index e0c42b2..e1061de 100644 --- a/component/main.jsonnet +++ b/component/main.jsonnet @@ -24,7 +24,7 @@ local namespace = operatorlib.validateInstance(params.namespace); }, }, // Create cluster-scoped OperatorGroup - kube._Object('operators.coreos.com/v1', 'OperatorGroup', namespace) { + operatorlib.OperatorGroup(namespace) { metadata+: { namespace: namespace, }, diff --git a/lib/openshift4-operators.libsonnet b/lib/openshift4-operators.libsonnet index 7716fe3..382e6d8 100644 --- a/lib/openshift4-operators.libsonnet +++ b/lib/openshift4-operators.libsonnet @@ -13,6 +13,8 @@ local instanceParams(instance) = local ikey = std.strReplace(instance, '-', '_'); params + com.getValueOrDefault(inv.parameters, ikey, {}); +local apigroup = 'operators.coreos.com'; + local validateInstance(instance, checkTargets=false, checkSource='') = local supported_instances = std.set([ 'openshift-operators', @@ -43,12 +45,14 @@ local validateInstance(instance, checkTargets=false, checkSource='') = local Subscription(name) = - kube._Object('operators.coreos.com/v1alpha1', 'Subscription', name) { + kube._Object(apigroup + '/v1alpha1', 'Subscription', name) { spec: { name: name, }, }; +local OperatorGroup(name) = + kube._Object(apigroup + '/v1', 'OperatorGroup', name); local globalSubscription = function( @@ -100,5 +104,6 @@ local namespacedSubscription = { globalSubscription: globalSubscription, namespacedSubscription: namespacedSubscription, + OperatorGroup: OperatorGroup, validateInstance: validateInstance, } From 0c1c96c0555654dea3def5be28341828f9f3bffa Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Thu, 29 Jul 2021 09:22:04 +0200 Subject: [PATCH 08/10] Change openshift-operators default source to `certified-operators` Also change the getting started example to use elasticsearch-eck-operator-certified Co-authored-by: Megian --- class/defaults.yml | 2 +- .../ROOT/pages/how-tos/getting-started.adoc | 16 ++++++++-------- .../ROOT/pages/references/parameters.adoc | 6 +++++- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/class/defaults.yml b/class/defaults.yml index 5566d6e..4cff4a5 100644 --- a/class/defaults.yml +++ b/class/defaults.yml @@ -7,7 +7,7 @@ parameters: defaultSourceNamespace: openshift-marketplace openshift_operators: - defaultSource: community-operators + defaultSource: certified-operators openshift_operators_redhat: defaultSource: redhat-operators diff --git a/docs/modules/ROOT/pages/how-tos/getting-started.adoc b/docs/modules/ROOT/pages/how-tos/getting-started.adoc index 3e45595..34ec66a 100644 --- a/docs/modules/ROOT/pages/how-tos/getting-started.adoc +++ b/docs/modules/ROOT/pages/how-tos/getting-started.adoc @@ -68,14 +68,14 @@ local operatorlib = import 'lib/openshift4-operators.libsonnet'; { subscription: operatorlib.registerSubscription( 'openshift-operators', <1> - 'grafana-operator', <2> - 'alpha', <3> + '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 subscription +<2> The name of the operator to install <3> The update channel for the subscription . Compile the catalog locally to check your changes @@ -94,14 +94,14 @@ kind: Subscription metadata: annotations: {} labels: - name: grafana-operator - name: grafana-operator + name: elasticsearch-eck-operator-certified + name: elasticsearch-eck-operator-certified namespace: openshift-operators spec: - channel: alpha + channel: stable installPlanApproval: Automatic <1> - name: grafana-operator - source: community-operators <2> + 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`. diff --git a/docs/modules/ROOT/pages/references/parameters.adoc b/docs/modules/ROOT/pages/references/parameters.adoc index a553a70..e091a21 100644 --- a/docs/modules/ROOT/pages/references/parameters.adoc +++ b/docs/modules/ROOT/pages/references/parameters.adoc @@ -34,7 +34,11 @@ This parameter configures the default value for the optional parameter `sourceNa type:: string default:: + -* `community-operators` for instance `openshift-operators` +* `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`. + +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. From 6545d57b74df5e0aede480d390d837d064ddca26 Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Thu, 29 Jul 2021 09:48:49 +0200 Subject: [PATCH 09/10] Rename `globalSubscription` to `managedSubscription` Reduce amount of duplicated code in component lib --- .../ROOT/pages/how-tos/getting-started.adoc | 2 +- lib/openshift4-operators.libsonnet | 55 +++++++++---------- 2 files changed, 27 insertions(+), 30 deletions(-) diff --git a/docs/modules/ROOT/pages/how-tos/getting-started.adoc b/docs/modules/ROOT/pages/how-tos/getting-started.adoc index 34ec66a..4ac32be 100644 --- a/docs/modules/ROOT/pages/how-tos/getting-started.adoc +++ b/docs/modules/ROOT/pages/how-tos/getting-started.adoc @@ -66,7 +66,7 @@ fi local operatorlib = import 'lib/openshift4-operators.libsonnet'; { - subscription: operatorlib.registerSubscription( + subscription: operatorlib.managedSubscription( 'openshift-operators', <1> 'elasticsearch-eck-operator-certfied', <2> 'stable', <3> diff --git a/lib/openshift4-operators.libsonnet b/lib/openshift4-operators.libsonnet index 382e6d8..e986bca 100644 --- a/lib/openshift4-operators.libsonnet +++ b/lib/openshift4-operators.libsonnet @@ -44,7 +44,7 @@ local validateInstance(instance, checkTargets=false, checkSource='') = instance; -local Subscription(name) = +local subscription(name) = kube._Object(apigroup + '/v1alpha1', 'Subscription', name) { spec: { name: name, @@ -54,32 +54,6 @@ local Subscription(name) = local OperatorGroup(name) = kube._Object(apigroup + '/v1', 'OperatorGroup', name); -local globalSubscription = - function( - instance, - name, - channel, - source=instanceParams(instance).defaultSource, - sourceNamespace=instanceParams(instance).defaultSourceNamespace, - installPlanApproval=instanceParams(instance).defaultInstallPlanApproval - ) - local _instance = validateInstance( - instance, - checkTargets=true, - checkSource='subscription %s' % [ name ] - ); - Subscription(name) { - metadata+: { - namespace: _instance, - }, - spec+: { - channel: channel, - installPlanApproval: installPlanApproval, - source: source, - sourceNamespace: sourceNamespace, - }, - }; - local namespacedSubscription = function( namespace, @@ -89,7 +63,7 @@ local namespacedSubscription = sourceNamespace=params.defaultSourceNamespace, installPlanApproval=params.defaultInstallPlanApproval ) - Subscription(name) { + subscription(name) { metadata+: { namespace: namespace, }, @@ -101,8 +75,31 @@ local namespacedSubscription = }, }; +local managedSubscription = + function( + instance, + name, + channel, + source=instanceParams(instance).defaultSource, + sourceNamespace=instanceParams(instance).defaultSourceNamespace, + installPlanApproval=instanceParams(instance).defaultInstallPlanApproval + ) + local _instance = validateInstance( + instance, + checkTargets=true, + checkSource='subscription %s' % [ name ] + ); + namespacedSubscription( + _instance, + name, + channel, + source, + sourceNamespace, + installPlanApproval + ); + { - globalSubscription: globalSubscription, + managedSubscription: managedSubscription, namespacedSubscription: namespacedSubscription, OperatorGroup: OperatorGroup, validateInstance: validateInstance, From 74883dc82dc3daa79c43af94e7fc3cf4b9342a5a Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Thu, 29 Jul 2021 09:48:31 +0200 Subject: [PATCH 10/10] Add component library documentation * Function comments in library * Page in component documentation --- .../ROOT/pages/how-tos/getting-started.adoc | 2 + .../pages/references/component-library.adoc | 85 +++++++++++++++++++ docs/modules/ROOT/partials/nav.adoc | 5 ++ lib/openshift4-operators.libsonnet | 68 +++++++++++++++ 4 files changed, 160 insertions(+) create mode 100644 docs/modules/ROOT/pages/references/component-library.adoc diff --git a/docs/modules/ROOT/pages/how-tos/getting-started.adoc b/docs/modules/ROOT/pages/how-tos/getting-started.adoc index 4ac32be..40ba8e9 100644 --- a/docs/modules/ROOT/pages/how-tos/getting-started.adoc +++ b/docs/modules/ROOT/pages/how-tos/getting-started.adoc @@ -77,6 +77,8 @@ local operatorlib = import 'lib/openshift4-operators.libsonnet'; 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 + diff --git a/docs/modules/ROOT/pages/references/component-library.adoc b/docs/modules/ROOT/pages/references/component-library.adoc new file mode 100644 index 0000000..004b4bd --- /dev/null +++ b/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 '' for "`. +-- + +== `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..defaultSource`. +This argument can be omitted. +`sourceNamespace`:: The namespace holding the `CatalogSource`. +Defaults to `parameters..defaultSourceNamespace`. +This argument can be omitted. +`installPlanApproval`:: How to manage subscription updates. +Valid options are `Automatic` and `Manual`. +Defaults to `parameters..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..defaultSource`. +This argument can be omitted. +`sourceNamespace`:: The namespace holding the `CatalogSource`. +Defaults to `parameters..defaultSourceNamespace`. +This argument can be omitted. +`installPlanApproval`:: How to manage subscription updates. +Valid options are `Automatic` and `Manual`. +Defaults to `parameters..defaultInstallPlanApproval`. +This argument can be omitted. +-- + +Arguments `source`, `sourceNamespace` and `installPlanApproval` are optional and default to component instance parameters `defaultSource`, `defaultSourceNamespace` and `defaultInstallPlanApproval`. + diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index b66faf5..e15fd1e 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -1,3 +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] diff --git a/lib/openshift4-operators.libsonnet b/lib/openshift4-operators.libsonnet index e986bca..fc59bd7 100644 --- a/lib/openshift4-operators.libsonnet +++ b/lib/openshift4-operators.libsonnet @@ -15,6 +15,22 @@ local instanceParams(instance) = local apigroup = 'operators.coreos.com'; +/** + * \brief Validate instance + * + * This function takes an instance name and validates it against the supported + * instance names and optionally against the instances present in the cluster + * catalog. + * + * \arg instance The instance to validate + * \arg checkTargets Whether to validate the instance against configured + * component instances + * \arg checkSource Free-form string included in the error output when + * checking against configured component instances. This is included in the + * error as "Unknown instance '' for ". + * + * \returns `instance` if it validates. Throws an assertion error otherwise. + */ local validateInstance(instance, checkTargets=false, checkSource='') = local supported_instances = std.set([ 'openshift-operators', @@ -51,9 +67,39 @@ local subscription(name) = }, }; +/** + * \brief Wrapper to create `OperatorGroup` resources + * + * The result of this function can be used in the same way as resources + * created by `kube.libjsonnet`. + * + * \arg name Value for `.metadata.name` of the resource + * + * \returns an `OperatorGroup` resource + */ local OperatorGroup(name) = kube._Object(apigroup + '/v1', 'OperatorGroup', name); +/** + * \brief Create a subscription object in an arbitrary namespace + * + * The result of this function can be used in the same way as resources + * created by `kube.libjsonnet`. + * + * \arg namespace The namespace in which to create the resource + * \arg name Name of the operator to install. Used as `.metadata.name` and + * `.spec.name` of the resulting `Subscription` object. + * \arg channel The channel for the subscription. + * \arg source The source (`CatalogSource`) for the operator. Defaults to + * `parameters..defaultSource`. + * \arg sourceNamespace The namespace holding the `CatalogSource`. Defaults to + * `parameters..defaultSourceNamespace`. + * \arg installPlanApproval How to manage subscription updates. Valid options + * are `Automatic` and `Manual`. Defaults to + * `parameters..defaultInstallPlanApproval`. + * + * \returns a preconfigured `Subscription` resource + */ local namespacedSubscription = function( namespace, @@ -75,6 +121,28 @@ local namespacedSubscription = }, }; +/** + * \brief Create a cluster-scoped subscription object 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`. + * + * \arg instance Name of the component instance in which to create the + * subscription + * \arg name Name of the operator to install. Used as `.metadata.name` and + * `.spec.name` of the resulting `Subscription` object. + * \arg channel The channel for the subscription. + * \arg source The source (`CatalogSource`) for the operator. Defaults to + * `parameters..defaultSource`. + * \arg sourceNamespace The namespace holding the `CatalogSource`. Defaults to + * `parameters..defaultSourceNamespace`. + * \arg installPlanApproval How to manage subscription updates. Valid options + * are `Automatic` and `Manual`. Defaults to + * `parameters..defaultInstallPlanApproval`. + * + * \returns a preconfigured `Subscription` resource + */ local managedSubscription = function( instance,