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..48f7ec0 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 should not 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]