From 98ded1853a5c2808c5aef7dac78b6f8ec9c5d961 Mon Sep 17 00:00:00 2001 From: gathomas Date: Tue, 30 May 2023 20:51:41 +0200 Subject: [PATCH 1/7] move documentation from managed tenants --- .markdownlint.yaml | 2 +- .../creating-addons/configure-vault-access.md | 204 ++++++++++++ .../managed-tenants-repository.md | 86 +++++ .../en/docs/creating-addons/merge-requests.md | 51 +++ .../creating-addons/testing/validation.md | 127 ++++++++ .../top-level-operator/OCM/_index.md | 7 + .../OCM/addon-external-resources.md | 50 +++ .../OCM/addon-parameters.md | 294 ++++++++++++++++++ .../OCM/addon-requirements.md | 230 ++++++++++++++ .../OCM/addon-suboperators.md | 30 ++ .../top-level-operator/addon-metadata-file.md | 13 + .../top-level-operator/addon-package.md | 53 ++++ .../top-level-operator/create-an-addon.md | 62 ++++ .../imageset-specification.md | 8 + .../migrate-to-imagesets.md | 25 ++ .../top-level-operator/subscription-config.md | 57 ++++ .../en/docs/internal-documentation/cicd.md | 9 + .../release-process/promote-to-production.md | 31 ++ 18 files changed, 1338 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/creating-addons/configure-vault-access.md create mode 100644 content/en/docs/creating-addons/merge-requests.md create mode 100644 content/en/docs/creating-addons/testing/validation.md create mode 100644 content/en/docs/creating-addons/top-level-operator/OCM/_index.md create mode 100644 content/en/docs/creating-addons/top-level-operator/OCM/addon-external-resources.md create mode 100644 content/en/docs/creating-addons/top-level-operator/OCM/addon-parameters.md create mode 100644 content/en/docs/creating-addons/top-level-operator/OCM/addon-requirements.md create mode 100644 content/en/docs/creating-addons/top-level-operator/OCM/addon-suboperators.md create mode 100644 content/en/docs/creating-addons/top-level-operator/addon-metadata-file.md create mode 100644 content/en/docs/creating-addons/top-level-operator/addon-package.md create mode 100644 content/en/docs/creating-addons/top-level-operator/create-an-addon.md create mode 100644 content/en/docs/creating-addons/top-level-operator/imageset-specification.md create mode 100644 content/en/docs/creating-addons/top-level-operator/migrate-to-imagesets.md create mode 100644 content/en/docs/creating-addons/top-level-operator/subscription-config.md create mode 100644 content/en/docs/internal-documentation/cicd.md create mode 100644 content/en/docs/release-process/promote-to-production.md diff --git a/.markdownlint.yaml b/.markdownlint.yaml index c0edd89a..6fd5fd74 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,6 +1,6 @@ default: true MD013: - line_length: 90 + line_length: 120 code_blocks: false # MD033/no-inline-html - Allow inline HTML MD033: false diff --git a/content/en/docs/creating-addons/configure-vault-access.md b/content/en/docs/creating-addons/configure-vault-access.md new file mode 100644 index 00000000..905c989d --- /dev/null +++ b/content/en/docs/creating-addons/configure-vault-access.md @@ -0,0 +1,204 @@ +--- +title: Configure Vault Access +linkTitle: Vault Access +--- + +## Background + +Vault access is required by teams at paths like `mt-sre/tenants//secrets/*` to store their secrets +which are referenced by their `addon.yaml`s. +For this, vault access needs to be set up for that team. + +Vault auth configuration is managed +via [app-interface](https://gitlab.cee.redhat.com/gathomas/app-interface#manage-vault-configurations-via-app-interface). + +Multiple components have to be set up to provide vault access to the team. We will define the vault policy, oidc +permission, +role and then assign the role to the members of the team. + +### Vault Policy + +First we want to create a vault policy that allows access to the path that the team will store their secrets, i.e. +`mt-sre/tenants//secrets/*`. A vault policy is essentially a path with associated permissions (verbs). +See the [HashiCorp Vault Policy documentation](https://developer.hashicorp.com/vault/docs/concepts/policies) for more +information. + +To create the policy we follow +Create a file under `data/services/vault.devshift.net/config/prod/policies` with the +name `mt-sre-tenants--secrets-policy.yaml` +with the following structure: + +```yaml +--- +$schema: /vault-config/policy-1.yml + +labels: + service: vault.devshift.net + +name: "mt-sre-tenants--secrets-policy" +instance: + $ref: /services/vault.devshift.net/config/instances/devshift-net.yml +rules: | + path "mt-sre/metadata" { + capabilities = ["list"] + } + path "mt-sre/metadata/tenants" { + capabilities = ["list"] + } + path "mt-sre/metadata/tenants/" { + capabilities = ["list"] + } + path "mt-sre/data/tenants//secrets/*" { + capabilities = ["list", "create", "read", "update", "delete"] + } + path "mt-sre/metadata/tenants//secrets/*" { + capabilities = ["list", "create", "read", "update", "delete"] + } + +``` + +Take whatever subset of the rules above are needed. +For example, under `data/services/vault.devshift.net/config/prod/policies/mt-sre-tenants-odf-secrets-policy.yml`, the +content is: + +```yaml +--- +$schema: /vault-config/policy-1.yml + +labels: + service: vault.devshift.net + +name: "mt-sre-tenants-odf-secrets-policy" +instance: + $ref: /services/vault.devshift.net/config/instances/devshift-net.yml +rules: | + path "mt-sre/metadata/tenants/odf/secrets/*" { + capabilities = ["create", "read", "update", "delete", "list"] + } + path "mt-sre/data/tenants/odf/secrets/*" { + capabilities = ["create", "read", "update", "delete", "list"] + } +``` + +See +the [app-interface documentation about creating policies](https://gitlab.cee.redhat.com/service/app-interface#manage-vault-policies-vault-configpolicy-1yml) +for more information. + +### OIDC Permission + +Next we will create an OIDC Permission to wrap the vault policy we just created. + +Create a file under `data/dependencies/vault/permissions/oidc/prod` with the +name `mt-sre-tenants--oidc-permission.yaml` +with the following structure: + +```yaml +--- +$schema: /access/oidc-permission-1.yml + +labels: + service: vault.devshift.net + +name: mt-sre-tenants--oidc-permission +description: mt-sre-tenants--oidc-permission vault devshift oidc permission + +instance: + $ref: /services/vault.devshift.net/config/prod/devshift-net.yml + +service: vault +vault_policies: + - $ref: /services/vault.devshift.net/config/prod/policies/mt-sre-tenants--secrets-policy.yml +``` + +For example, under `data/dependencies/vault/permissions/oidc/prod/github-app-sre-vault-odf-team.yaml` +(the difference in file name is for legacy reasons), the content is: + +```yaml +--- +$schema: /access/oidc-permission-1.yml + +labels: + service: vault.devshift.net + +name: github-app-sre-vault-odf-team-oidc-vault +description: github-app-sre-vault-odf-team vault devshift oidc permission + +instance: + $ref: /services/vault.devshift.net/config/prod/devshift-net.yml + +service: vault +vault_policies: + - $ref: /services/vault.devshift.net/config/prod/policies/mt-sre-tenants-odf-secrets-policy.yml +``` + +### Role + +We now have to include this permission in a role that we can assign to the team members: *Note* this is an app-interface +role, not to be confused with a vault role. + +Under `data/teams//roles` create a file called `app-sre-vault-.yml` with the following contents: + +```yaml +--- +$schema: /access/role-1.yml + +labels: { } +name: app-sre-vault-odf + +permissions: [ ] + +oidc_permissions: + - $ref: /dependencies/vault/permissions/oidc/prod/mt-sre-tenants--oidc-permission.yaml +``` + +For example, the contents of `data/teams/odf-managed-service/roles/app-sre-vault-odf.yml` is: + +```yaml +--- +$schema: /access/role-1.yml + +labels: { } +name: app-sre-vault-odf + +permissions: [ ] + +oidc_permissions: + - $ref: /dependencies/vault/permissions/oidc/prod/github-app-sre-vault-odf-team.yml +``` + +### Adding Users + +Now the users just need to be added with the role we just created. +Under `data/teams//users` create files called `.yml` with the following contents: + +```yaml +--- +$schema: /access/user-1.yml + +labels: { } + +name: +org_username: +github_username: +quay_username: + +roles: ## "roles" link your user to a certain role. Role in this case would point to the app-sre/your-team on Github. + - $ref: /teams//roles/app-sre-vault-.yml ## path to the roles file you created in the last step +``` + +For example, the contents of `data/teams/odf-managed-service/users/dbindra.yml` is: + +```yaml +--- +$schema: /access/user-1.yml + +labels: { } + +name: Dhruv Bindra +org_username: dbindra +github_username: bindrad +quay_username: dbindra + +roles: + - $ref: /teams/odf-managed-service/roles/app-sre-vault-odf.yml +``` diff --git a/content/en/docs/creating-addons/managed-tenants-repository.md b/content/en/docs/creating-addons/managed-tenants-repository.md index 089490dc..552af2ae 100644 --- a/content/en/docs/creating-addons/managed-tenants-repository.md +++ b/content/en/docs/creating-addons/managed-tenants-repository.md @@ -11,3 +11,89 @@ be found in the . See the [create an addon](https://gitlab.cee.redhat.com/service/managed-tenants/-/blob/main/docs/tenants/create_an_addon.md) documentation page for a good starting point. + +## Structure + +The `addons` directory contains one subdirectory per Add-On that contains a `metadata` subdirectory. +The `metadata` subdirectory contains one subdirectory per environment, which contains an Add-On metadata file +for the corresponding environment. For example: + +```yaml +addons/ocs-converged +└── metadata + ├── production + │   └── addon.yaml + └── stage + └── addon.yaml +``` + +### addon imagesets + +Our tooling now supports creating imagesets for addons. Imageset of a new version of +an addon sits inside a new directory called `addonimagesets/`. CPaaS/Tenants will need to create +a merge request in in order to notify +MT-SRE of the availability of the new release. Each new addon version is a new file under the +earlier mentioned `addonimagesets/` directory. + +See the [Imageset Specification](top-level-operator/imageset-specification.md) for more details about +the imageset file. + +Example repository structure of an addon with imagesets: + +```bash +mock-operator-with-imagesets +├── addonimagesets +│   └── stage +│   ├── mock-operator.v1.0.0.yml +│   ├── mock-operator.v1.0.2.yml +└── metadata + └── stage + └── addon.yaml +``` + +The `addon.yaml` file would then reference the required imageset version +using the attribute `addonImageSetVersion`. See the +[Metadata Specification](top-level-operator/addon-metadata-file.md) for details. + +Ex: + +```yaml +id: mock-operator +name: Mock Operator +description: This is a mock operator. +icon: mock +label: "api.openshift.com/addon-mock-operator" +enabled: true +addonOwner: Mock +quayRepo: quay.io/osd-addons/mock-operator +installMode: OwnNamespace +targetNamespace: mock-operator +namespaces: + - mock-operator +namespaceLabels: + monitoring-key: mock +namespaceAnnotations: {} +ocmQuotaName: addon-mock-operator +ocmQuotaCost: 1 +testHarness: quay.io/mock-operator/mock-operator-test-harness +operatorName: mock-operator +hasExternalResources: true +defaultChannel: alpha +bundleParameters: + useClusterStorage: "true" +addonImageSetVersion: 1.0.0 +``` + +#### metadata + +The `metadata` directory contains exclusively sub-directories, one per +environment. + +The environment subdirectories host the corresponding `addons.yaml` metadata. +See the [Metadata Specification](top-level-operator/addon-metadata-file.md) for details. + +#### bundles (deprecated) + +The `bundles` directory has been moved to the +[managed-tenants-bundles repository](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/blob/main/README.md) +. diff --git a/content/en/docs/creating-addons/merge-requests.md b/content/en/docs/creating-addons/merge-requests.md new file mode 100644 index 00000000..3a9a5dfa --- /dev/null +++ b/content/en/docs/creating-addons/merge-requests.md @@ -0,0 +1,51 @@ +--- +title: Merge Requests +--- + +## Merge Request Review + +## Stage + +Merge Requests to stage can be self-serviced using the OWNERS file mechanism. + +## Production + +Any PR that promotes to prod will be manually reviewed to ensure that the addon +has been present in the staging environment previously, in order to ensure that +nothing goes directly to production without having had time in staging. + +## FAQ + +### Will my addon be automatically upgraded? + +For that, the new version bundle directory has to contain a +`ClusterServiceVersion` manifest with the `replaces` field pointing to the version +it will be upgraded from: + +```yaml +... +kind: ClusterServiceVersion +... +spec: + version: 1.19.0 + replaces: example-operator.v1.18.0 + ... +``` + +### Can I change metadata fields? + +By changing the metadata, the addon will be updated in the OCM API. That will +affect new installations, but no cleanup is done to the already installed +addons. + +### If my addon fails testing in prod, how will I be notified? + +Apart from the validations done here before publishing the addon, at the moment +all the real world testing in done externally to this repository, either (or +both) by using the OSD e2e framework or by assigning testing tasks to QA team. + +### Can I push to the addon catalog quay repo? + +No. The Quay.io organization is owned by the Add-Ons SRE team. All the pushes +there are automated and executed after the code is merged, which happens +after all the tests are green. diff --git a/content/en/docs/creating-addons/testing/validation.md b/content/en/docs/creating-addons/testing/validation.md new file mode 100644 index 00000000..f5888296 --- /dev/null +++ b/content/en/docs/creating-addons/testing/validation.md @@ -0,0 +1,127 @@ +--- +title: Addon Validation +linkTitle: Addon Validation +--- + +## Getting Started + +Start with creating/activating a virtual environment: + +```bash +make init +``` + +View Makefile documentation + +```bash +make help +``` + +Run test suite: + +```bash +make test +``` + +## pre-commit + +### Install on your developer machine + +This is intended for developers, and will trigger hooks every time `git commit` is run: + +```bash +pip install pre-commit +pre-commit install +``` + +### Run in virtualenv + +This is intended for CI systems, to validate PRs/MRs: + +```bash +make pre-commit +``` + +## Environment "load" Check + +Before proceeding, make sure to install the `managedtenants` CLI tool using `pip` + +```bash +pip install managedtenants-cli +``` + +The code repository for the `managedtenants` CLI can be found at + +Using the CLI, check the content of the `addons` directory for a given +environment: + +```bash +$ managedtenants --environment=stage --addons-dir addons load +Loading stage... +Loading stage OK +``` + +That minimalistic `OK` means that all the `addons` are valid for the `stage` +environment. + +## Task API + +If you want to write additional checks for the `addons` content, you can do so +using the `Task` API. Start creating a new file in the `tasks/check/` directory. + +Example: + +`tasks/check/40-demo_task.py` + +```python +from managedtenants import Task + + +class DummyCheck(Task): + def run(self): + assert self.addon.metadata['id'] is not None +``` + +- The `self.addon` object abstracts the entire content of each `addon`. +- The `Task` base class is the flag for the runner to execute this class. +- The `run` method is the entrypoint. Feel free to create any number of + helper methods in the same class. + +To run the check against all the addons: + +```bash +$ managedtenants --environment=stage --addons-dir addons --dry-run run tasks/check/40-demo_task.py +Loading stage... +Loading stage OK +== TASKS ===================================== +tasks/check/40-demo_task.py:DummyCheck:codeready-workspaces-operator:stage... +tasks/check/40-demo_task.py:DummyCheck:codeready-workspaces-operator:stage OK +tasks/check/40-demo_task.py:DummyCheck:codeready-workspaces-operator-qe:stage... +tasks/check/40-demo_task.py:DummyCheck:codeready-workspaces-operator-qe:stage OK +tasks/check/40-demo_task.py:DummyCheck:dba-operator:stage... +tasks/check/40-demo_task.py:DummyCheck:dba-operator:stage OK +tasks/check/40-demo_task.py:DummyCheck:integreatly-operator:stage... +tasks/check/40-demo_task.py:DummyCheck:integreatly-operator:stage OK +tasks/check/40-demo_task.py:DummyCheck:prow-operator:stage... +tasks/check/40-demo_task.py:DummyCheck:prow-operator:stage OK +``` + +To run the check against a selected addon: + +```bash +$ managedtenants --environment=stage --addons-dir addons --dry-run run tasks/check/40-demo_task.py::integreatly-operator: +Loading stage... +Loading stage OK +== TASKS ===================================== +tasks/check/40-demo_task.py:DummyCheck:integreatly-operator:stage... +tasks/check/40-demo_task.py:DummyCheck:integreatly-operator:stage OK +``` + +All the checks included in `tasks/check/` are expected to pass on Pull +Request check. + +## Addon Metadata Operator + +There are also checks defined in the [Addon Metadata Operator Repository](https://github.com/mt-sre/addon-metadata-operator) +in the [addon-metadata-operator/pkg/validator/ directory](https://github.com/mt-sre/addon-metadata-operator/tree/master/pkg/validator). +These checks are run by in the `mtcli validate` subcommand. diff --git a/content/en/docs/creating-addons/top-level-operator/OCM/_index.md b/content/en/docs/creating-addons/top-level-operator/OCM/_index.md new file mode 100644 index 00000000..f8da539d --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/OCM/_index.md @@ -0,0 +1,7 @@ +--- +title: OCM +linkTitle: OCM +weight: 20 +description: > + Documentation of relevant OCM features. +--- diff --git a/content/en/docs/creating-addons/top-level-operator/OCM/addon-external-resources.md b/content/en/docs/creating-addons/top-level-operator/OCM/addon-external-resources.md new file mode 100644 index 00000000..1bd3c5ba --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/OCM/addon-external-resources.md @@ -0,0 +1,50 @@ +--- +title: Addon External Resources +--- + +Whenever an add-on creates a resource externally to the cluster (eg, S3, RDS Instances, etc.) The flag +`hasExternalResources` must be set to true in the addon metadata: + +```yaml +... +hasExternalResources: true +... + +``` + +## Addon Deletion + +The Addon is responsible for all resources it creates and needs to clean them up when it is removed. + +The full deletion process: + +1. Addon deletion is triggered via the OCM UI or Cluster deletion. +2. A "Deletion" ConfigMap is created in the Addons Namespace. [1] +3. **The Addon cleans up its resources.** +4. **The Addon signals it is ready to be removed by removing its ClusterServiceVersion.** +5. OCM will wait for the `csv_succeeded` metric to transition to `false`. [2] +6. OCM will remove the `Subscription`, `CatalogSource`, and `Namespace` from the cluster. +7. The deletion process is complete. + +Each Addon is responsible for implementing points 3. and 4. within one of their operator's controllers. + +**[1] Deletion ConfigMap:** + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: + namespace: + labels: + -delete: 'true' +``` + +**[2] csv_succeeded metric** +As Clusters Service and Hive is unaware of resources owned and controlled by the operator it relies on metrics to +evaluate the state of the add-on. Notably it uses `csv_succeeded{}` to determine the state, when an add-on is marked +for deletion, an absence of the `csv_succeeded{}` will allow Clusters Service and Hive remove any remaining SyncSets +associated with the add-on and clean the `Cluster Deployment` of the add-on + +> **_NOTE:_** A label will be added to add-on namespace `{{ADDON.metadata['label']}}-delete: 'true'` on addon deletion. +> This is deprecated, add-ons should watch for existence of the "deletion ConfigMap" to trigger resource clean up. diff --git a/content/en/docs/creating-addons/top-level-operator/OCM/addon-parameters.md b/content/en/docs/creating-addons/top-level-operator/OCM/addon-parameters.md new file mode 100644 index 00000000..b88ffb1f --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/OCM/addon-parameters.md @@ -0,0 +1,294 @@ +--- +title: Addon Parameters +--- + +Parameters can be defined for an add-on using the addOnParameters field, this field takes an array of parameter objects. + +```yaml +- id: "my-param" + name: "My Param" + description: "My Param Description" + value_type: string + validation: '^myparam-[A-Za-z0-9]$' + required: false + editable: false + enabled: true + default_value: "my default" +``` + +#### Value Type + +Parameters must have a `value_type` field, and it must be a supported value type, currently supported types : + +* `string` +* `boolean` +* `number` +* `cidr` +* `resource` +* `resource_requirement` + +> **_NOTE:_** All values are ultimately stored as strings, but additional validation is handled by clusters service to +> ensure they are supported by their corresponding type e.g boolean is a boolean value, number is an integer or float +> etc.. + +#### 'resource' + +A resource type parameter is used to allow addons to set values to consume from resource quota stored in the account +manager service (AMS). +The 'id' of the parameter is the quota resource name and the 'value' is a number representing the amount the +installation of this addon will consume from the total of that resource. + +**Example:** + +```yaml + - id: "addon-my-addon" + name: "AddOn Flavour" + description: "Flavour of AddOn, small, medium or large" + value_type: resource + required: true + editable: true + enabled: true + options: + - name: "Small SKU" + value: "1" + - name: "Medium SKU" + value: "5" + - name: "Large SKU" + value: "10" + default_value: "5" +``` + +The above would require quota in AMS to exist with a resource name of `addon-my-addon`, and depending on which option +the user selects at installation +time (1, 5 or 10), that value is deducted from the total available. + +Details of quota and resources available can be found from the following endpoint: + +```bash +ocm get /api/accounts_mgmt/v1/organizations/{myorg}/quota_cost --parameter=search="quota_id LIKE 'addon%'" --parameter=fetchRelatedResources=true +``` + +#### 'resource_requirement' + +A `resource_requirement` parameter is used to introduce a set of cluster requirements as part of the parameter options. +See [Add-on Requirements](addon-requirements.md) for information on what requirements can be set. +These cluster requirements are applied as addon resources, and therefore, they will consume the quota stored in the +account manager service (AMS). +When the addon is installed the `requirements` present in the option that match the parameter value will be used +for the addon, as if they were defined directly in the addon itself as `addOnRequirements`. A `resource_requirement` +parameter +can be used with or without `addOnRequirements` being defined. If both are used, `requirements` will inherit any +requirements +set in `addOnRequirements`. However, the same requirement cannot be set in both `addOnRequirements` and `requirements`. +In this case the addon would not be able to be installed. + +Only one `resource_requirement` parameter is allowed per addon, and options with `requirements` are only allowed for +`resource_requirement` type parameters. + +**Example:** + +```yaml +- id: "addon-my-addon" + name: "AddOn Flavour and Requirements" + description: "Flavour of AddOn, small, medium or large, with requirements" + value_type: resource_requirement + required: true + editable: true + enabled: true + options: + - name: "Small SKU" + value: "1" + requirements: + - resource: 'machine_pool' + id: 'my-machine-pool-req' + data: + instance_type: 'm5.xlarge' + replicas: 2 + enabled: true + - name: "Medium SKU" + value: "5" + requirements: + - resource: 'machine_pool' + id: 'my-machine-pool-req' + data: + instance_type: 'm5.2xlarge' + replicas: 4 + enabled: true + - name: "Large SKU" + value: "10" + requirements: + - resource: 'machine_pool' + id: 'my-machine-pool-req' + data: + instance_type: 'm5.16xlarge' + replicas: 5 + enabled: true + default_value: "5" +``` + +The above would require quota in AMS to exist with a resource name of `addon-my-addon`, and depending on which option +the user selects at installation +time (1, 5 or 10), that value is deducted from the total available. + +Details of quota and resources available can be found from the following endpoint: + +```bash +ocm get /api/accounts_mgmt/v1/organizations/{myorg}/quota_cost --parameter=search="quota_id LIKE 'addon%'" --parameter=fetchRelatedResources=true +``` + +#### Required + +Parameters can be set as "required" meaning that they must have a value set in order for the add-on to be installed. + +**Note:** In the case of boolean values this does not mean they need to be true (checked in the UI), since a true or +false value can both satisfy the OCM "required" requirement. +If however you want to enforce a true value (must be checked in the UI), you can add a validation to your parameter +like the following: + +```yaml + - id: "agree-to-something" + name: "Agree to Something Important" + description: "Agree to Something Important" + value_type: boolean + validation: "^true$" + required: true + editable: false + enabled: true +``` + +#### Editable + +Parameters set `editable: false` can not be modified after it has been set, and any request to modify it from its +original +value will result in an error. Alternatively setting `editable: true` allows the value to be modified after the fact. + +**Note:** Please be cautious when using `editable: false` with `required: false`. With this configuration, it is +possible to create the addon +without setting the given parameter. Then, because the parameter cannot be modified _after it has been set_, it is still +possible +for the parameter value to be changed (set for the first time) after installation. + +#### Editable Direction + +Parameters can have `editable_direction: ["up"|"down"]` set to restrict upscale/downscale operations on options. For +example: + +```json + "parameters": { + "items": [ + { + "name": "size", + "description": "Default editable direction is unrestricted.", + "id": "size", + "value_type": "string", + "required": true, + "editable": true, + "editable_direction": "up" + "enabled": true, + "options": [ + { + "name": "0 TiB", + "value": "0" + }, + { + "name": "4 TiB", + "value": "4", + "rank": 4 + }, + { + "name": "20 TiB", + "value": "20", + "rank": 20 + } + ] + } + ] + } +``` + +Add-on installations with this configuration would be able to upscale from 4 TiB to 20 TiB, but they would not be able +to downscale from 4 TiB to 0 TiB. + +#### Validation + +Custom validations can also be added to an addon by means of the `validation` field. This field should be a regular +expression, and any values given for this parameter must match the validation criteria, any request containing a value +that doesn't will result in a validation error. Validation is also used when setting `default_value` + +#### Validation Error Message + +Should a parameter not pass the validation criteria, OCM's default behavior is to return the regular expression where +the mismatch occurred. A custom message can be returned instead by setting the `validation_err_msg` field. + +#### Default Value + +`default_value` can be set to provide a placeholder value for the parameter in the portal. Note that `default_value` is +passed as a `string` regardless of the parameter type. +In particular boolean defaults are passed as `"True"` or `"False"` and **not** their YAML representations (`true` +, `false`). + +#### Options + +`options` can be set to provide a list of allowed values for this parameter, these will be presented in a dropdown +select component in the portal. + +**Example:** + +```yaml + - id: "sku" + name: "SKU" + description: "SKU" + value_type: string + options: + - name: "SKU1" + value: "sku1" + - name: "SKU2" + value: "sku2" + required: true + editable: false + enabled: true +``` + +If specifying `editable_direction`, it is recommended to add numerical `rank` values to the options (see above Editable +Direction for an example). + +#### Conditions + +`conditions` can be set to put conditions on when the parameter is to be included for a particular cluster. +If the cluster conditions for the parameter are not met by the target cluster, the parameter will be ignored, and will +not be displayed to the end user in the UI. + +**Example:** + +```yaml + - id: "aws-sts-arn" + name: "AWS STS ARN" + description: "AWS STS ARN (Only required for AWS STS clusters)" + value_type: string + conditions: + - resource: "cluster" + data: + aws.sts.enabled: true + cloud_provider.id: 'aws' + required: true + editable: false + enabled: true +``` + +#### Enabled + +The aim is to not remove parameters after they have been added to the metadata. To deprecate or disable a parameter +set `enabled` to `false` + +### Accessing parameter values + +To access parameter values in cluster, an add-on parameters secret `addon-<>-parameters` is created in +the `target namespace` of the add-on on the target cluster. This secret contains all the parameter information given at +installation time and is automatically updated as and when parameter values are updated. + +```bash +oc get secret/addon-<>-parameters -n <> -o json | jq '.data | map_values(@base64d)' +{ + "my-param": "my value", +} +``` diff --git a/content/en/docs/creating-addons/top-level-operator/OCM/addon-requirements.md b/content/en/docs/creating-addons/top-level-operator/OCM/addon-requirements.md new file mode 100644 index 00000000..f0443e35 --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/OCM/addon-requirements.md @@ -0,0 +1,230 @@ +--- +title: Addon Requirements +--- + +Requirements for an add-on can be defined using the `addOnRequirements` field. This field takes an array of requirement +objects. + +```yaml +addOnRequirements: + - resource: 'cluster' + id: 'my-cluster-req' + data: + cloud_provider.id: 'aws' + enabled: true +``` + +#### resource + +Requirements must have a `resource` field, and it must be a supported resource type, currently supported types: + +* `cluster` +* `addon` +* `machine_pool` + +#### id + +Requirements must have an 'id'. It can be anything, but it must be unique per addon/resource pair. + +#### enabled + +Indicates if the requirement is enabled or not. To deprecate or disable a parameter set `enabled` to `false`, or +alternatively remove it from the requirements list. + +#### data + +Resource specific data that is used to supply constraints on individual resource fields. +A constraint can be added here for any resource field that is exposed by the publicly facing API of that particular +resource. +Data is a map, and the key is a resource field represented in dot notation e.g. ccs.enabled == {ccs: {enabled: true}}, +the value is the value expected. + +For a list of currently supported fields please refer to +the [metadata schema](https://github.com/mt-sre/managed-tenants-cli/blob/main/managedtenants/schemas/shared/addon_requirements.json) + +## Compute Requirements + +Compute requirements can be set on a cluster or machine pool resource type that enforces that the resource is capable of +providing the specified compute capacity (cpu or memory). + +### compute.cpu + +Amount of vCPUs required by your addon. + +### compute.memory + +Amount of memory in bytes required by your addon. + +Example here would require the cluster to provide at lease '11' vCPUs and '25769803776' bytes or '24' GiB of memory +combined across all it's compute nodes. + +```yaml +addOnRequirements: + - resource: 'cluster' + id: 'my-cluster-compute-req' + data: + compute.memory: 25769803776, + compute.cpu: 11 + enabled: true +``` + +**Important Note**: Compute requirements, like all others, are only checking the relevant resource's (cluster/machine +pool) +specification within OCM, it does not check the current usage of the particular resource. If other workloads are already +using capacity it may still negatively impact your addons installation. + +## Platform Requirements + +Platform requirements can be set on a cluster if your addon only supports a particular version or versions of the +platform. Platform requirements can be specified as semantic version constraints. + +### version.raw_id + +The platform version(s) supported, a comma separated list of semantic version constraints using any of these +operators: ```"=","!=",">","<",">=","<=","~>"``` + +```yaml +addOnRequirements: + - resource: 'cluster' + id: 'my-cluster-req' + data: + version.raw_id: '>= 4.6, < 4.8, != 4.6.6' + enabled: true +``` + +## Managed Service - specific requirements + +AddOns that comprise a managed service have the option to specify **taint** and **label** requirements for machine pool +resources. +Declaring these requirements lets OCM know to build a machine pool with the taints/labels listed. + +```yaml + addOnRequirements: + - id: mp-requirements + resource: machine_pool + enabled: true + data: + taints: + - key: taint-key0 + value: taint-value0 + effect: NoSchedule + - key: taint-key1 + value: taint-value1 + effect: PreferNoSchedule + - key: taint-key2 + value: taint-value2 + effect: NoExecute + labels: + label0: value0 + label1: value1 + label2: value2 +``` + +## Examples + +### cluster + +The target cluster must have a `cloud_provider.id` of `aws` (My AddOn only works on AWS) + +```yaml +addOnRequirements: + - resource: 'cluster' + id: 'my-cluster-req' + data: + cloud_provider.id: 'aws' + enabled: true +``` + +### addon + +The `codeready-workspaces` addon must be installed + +```yaml +addOnRequirements: + - resource: 'addon' + id: 'my-addon-req' + data: + id: 'codeready-workspaces' + enabled: true +``` + +The code `codeready-workspaces` addon must be installed and in a `ready` state + +```yaml +addOnRequirements: + - resource: 'addon' + id: 'my-addon-req' + data: + id: 'codeready-workspaces' + state: 'ready' + enabled: true +``` + +### machine_pool + +A machine pool must exist. This does not include the `default` machine pool + +```yaml +addOnRequirements: + - resource: 'machine_pool' + id: 'my-machine-pool-req' + data: { } + enabled: true +``` + +A machine pool with the id `my-machine-pool` must exist + +```yaml +addOnRequirements: + - resource: 'machine_pool' + id: 'my-machine-pool-req' + data: + id: 'my-machine-pool' + enabled: true +``` + +A machine pool must exist with instance type of `m5.xlarge` and a minimum `2` replicas. Th*is includes the `default` +machine pool. + +```yaml +addOnRequirements: + - resource: 'machine_pool' + id: 'my-machine-pool-req' + data: + instance_type: 'm5.xlarge' + replicas: 2 + enabled: true +``` + +### Multiple + +```yaml +addOnRequirements: + - resource: 'cluster' + id: 'my-cluster-req' + data: + cloud_provider.id: 'aws' + ccs.enabled: false + product.id: 'osd' + nodes.compute: 4 + nodes.compute_machine_type.id: 'm5.xlarge' + enabled: true + - resource: 'addon' + id: 'my-addon-req' + data: + id: 'codeready-workspaces' + state: 'ready' + enabled: true + - resource: 'machine_pool' + id: 'my-machine-pool-req' + data: + id: 'addon-mas' + instance_type: 'm5.xlarge' + replicas: 2 + enabled: true +``` + +## Dynamically Set Requirements + +To allow the user to dynamically set requirements at install time, a `resource_requirement` parameter +can be used. See [resource_requirement parameter](addon-parameters.md#resource_requirement). diff --git a/content/en/docs/creating-addons/top-level-operator/OCM/addon-suboperators.md b/content/en/docs/creating-addons/top-level-operator/OCM/addon-suboperators.md new file mode 100644 index 00000000..c255c793 --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/OCM/addon-suboperators.md @@ -0,0 +1,30 @@ +--- +title: Addon Sub-Operators +--- + +To support umbrella add-on operators, a list of sub operators can be defined in the add-on metadata using the +`subOperators` field. This field takes an array of operator objects: + +```yaml +subOperators: + - operator_name: 'foo' + operator_namespace: 'bar' + enabled: true +``` + +> **_NOTE:_** The `subOperator` `operator_name` and `operator_namespace` is used by OCM when defining the current +state and status of an Add-on. Eg, if one operator is in a `failed` state, the add-on status will be `failed`. +The life cycle of the `subOperators` relies on the add-on operator itself and **not** OCM. + +### Operator Name + +`operator_name` is a required field in the operator object. + +### Operator Namespace + +`operator_namespace` is a required field in the operator object. + +### Enabled + +Indicates if the operator is enabled or not. To deprecate or disable an operator set `enabled` to `false`, or +alternatively remove it from the sub operators list. diff --git a/content/en/docs/creating-addons/top-level-operator/addon-metadata-file.md b/content/en/docs/creating-addons/top-level-operator/addon-metadata-file.md new file mode 100644 index 00000000..6a82bb7c --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/addon-metadata-file.md @@ -0,0 +1,13 @@ +--- +title: Addon Metadata File +linkTitle: Addon Metadata File +--- + +## Schema in Markdown + +Please view the [schema documentation](https://github.com/mt-sre/managed-tenants-cli/blob/main/docs/tenants/zz_metadata_schema_generated.md). + +## Existing PR checks for addon metadata + +* Checks in [managed-tenants repository](https://gitlab.cee.redhat.com/service/managed-tenants/-/tree/main/tasks/check) +* Check in [addon-metadata-operator repository](https://github.com/mt-sre/addon-metadata-operator/tree/e0cc0aecaf7c55a92e833eda45928db4fa737bdc/pkg/validator) 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 new file mode 100644 index 00000000..54c73f23 --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/addon-package.md @@ -0,0 +1,53 @@ +--- +title: Addon Package +linkTitle: Addon Package +--- + +## Feature Flag + +Currently, the addons plug and play functionality is hidden behind a feature flag. Feature flags are specified in +the `AddonOperator` resources under `.spec.featureflags`. This field is a string which is a comma separated +list of feature flags to enable. For addons plug and play and thus the addon package to be enabled, the string +`ADDONS_PLUG_AND_PLAY` has to be included in this field. + +## 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. + +The `ClusterPackage` manifest will look like this: + +```shell +apiVersion: package-operator.run/v1alpha1 +kind: ClusterPackage +metadata: + name: +spec: + image: + config: + addonsv1: + clusterID: a440b136-b2d6-406b-a884-fca2d62cd170 + deadMansSnitchUrl: https://example.com/test-snitch-url + ocmClusterID: abc123 + ocmClusterName: asdf + pagerDutyKey: 1234567890ABCDEF + parameters: + foo1: bar + foo2: baz + 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/) +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* +. + +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. diff --git a/content/en/docs/creating-addons/top-level-operator/create-an-addon.md b/content/en/docs/creating-addons/top-level-operator/create-an-addon.md new file mode 100644 index 00000000..9e884aa7 --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/create-an-addon.md @@ -0,0 +1,62 @@ +--- +title: Create an Addon +linkTitle: Create an Addon +weight: 20 +--- + + +## Shipping your addon through the `addon.yaml` manifest + +Your addon operator will be available through +a [`CatalogSource`](https://olm.operatorframework.io/docs/concepts/crds/catalogsource/) CR in OSD. For this to work, you +need to: + +- Build a catalog image available at `https://quay.io/osd-addons/-index` +- Build bundle images available at `https://quay.io/osd-addons/-bundle` + +Both the [`managed-tenants`](https://gitlab.cee.redhat.com/service/managed-tenants/) and +the [`managed-tenants-bundles`](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/) repositories will help +you in accomplishing this: + +### Imageset + +1. Create an initial merge request to `managed-tenants` with this file `addons//metadata/stage/addon.yaml`. + - Set `addonImageSetVersion: latest` + - So that your addon can use the SyncSet flow from the beginning, please also + set `syncsetMigration: "shortcircuit whitelist"`. + - Look at + the [reference-addon](https://gitlab.cee.redhat.com/service/managed-tenants/-/blob/main/addons/reference-addon/metadata/stage/addon.yaml) + , + the [jsonschema documentation](https://github.com/mt-sre/managed-tenants-cli/blob/main/docs/tenants/zz_metadata_schema_generated.md) + , + and the [validation PR checks](addon-metadata-file.md#existing-pr-checks-for-addon-metadata) for help. +2. Submit your bundles to the `managed-tenants-bundles` repository, respecting the directory structure. Specify that + your + addon will use imagesets by adding it to the list of imageset enabled addons (`IMAGESET_ENABLED_ADDONS`) in + the `Makefile`, + see [IMAGE_SET_ADDONS](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/blob/main/Makefile#L13). + - [Creating an operator Bundle](https://olm.operatorframework.io/docs/tasks/creating-operator-bundle/). + - [Example MR for dbaas-operator without IMAGESET_ENABLED_ADDONS](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/merge_requests/105) + . +3. The `managed-tenants-bundles` pipeline will automatically open a new MR to the `managed-tenants` repository, + adding a new imageset. + +### Index Image (deprecated) + +1. Create an initial MR to `managed-tenants` with this file `addons//metadata/stage/addon.yaml`. + - Set `indexImage: quay.io/osd-addons/` temporarily. It will be overridden automatically later. + - Look at + the [reference-addon](https://gitlab.cee.redhat.com/service/managed-tenants/-/blob/main/addons/reference-addon/metadata/stage/addon.yaml) + , + the [jsonschema documentation](https://github.com/mt-sre/managed-tenants-cli/blob/main/docs/tenants/zz_metadata_schema_generated.md) + , + and the [validation PR checks](addon-metadata-file.md#existing-pr-checks-for-addon-metadata) for help. + - [Example MR for dbaas-operator](https://gitlab.cee.redhat.com/service/managed-tenants/-/merge_requests/1270). +2. Submit your bundles to the `managed-tenants-bundles` repository, respecting the directory structure. + - [Creating an operator Bundle](https://olm.operatorframework.io/docs/tasks/creating-operator-bundle/). + - [Example MR for dbaas-operator](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/merge_requests/105). +3. The `managed-tenants-bundles` pipeline will automatically open a new MR to the `managed-tenants` repository, + modifying the `indexImage: <...>` field with your catalog image. + +See the [addon repository structure doc](content/en/docs/creating-addons/managed-tenants-repository.md#structure) for +more information. diff --git a/content/en/docs/creating-addons/top-level-operator/imageset-specification.md b/content/en/docs/creating-addons/top-level-operator/imageset-specification.md new file mode 100644 index 00000000..ec0d3701 --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/imageset-specification.md @@ -0,0 +1,8 @@ +--- +title: Imageset Specification +linkTitle: Imageset +--- + +## Json Schema in Markdown + +Please view the [imageset schema documentation](https://github.com/mt-sre/managed-tenants-cli/blob/main/docs/tenants/zz_imageset_schema_generated.md). diff --git a/content/en/docs/creating-addons/top-level-operator/migrate-to-imagesets.md b/content/en/docs/creating-addons/top-level-operator/migrate-to-imagesets.md new file mode 100644 index 00000000..ca58ce63 --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/migrate-to-imagesets.md @@ -0,0 +1,25 @@ +--- +title: Migrate to Imagesets +linkTitle: Migrate to Imagesets +--- + +All addons will eventually have to use imagesets. To start using imagesets, follow the steps below: + +1. In the `managed-tenants-bundles` repository, create a merge request making a no-op change in your addon's directory + *and* + add the name of your addon to the list of imageset enabled addons (`IMAGESET_ENABLED_ADDONS`) in the `Makefile`, + see [IMAGE_SET_ADDONS](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/blob/main/Makefile#L13). + + - See [this MR](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/merge_requests/608) + as an example. + - The `managed-tenants-bundles` pipeline will then create an imageset for your addon in the environment(s) specified + in `managed-tenants-bundles/addons//config/main.yaml` i.e. create an + imageset file in `addons//addonimagesets/` in the `managed-tenants` repository. To get an + imageset into production, please + see [promote an imageset to production](content/en/docs/release-process/promote-to-production.md). + +2. In the `managed-tenantes` repository, create a merge request replacing `indexImage: ...` + with `addonImageSetVersion: latest` + in the `addons//metadata//addon.yaml` file(s). + + - See [this MR](https://gitlab.cee.redhat.com/service/managed-tenants/-/merge_requests/2903) as an example. diff --git a/content/en/docs/creating-addons/top-level-operator/subscription-config.md b/content/en/docs/creating-addons/top-level-operator/subscription-config.md new file mode 100644 index 00000000..3ef343b7 --- /dev/null +++ b/content/en/docs/creating-addons/top-level-operator/subscription-config.md @@ -0,0 +1,57 @@ +--- +title: Subscription Config +linkTitle: Subscription Config +--- + +## Configs for addons + +Additional configs maybe supplied to an addon using the `config` attribute present in either the addon metadata file +or the addon imageset file. The attributes defined here are passed to the subscription OLM object. +Read more about subscription +config [here](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md) +. + +We support two ways of defining subscription configs for addons: + +- Version specific subscription config through the respective addon imageset file. This config takes precedence. +- A default subscription config through the addon metadata file (`addon.yaml` file) + +Currently, only the following sub-attributes are supported under `config`: + +- `env` : Defines an array of key value pairs (with the field `name` and `value` respectively). + The env field defines a list of Environment Variables that must exist in all containers in the Pod created by OLM + (values defined here will overwrite existing environment variables of the same name). + +Example: +Lets say in stage environment you want your addon to have a more verbose logging. Assuming that your addon sets the +logging level according to the value set in the environment variable `LOGGING_LEVEL`, you'd have the +following `stage/addon.yaml` file: + +```yaml +id: reference-addon +name: Reference Addon +description: Reference Addon is a real Addon, created to validate and demonstrate the Addons Flow. +link: https://github.com/openshift/reference-addon +icon: kLdODtkgbUXm7Htgt9scAMOODX6Tz2BImmdt/KGASyjvzlhfvjLU8wf0ZLk3JuMh4LOBxAgFJ5gDCGl31+DiW1syaLCjCDyBQHzIvQcM0CDLVq4MKAo3EMaluU4xB9C2Ys7K +label: api.openshift.com/addon-reference-addon +enabled: true +addonOwner: MT-SRE Team +quayRepo: quay.io/osd-addons/reference-addon +testHarness: quay.io/miwilson/addon-samples +installMode: OwnNamespace +targetNamespace: redhat-reference-addon +namespaces: +- redhat-reference-addon +ocmQuotaName: addon-reference-addon +ocmQuotaCost: 1 +operatorName: reference-addon +defaultChannel: alpha +bundleParameters: {} +namespaceLabels: {} +namespaceAnnotations: {} +indexImage: quay.io/osd-addons/reference-addon-index@sha256:b9e87a598e7fd6afb4bfedb31e4098435c2105cc8ebe33231c341e515ba9054d +config: +env: +- name: LOGGING_LEVEL + value: "VERBOSE" +``` diff --git a/content/en/docs/internal-documentation/cicd.md b/content/en/docs/internal-documentation/cicd.md new file mode 100644 index 00000000..47e9c0e7 --- /dev/null +++ b/content/en/docs/internal-documentation/cicd.md @@ -0,0 +1,9 @@ +--- +title: CI/CD +--- + +Addon Operator Pipeline Definition + + +Jenkins + diff --git a/content/en/docs/release-process/promote-to-production.md b/content/en/docs/release-process/promote-to-production.md new file mode 100644 index 00000000..6c394d36 --- /dev/null +++ b/content/en/docs/release-process/promote-to-production.md @@ -0,0 +1,31 @@ +--- +title: "Promote an Imageset to Production" +linkTitle: "Promote to Production" +--- + +Before starting, please make sure you have successfully switched your addon to imagesets in stage (and integration if +applicable), +see [here](content/en/docs/creating-addons/top-level-operator/migrate-to-imagesets.md). + +When you have thoroughly tested a version of your addon in stage and would like to +promote it to production, follow these steps: + +1. Create a merge request in `managed-tenants` copying the imageset file from `addons//addonimagesets/stage` + and + pasting it in `addons//addonimagesets/production`. +2. If this is the first time doing this i.e. your addon is not using imagesets in production yet, there is one more + step: In the same + merge request, replace `indexImage: ...` with `addonImageSetVersion: latest` in the + `addons//metadata/production/addon.yaml` file. + +Because the `addon.yaml` file refers to the latest imageset (`addonImageSetVersion: latest`), +this newer version you just moved will be picked up and deployed. + +## Versioning with imagesets + +Currently, the only supported value for `addonImageSetVersion` is `latest`. +This is because further work is pending to pin an addon's version in the OCM API. +Attempting to lower addon versions by removing imageset files will not have any effect. +Though it is possible to update an addon version in-place by modifying the corresponding +imageset this is discouraged. It is preferred to "fix-forward" with new versions even in +the event that the fix is just a reversion to a previous stable version. From 8e3caec858f2f663d5339a2f924aedb328ed7c3f Mon Sep 17 00:00:00 2001 From: gathomas Date: Wed, 31 May 2023 09:40:24 +0200 Subject: [PATCH 2/7] add link checker precommit hook --- .pre-commit-config.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e55f038d..be95fe09 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -21,3 +21,8 @@ repos: - id: markdownlint-fix types: [markdown] exclude: themes/ + - repo: https://github.com/tcort/markdown-link-check + rev: v3.11.2 + hooks: + - id: markdown-link-check + args: [ -q ] From 129520bd0591e392cc7539b107a5a770db6218dc Mon Sep 17 00:00:00 2001 From: gathomas Date: Mon, 5 Jun 2023 13:43:06 +0200 Subject: [PATCH 3/7] ignore sites with forwarding --- .link-check-config.json | 16 ++++++++++++++++ .pre-commit-config.yaml | 2 +- 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 .link-check-config.json diff --git a/.link-check-config.json b/.link-check-config.json new file mode 100644 index 00000000..0de2121b --- /dev/null +++ b/.link-check-config.json @@ -0,0 +1,16 @@ +{ + "ignorePatterns": [ + { + "pattern": "^content.*$" + }, + { + "pattern": "^\/.*$" + }, + { + "pattern": "^https://source.redhat.com" + }, + { + "pattern": "^https://rover.redhat.com" + } + ] +} \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index be95fe09..5faf3203 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -25,4 +25,4 @@ repos: rev: v3.11.2 hooks: - id: markdown-link-check - args: [ -q ] + args: [ '-c .link-check-config.json' ] From c5e2ebcb5b6d49a983ec92ebce5d7e435d045756 Mon Sep 17 00:00:00 2001 From: gathomas Date: Tue, 6 Jun 2023 14:30:07 +0200 Subject: [PATCH 4/7] exclude themes from link precommit hook --- .pre-commit-config.yaml | 1 + content/en/docs/internal-documentation/team_ceremonies.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5faf3203..aef169ba 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -26,3 +26,4 @@ repos: hooks: - id: markdown-link-check args: [ '-c .link-check-config.json' ] + exclude: ^themes/ diff --git a/content/en/docs/internal-documentation/team_ceremonies.md b/content/en/docs/internal-documentation/team_ceremonies.md index 01ff0493..f51c0ef2 100644 --- a/content/en/docs/internal-documentation/team_ceremonies.md +++ b/content/en/docs/internal-documentation/team_ceremonies.md @@ -28,7 +28,6 @@ happens right before the planning meeting for the next sprint: * and adapt it if necessary * in small steps and an iterative fashion * incorporate eventual process changes in the next sprint -* [Guide that @jgwosdz used for our first retro](https://www.notion.so/First-Retro-8cb1180cda1f4b03879065e225392b50) * Our retro dashboard with retros and derived action items: ## Sprint Review From 74ed9266dc91de79d611b4dcc1795d2379b5ade8 Mon Sep 17 00:00:00 2001 From: gathomas Date: Tue, 6 Jun 2023 14:32:58 +0200 Subject: [PATCH 5/7] remove link check --- .link-check-config.json | 16 ---------------- .pre-commit-config.yaml | 6 ------ 2 files changed, 22 deletions(-) delete mode 100644 .link-check-config.json diff --git a/.link-check-config.json b/.link-check-config.json deleted file mode 100644 index 0de2121b..00000000 --- a/.link-check-config.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "ignorePatterns": [ - { - "pattern": "^content.*$" - }, - { - "pattern": "^\/.*$" - }, - { - "pattern": "^https://source.redhat.com" - }, - { - "pattern": "^https://rover.redhat.com" - } - ] -} \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index aef169ba..e55f038d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -21,9 +21,3 @@ repos: - id: markdownlint-fix types: [markdown] exclude: themes/ - - repo: https://github.com/tcort/markdown-link-check - rev: v3.11.2 - hooks: - - id: markdown-link-check - args: [ '-c .link-check-config.json' ] - exclude: ^themes/ From 753a94caaf7ff641ea438119d8ae96d4a4e7e1f1 Mon Sep 17 00:00:00 2001 From: gathomas Date: Mon, 19 Jun 2023 16:45:38 +0200 Subject: [PATCH 6/7] remove addon package documentation --- .../top-level-operator/addon-package.md | 53 ------------------- 1 file changed, 53 deletions(-) delete mode 100644 content/en/docs/creating-addons/top-level-operator/addon-package.md 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 deleted file mode 100644 index 54c73f23..00000000 --- a/content/en/docs/creating-addons/top-level-operator/addon-package.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Addon Package -linkTitle: Addon Package ---- - -## Feature Flag - -Currently, the addons plug and play functionality is hidden behind a feature flag. Feature flags are specified in -the `AddonOperator` resources under `.spec.featureflags`. This field is a string which is a comma separated -list of feature flags to enable. For addons plug and play and thus the addon package to be enabled, the string -`ADDONS_PLUG_AND_PLAY` has to be included in this field. - -## 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. - -The `ClusterPackage` manifest will look like this: - -```shell -apiVersion: package-operator.run/v1alpha1 -kind: ClusterPackage -metadata: - name: -spec: - image: - config: - addonsv1: - clusterID: a440b136-b2d6-406b-a884-fca2d62cd170 - deadMansSnitchUrl: https://example.com/test-snitch-url - ocmClusterID: abc123 - ocmClusterName: asdf - pagerDutyKey: 1234567890ABCDEF - parameters: - foo1: bar - foo2: baz - 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/) -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* -. - -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. From d20a5c8e4f1071995da2486de5205e86aa125b8f Mon Sep 17 00:00:00 2001 From: gathomas Date: Tue, 20 Jun 2023 15:35:25 +0200 Subject: [PATCH 7/7] suggestion from Mark --- content/en/docs/creating-addons/managed-tenants-repository.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/creating-addons/managed-tenants-repository.md b/content/en/docs/creating-addons/managed-tenants-repository.md index 552af2ae..fbad2a7b 100644 --- a/content/en/docs/creating-addons/managed-tenants-repository.md +++ b/content/en/docs/creating-addons/managed-tenants-repository.md @@ -29,8 +29,8 @@ addons/ocs-converged ### addon imagesets -Our tooling now supports creating imagesets for addons. Imageset of a new version of -an addon sits inside a new directory called `addonimagesets/`. CPaaS/Tenants will need to create +Our tooling now supports creating imagesets for addons. The imageset of a new version of +an addon, which sits inside a new directory called `addonimagesets/`. CPaaS/Tenants will need to create a merge request in in order to notify MT-SRE of the availability of the new release. Each new addon version is a new file under the earlier mentioned `addonimagesets/` directory.