From 7f95f775825babf928d2eb38f1324198f8c3bc30 Mon Sep 17 00:00:00 2001 From: Mary Frances Hull Date: Fri, 7 Jul 2023 12:51:15 -0700 Subject: [PATCH 1/2] initial changes to addon-package docs --- .../top-level-operator/addon-package.md | 55 ++++++++++++++----- 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/content/en/docs/creating-addons/top-level-operator/addon-package.md b/content/en/docs/creating-addons/top-level-operator/addon-package.md index 638eb06a..6c0d0784 100644 --- a/content/en/docs/creating-addons/top-level-operator/addon-package.md +++ b/content/en/docs/creating-addons/top-level-operator/addon-package.md @@ -5,12 +5,14 @@ linkTitle: Plug and Play Addon ## Package -For each addon that has `packageOperator` defined in its `spec`, a -ClusterObjectTemplate[https://package-operator.run/docs/getting_started/api-reference/#clusterobjecttemplate]. -The average user does not need to interact with the `ClusterObjectTemplate`; they will interact with the resultant -ClusterPackage[https://package-operator.run/docs/getting_started/api-reference/#clusterpackage] that is created. +Each addon that includes a `packageOperator` defined in its `spec`, will have a corresponding +[ClusterObjectTemplate](https://package-operator.run/docs/getting_started/api-reference/#clusterobjecttemplate). +However, regular users typically do not need to directly interact with the `ClusterObjectTemplate`. +Instead, they can interact with the resulting +[ClusterPackage](https://package-operator.run/docs/getting_started/api-reference/#clusterpackage) +manifest that is generated from it. -The `ClusterPackage` manifest will look like this: +Example `ClusterPackage` manifest: ```shell apiVersion: package-operator.run/v1alpha1 @@ -32,15 +34,38 @@ spec: targetNamespace: pko-test-ns-00-req-apy-dsy-pdy ``` -The `deadMansSnitchUrl` and the `pagerDutyKey` come from the `configMap`s with the default names in the default -locations -documented in -the [addons deadMansSnitch](https://mt-sre.github.io/docs/creating-addons/monitoring/deadmanssnitch_integration/) +The `deadMansSnitchUrl` and the `pagerDutyKey` are obtained +from the ConfigMaps with their default names and locations, +as documented in the +[addons deadMansSnitch](https://mt-sre.github.io/docs/creating-addons/monitoring/deadmanssnitch_integration/) and -the [addons pagerDuty documentation](https://mt-sre.github.io/docs/creating-addons/monitoring/pagerduty_integration/) -respectively. *To have these values inject you must maintain the default naming scheme and location of these configMaps* -. +the [addons pagerDuty](https://mt-sre.github.io/docs/creating-addons/monitoring/pagerduty_integration/) documentation. -All the values in `.spec.config.addonsv1` can be injected into the objects contained in your packageImage. See the -[package operator documentation](https://package-operator.run/docs/guides/packaging-an-application/#go-templates) to see -how to do this. +**IMPORTANT:** To successfully inject the `deadMansSnitchUrl` and `pagerDutyKey` values, +you must keep the default naming scheme and location of the corresponding ConfigMaps. + +Additionally, all the values present in `.spec.config.addonsv1` + can be injected into the objects within your packageImage. + See the +[package operator](https://package-operator.run/docs/guides/packaging-an-application/#go-templates) +documentation for more information. + +## Tenants Onboarding Steps + +You can generate the packageImage yourself using the +[package operator](https://package-operator.run/docs/guides/packaging-an-application/#build--validate) documentation. +However, we recommend you use the Managed Tenants Bundles (MTB) facilities. + +The following steps are an example of generating the packageImage for the reference-addon package using the MTB flow: + +1. In the MTB repository, create a `package` directory and add the `manifests.yaml` inside the `package` directory. +See the following + [merge request](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/tree/main/addons/reference-addon/package) + for an example. + +2. The MTB CI creates the packageImage and the Operator Lifecycle Manager (OLM) Index Image as part of the team's + [addon folder](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/tree/main/addons/reference-addon). + +3. The MTB CI creates a merge request to the +[managed-tenants repository](https://gitlab.cee.redhat.com/service/managed-tenants/-/blob/main/addons/reference-addon/addonimagesets/stage/reference-addon.v0.10.1.yaml#L24) +and adds a new AddonImageSet with the PackageImage and OLM Index images. From 474c5bb02223bc657eebd8f06735e9fd15151e7f Mon Sep 17 00:00:00 2001 From: Mary Frances Hull Date: Tue, 11 Jul 2023 10:57:02 -0700 Subject: [PATCH 2/2] improve formatting and flow of doc --- .../top-level-operator/addon-package.md | 39 ++++++++++--------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/content/en/docs/creating-addons/top-level-operator/addon-package.md b/content/en/docs/creating-addons/top-level-operator/addon-package.md index 6c0d0784..d2dc5a23 100644 --- a/content/en/docs/creating-addons/top-level-operator/addon-package.md +++ b/content/en/docs/creating-addons/top-level-operator/addon-package.md @@ -3,16 +3,21 @@ title: Plug and Play Addon linkTitle: Plug and Play Addon --- -## Package +## Package Operator -Each addon that includes a `packageOperator` defined in its `spec`, will have a corresponding +Package Operator is a Kubernetes Operator for packaging and managing a collection of arbitrary Kubernetes objects. + +Each addon with a `packageOperator` defined in its `spec` will have a corresponding [ClusterObjectTemplate](https://package-operator.run/docs/getting_started/api-reference/#clusterobjecttemplate). -However, regular users typically do not need to directly interact with the `ClusterObjectTemplate`. -Instead, they can interact with the resulting +The ClusterObjectTemplate is an API defined in Package +Operator, enabling users to create an object by templating a + manifest and injecting values retrieved from other arbitrary source objects. +However, regular users typically do not need to interact with the `ClusterObjectTemplate`. +Instead, they can interact with the generated [ClusterPackage](https://package-operator.run/docs/getting_started/api-reference/#clusterpackage) -manifest that is generated from it. +manifest. -Example `ClusterPackage` manifest: +**Example of a `ClusterPackage` manifest:** ```shell apiVersion: package-operator.run/v1alpha1 @@ -34,17 +39,15 @@ spec: targetNamespace: pko-test-ns-00-req-apy-dsy-pdy ``` -The `deadMansSnitchUrl` and the `pagerDutyKey` are obtained -from the ConfigMaps with their default names and locations, -as documented in the -[addons deadMansSnitch](https://mt-sre.github.io/docs/creating-addons/monitoring/deadmanssnitch_integration/) -and -the [addons pagerDuty](https://mt-sre.github.io/docs/creating-addons/monitoring/pagerduty_integration/) documentation. - -**IMPORTANT:** To successfully inject the `deadMansSnitchUrl` and `pagerDutyKey` values, +* The `deadMansSnitchUrl` and `pagerDutyKey` are obtained +from the ConfigMaps using their default names and locations. +**IMPORTANT:** To successfully inject the `deadMansSnitchUrl` and `pagerDutyKey` values into the `ClusterPackage` manifest, you must keep the default naming scheme and location of the corresponding ConfigMaps. +See the [addons deadMansSnitch](https://mt-sre.github.io/docs/creating-addons/monitoring/deadmanssnitch_integration/) +and [addons pagerDuty](https://mt-sre.github.io/docs/creating-addons/monitoring/pagerduty_integration/) +documentation for more information. -Additionally, all the values present in `.spec.config.addonsv1` +* Additionally, all the values present in `.spec.config.addonsv1` can be injected into the objects within your packageImage. See the [package operator](https://package-operator.run/docs/guides/packaging-an-application/#go-templates) @@ -52,9 +55,9 @@ documentation for more information. ## Tenants Onboarding Steps -You can generate the packageImage yourself using the -[package operator](https://package-operator.run/docs/guides/packaging-an-application/#build--validate) documentation. -However, we recommend you use the Managed Tenants Bundles (MTB) facilities. +Although you can generate the packageImage yourself using the +[package operator](https://package-operator.run/docs/guides/packaging-an-application/#build--validate) documentation, +we recommend you use the Managed Tenants Bundles (MTB) facilities. The following steps are an example of generating the packageImage for the reference-addon package using the MTB flow: