From 1adc563e83a8b9f29a0c439b6fd4ef0365dbbec0 Mon Sep 17 00:00:00 2001 From: AnnaZivkovic Date: Wed, 11 Sep 2024 13:11:07 -0700 Subject: [PATCH 1/2] Added documentation --- docs/ocp-release.md | 282 ++++++++++++++++++++++++++++---------------- 1 file changed, 183 insertions(+), 99 deletions(-) diff --git a/docs/ocp-release.md b/docs/ocp-release.md index 9c1c05cff..6cfedb6e7 100644 --- a/docs/ocp-release.md +++ b/docs/ocp-release.md @@ -1,117 +1,189 @@ + +### Branching and creation of a new development stream +This is done at the beginning of a release cycle. + +1. Create new branch off of main. For example v1.0, v0.9. +2. Define a new Development Stream for the operator in the [Konflux + cluster](https://gitlab.cee.redhat.com/releng/konflux-release-data).

+ Create a new directory + `tenants-config/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/_base/projectl.konflux.dev/projectdevelopmentstreams/multiarch-tuning-operator-`. + For instance, when the branch version is `v1.0`, replace the period (`.`) with a dash (`-`). Thus, `` would + be formatted as `v1-0`. + Add two files to the directory `projectdevelopmentstream.yaml` and `kustomization.yaml`. + + ```yaml + # multiarch-tuning-operator-/projectdevelopmentstream.yaml + --- + apiVersion: projctl.konflux.dev/v1beta1 + kind: ProjectDevelopmentStream + metadata: + name: multiarch-tuning-operator- + spec: + + project: multiarch-tuning-operator + template: + name: multiarch-tuning-operator + values: + - name: version + # The branch name, formatted without the 'v' prefix (e.g., '1.0' for branch 'v1.0') + value: + ``` + + ```yaml + # multiarch-tuning-operator-/kustomization.yaml + --- + kind: Kustomization + apiVersion: kustomize.config.k8s.io/v1beta1 + resources: + - ./projectdevelopmentstream.yaml + ``` + + Update `tenants-config/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/_base/kustomization.yaml` file to + include the newly added `projectdevelopmentstreams`.

+ Run `build-manifests.sh` to generate auxiliary files. After making the changes, create a new pull request. + +3. Update the tekton files in the newly created branch. An example can be found [here](https://github.com/openshift/multiarch-tuning-operator/commit/b31311f3e642b2ba4ac71b32a675395962d5dd38). + ### Release the operator (for OCP) +1. When planning to release a new version (e.g. v1.0) or a patch version (e.g., v1.0.z), select a snapshot from the +corresponding Konflux application +and ensure all post-submit checks have successfully passed. + + ```shell + oc get snapshots --sort-by .metadata.creationTimestamp -l pac.test.appstudio.openshift.io/event-type=push,appstudio.openshift.io/application=multiarch-tuning-operator- + ``` + +3. Look at the results of the tests for the commit reported in the snapshot: + + ```yaml + [ ... ] + spec: + application: multiarch-tuning-operator + artifacts: { } + components: + - containerImage: quay.io/redhat-user-workloads/multiarch-tuning-ope-tenant/multiarch-tuning-operator-/multiarch-tuning-operator-@sha256:250498c137c91f8f932317d48ecacb0d336e705828d3a4163e684933b610547f + name: multiarch-tuning-operator- + source: + git: + revision: d73959c925629f29f9071fd6e7d58a0f58a54399 + url: https://github.com/openshift/multiarch-tuning-operator + - containerImage: quay.io/redhat-user-workloads/multiarch-tuning-ope-tenant/multiarch-tuning-operator-/multiarch-tuning-operator-bundle-@sha256:be0945723a0a5ad881d135b3f83a65b0e8fc69c0da337339587aebed4bee89a1 + name: multiarch-tuning-operator-bundle- + source: + git: + context: ./ + dockerfileUrl: bundle.Dockerfile + revision: d73959c925629f29f9071fd6e7d58a0f58a54399 + url: https://github.com/openshift/multiarch-tuning-operator + [ ... ] + ``` + +4. Ensure that the `containerImage` of the operator matches the one referenced by the bundle in the selected snapshot. + This value should not be updated manually—Konflux will automatically file the PR. If it doesn’t, there may be an + issue with the nudging process, and you should review the `Renovate` PipelineRun logs. Once resolved, wait for the new snapshot to be made + and restart at step 2.

+ Pull and save the pulled image to a tar file. Extract the tar file into the newly created directory and remember to extract the nested tar files. + + ```shell + find /tmp/operator_bundle -name "*.clusterserviceversion.yaml" -print + yq '.spec.install.spec.deployments[0].spec.template.metadata.annotations."multiarch.openshift.io/image"' + ``` -1. Choose a snapshot from the list of snapshots and double check post-submits passed for it. -```shell -oc get snapshots --sort-by .metadata.creationTimestamp -l pac.test.appstudio.openshift.io/event-type=push,appstudio.openshift.io/application=multiarch-tuning-operator -``` -2. Look at the results of the tests for the commit reported in the snapshot: -```yaml -[...] -spec: - application: multiarch-tuning-operator - artifacts: {} - components: - - containerImage: quay.io/redhat-user-workloads/multiarch-tuning-ope-tenant/multiarch-tuning-operator/multiarch-tuning-operator@sha256:250498c137c91f8f932317d48ecacb0d336e705828d3a4163e684933b610547f - name: multiarch-tuning-operator - source: - git: - revision: d73959c925629f29f9071fd6e7d58a0f58a54399 - url: https://github.com/openshift/multiarch-tuning-operator - - containerImage: quay.io/redhat-user-workloads/multiarch-tuning-ope-tenant/multiarch-tuning-operator/multiarch-tuning-operator-bundle@sha256:be0945723a0a5ad881d135b3f83a65b0e8fc69c0da337339587aebed4bee89a1 - name: multiarch-tuning-operator-bundle - source: - git: - context: ./ - dockerfileUrl: bundle.Dockerfile - revision: d73959c925629f29f9071fd6e7d58a0f58a54399 - url: https://github.com/openshift/multiarch-tuning-operator -[...] -``` -3. Ensure that the containerImage of the operator is the one referenced by the bundle in the selected snapshot -```shell -podman create quay.io/redhat-user-workloads/multiarch-tuning-ope-tenant/multiarch-tuning-operator/multiarch-tuning-operator-bundle@sha256:... -yq '.spec.install.spec.deployments[0].spec.template.metadata.annotations."multiarch.openshift.io/image"' /tmp/csv.yaml -``` -4. Create a new release for the operator in the Konflux cluster: -```yaml -# oc create -f - <.yaml` by + copping `openshift-multiarch-tuning-operator-main.yaml` and updating references from `main` to the new branch name. + (ex. https://github.com/openshift/release/pull/56835) + +7. Create a new `ReleasePlanAdmission` file in the directory + `konflux-release-data/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope`, + naming it `multiarch-tuning-operator-.yaml` where `` is the `konfluxVersion` without the " + v" (e.g., for `v1-0`, name it `multiarch-tuning-operator-1-0.yaml`). + Duplicate the contents of the existing ReleasePlanAdmission from the `multiarch-tuning-operator.yaml` file, update + the + - tags + - set the appropriate release notes version + - change metadata name from `multiarch-tuning-operator` to `multiarch-tuning-operator-` + - change the spec application name to `multiarch-tuning-operator-` + - change the components to include ``

+ Run `build-manifests.sh` to generate auxiliary files. After making the changes, create a new pull request. +8. Update the `fbc-4.x` branches to use the selected container image for both the bundle and operator. + Example [commit](https://github.com/openshift/multiarch-tuning-operator/pull/341). The process will generate and render + a new bundle—rather than modifying the existing reference, simply add a new bundle and introduce a new channel. + When updating the version of `registry.redhat.io/openshift4/ose-operator-registry:v4.1X`, ensure that all bundles are + re-rendered with the updated version per FBC. Failure to do so may result in pipeline execution errors. For example `4.17` bundles in the index.yaml must be generated using uses `registry.redhat.io/openshift4/ose-operator-registry:v4.14`, but `4.16` must have all of its bundles generated using `registry.redhat.io/openshift4/ose-operator-registry:v4.13`. + + ```shell + podman run -it --entrypoint /bin/opm -v $(pwd):/code:Z registry.redhat.io/openshift4/ose-operator-registry:v4.1X render --output=yaml + ``` + Make a pull request with the updated `index.yaml`. The commit message should resemble this [commit](https://github.com/openshift/multiarch-tuning-operator/pull/341). + +9. Get the new snapshot triggered by the build of the merge commit at the previous point and check the build pipeline for errors and warnings. + + ```shell + oc get snapshots --sort-by .metadata.creationTimestamp -l pac.test.appstudio.openshift.io/event-type=push,appstudio.openshift.io/application=fbc-v4-x + ``` + +10. Create a new Release for the fbc snapshot created after the commit in the previous step. + + ```yaml + # oc create -f - < + # EOF + ``` +11. Watch the `status` of the `Release` Object or look in the Konflux UI to confirm that images and bundle were published +as expected. Note that the peipeline is run in a different namespace (rhtap-releng-tenant). + +12. Once the release pipeline has succeeded view the index images provided in the task run section. + ```yaml + { + "index_image": { + "index_image": "registry-proxy.engineering.redhat.com/rh-osbs/iib:835019", + "index_image_resolved": "registry-proxy.engineering.redhat.com/rh-osbs/iib@sha256:d594746527f8acd02af12c48d15842f02cf61a3091aede7238d222f1d0ec92c5" + } + } + ``` + Take the index image and replace the registry `registry-proxy.engineering.redhat.com/rh-osbs/iib` with `brew.registry.redhat.io`. + The image to announce would look like `brew.registry.redhat.io:835019` + +### Create a new FBC fragment for a new OCP release The current approach is that for every new OCP release, we will have to: 1. Create New Konflux Application and Component for the FBC 2. Create a new branch in this repo like `fbc-4.16`. E.g., `fbc-4.17` for OCP 4.17 -3. Create a new PR in https://gitlab.cee.redhat.com/releng/konflux-release-data/-/tree/main with ReleasePlanAdmission for the new File Based Catalog (FBC) fragment, based on - a. https://gitlab.cee.redhat.com/releng/konflux-release-data/-/blob/main/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope/multiarch-tuning-operator-fbc-prod-index.yaml - b. https://gitlab.cee.redhat.com/releng/konflux-release-data/-/blob/main/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope/multiarch-tuning-operator-fbc-staging-index.yaml +3. Create a new PR in https://gitlab.cee.redhat.com/releng/konflux-release-data/-/tree/main with ReleasePlanAdmission for the new File Based Catalog (FBC) fragment, based on + a. https://gitlab.cee.redhat.com/releng/konflux-release-data/-/blob/main/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope/multiarch-tuning-operator-fbc-prod-index.yaml + b. https://gitlab.cee.redhat.com/releng/konflux-release-data/-/blob/main/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope/multiarch-tuning-operator-fbc-staging-index.yaml 4. Create a new PR in https://github.com/redhat-appstudio/tenants-config to add the ReleasePlan for the new FBC, based on - a. https://github.com/redhat-appstudio/tenants-config/tree/main/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/fbc_4_16/appstudio.redhat.com/releaseplans/fbc-v4-16-release-as-fbc - b. https://github.com/redhat-appstudio/tenants-config/tree/main/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/fbc_4_16/appstudio.redhat.com/releaseplans/fbc-v4-16-release-as-staging-fbc - c. https://github.com/redhat-appstudio/tenants-config/blob/main/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/fbc_4_16/kustomization.yaml + a. https://github.com/redhat-appstudio/tenants-config/tree/main/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/fbc_4_16/appstudio.redhat.com/releaseplans/fbc-v4-16-release-as-fbc + b. https://github.com/redhat-appstudio/tenants-config/tree/main/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/fbc_4_16/appstudio.redhat.com/releaseplans/fbc-v4-16-release-as-staging-fbc + c. https://github.com/redhat-appstudio/tenants-config/blob/main/cluster/stone-prd-rh01/tenants/multiarch-tuning-ope-tenant/fbc_4_16/kustomization.yaml 5. Adjust the graphs as needed in the branches. - - -### Other pre-release SDL activities +ies If the release is a major version or introduced significant - [architectural changes](https://docs.engineering.redhat.com/pages/viewpage.action?pageId=402429315), - ensure that the threat model is reviewed and updated accordingly. +[architectural changes](https://docs.engineering.redhat.com/pages/viewpage.action?pageId=402429315), +ensure that the threat model is reviewed and updated accordingly. SAST findings will be processed according to: + - https://spaces.redhat.com/display/PRODSEC/SAST+Workflow - https://spaces.redhat.com/display/PRODSEC/Weakness+Management+Standard - https://spaces.redhat.com/display/PRODSEC/Security+Errata+Standard -In general, SAST findings cause a PR to fail to merge. -It's the resposibility of the PR author to review the findings. +In general, SAST findings cause a PR to fail to merge. +It's the resposibility of the PR author to review the findings. -In case a finding is not a false positive, it needs to be classified as weakness or vulnerability -(if in doubt, contact the Security Architect for help). -Once classified, an appropriate Jira issue needs to be created (ask Security Architect for guidance). +In case a finding is not a false positive, it needs to be classified as weakness or vulnerability +(if in doubt, contact the Security Architect for help). +Once classified, an appropriate Jira issue needs to be created (ask Security Architect for guidance). The issues will have to be remediated according to the timelines set in the standard. @@ -119,24 +191,30 @@ If malware is detected, contact prodsec@redhat.com immediately. ## Pin to a new Golang and K8S API version -1. Update the Dockerfiles to use a base image with the desired Golang version (it should be the one used by k8s.io/api or openshift/api) +1. Update the Dockerfiles to use a base image with the desired Golang version (it should be the one used by k8s.io/api + or openshift/api) 2. Update the Makefile to use the new Golang version base image (BUILD_IMAGE variable) 3. Commit the changes to the Golang version 4. Update the k8s libraries in the go.mod file to the desired version 5. Update the dependencies with `go get -u`, and ensure no new version of the k8s API is used + ```shell go mod download go mod tidy -go mod verify +go mod verify ``` + 6. Commit the changes to go.mod and go.sum 7. Update the vendor/ folder + ```shell rm -rf vendor/ go mod vendor ``` + 8. Commit the changes to the vendor/ folder 9. Update the tools in the Makefile to the desired version: + ```makefile # https://github.com/kubernetes-sigs/kustomize/releases KUSTOMIZE_VERSION ?= v5.4.3 @@ -149,18 +227,23 @@ ENVTEST_K8S_VERSION = 1.29.3 # https://github.com/golangci/golangci-lint/releases GOLINT_VERSION = v1.60.1 ``` + 10. Commit the changes to the Makefile -11. Run the tests and ensure everything is building and working as expected. Look for deprecation warnings PRs in the controller-runtime repository. +11. Run the tests and ensure everything is building and working as expected. Look for deprecation warnings PRs in the + controller-runtime repository. + ```shell make docker-build make build make bundle make test ``` + 12. Commit any other changes to the code, if any 13. Create a PR with the changes. Example log: + ``` 02eb25dd (HEAD -> update-go) Add info in the ocp-release.md doc about k8s and golang upgrade 8e2d3389 Add info in the ocp-release.md doc about k8s and golang upgrade @@ -179,6 +262,7 @@ see https://github.com/openshift/release/pull/55728/commits/707fa080a66d8006c4a6 # Bumping the operator version To bump the operator version, run the following command: + ```shell make version VERSION=1.0.1 ``` From d7f1f30ced5012014ea9675f49969f8bff7131eb Mon Sep 17 00:00:00 2001 From: AnnaZivkovic Date: Tue, 19 Nov 2024 12:33:12 -0800 Subject: [PATCH 2/2] Updated docs on creating a new FBC fragment --- docs/ocp-release.md | 107 +++++++++++++++++++++++++++++++++----------- 1 file changed, 80 insertions(+), 27 deletions(-) diff --git a/docs/ocp-release.md b/docs/ocp-release.md index 6cfedb6e7..62c898d0d 100644 --- a/docs/ocp-release.md +++ b/docs/ocp-release.md @@ -44,6 +44,23 @@ This is done at the beginning of a release cycle. 3. Update the tekton files in the newly created branch. An example can be found [here](https://github.com/openshift/multiarch-tuning-operator/commit/b31311f3e642b2ba4ac71b32a675395962d5dd38). +4. Duplicate the prow config to target the new branch. Add + `ci-operator/config/openshift/multiarch-tuning-operator/openshift-multiarch-tuning-operator-.yaml` by + copping `openshift-multiarch-tuning-operator-main.yaml` and updating references from `main` to the new branch name. + (ex. https://github.com/openshift/release/pull/56835) +5. Create a new `ReleasePlanAdmission` file in the directory + `konflux-release-data/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope`, + naming it `multiarch-tuning-operator-.yaml` where `` is the `konfluxVersion` without the " + v" (e.g., for `v1-0`, name it `multiarch-tuning-operator-1-0.yaml`). + Duplicate the contents of the existing ReleasePlanAdmission from the `multiarch-tuning-operator.yaml` file, update + the + - tags + - set the appropriate release notes version + - change metadata name from `multiarch-tuning-operator` to `multiarch-tuning-operator-` + - change the spec application name to `multiarch-tuning-operator-` + - change the components to include ``

+ Run `build-manifests.sh` to generate auxiliary files. After making the changes, create a new pull request. + ### Release the operator (for OCP) 1. When planning to release a new version (e.g. v1.0) or a patch version (e.g., v1.0.z), select a snapshot from the corresponding Konflux application @@ -88,26 +105,62 @@ and ensure all post-submit checks have successfully passed. find /tmp/operator_bundle -name "*.clusterserviceversion.yaml" -print yq '.spec.install.spec.deployments[0].spec.template.metadata.annotations."multiarch.openshift.io/image"' ``` +9. Get the new snapshot triggered by the build of the merge commit at the previous point and check the build pipeline for errors and warnings. + ```shell + oc get snapshots --sort-by .metadata.creationTimestamp -l pac.test.appstudio.openshift.io/event-type=push,appstudio.openshift.io/application=fbc-v4-x + ``` + +10. Create a new Release for the operator snapshot in the previous step. + - Update the [allowed tags](https://gitlab.cee.redhat.com/releng/konflux-release-data/-/blob/main/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope/multiarch-tuning-operator-1-0.yaml#L27-28) for the release plan admission + ```yaml + ... + defaults: + tags: + - "1.0.0" + - "1.0.0-{{ timestamp }}" + - "add new tags" + ... + ``` + - In [comet](https://comet.engineering.redhat.com/containers/repositories/6616582895a35187a06ba2ce) add the new tag in the content streams field + - Create a new release for the operator + ```yaml + apiVersion: appstudio.redhat.com/v1alpha1 + kind: Release + metadata: + generateName: release-1-0-0- + namespace: multiarch-tuning-ope-tenant + spec: + releasePlan: multiarch-tuning-operator-1-0-release-as-operator + snapshot: multiarch-tuning-operator-1-0-5lr4j + data: + releaseNotes: + type: RHEA + synopsis: Red Hat Multiarch Tuning 1.0.0 + topic: >- + The 1.0.0 release of the Red Hat Multiarch Tuning Operator. + For more details, see [product documentation](https://docs.openshift.com/container-platform/4.17/post_installation_configuration/configuring-multi-arch-compute-machines/multiarch-tuning-operator.html). + description: >- + The Red Hat Multiarch Tuning Operator can be used with OpenShift Container Platform. + Enhancements: + - With this release, the Multiarch Tuning Operator supports custom network scenarios and cluster-wide custom registries configurations. + - With this release, you can identify pods based on their architecture compatibility by using the pod labels that the Operator adds to newly created pods. + - With this release, you can monitor the behavior of the Multiarch Tuning Operator by using the metrics and alerts registered in the cluster monitoring operator. + solution: >- + The Multiarch Tuning Operator optimizes workload management within multi-architecture clusters and in single-architecture clusters transitioning to multi-architecture environments. + This Operator is available in the Red Hat Operators catalog that is included with OpenShift Container Platform. + For more details, see [product documentation](https://docs.openshift.com/container-platform/4.17/post_installation_configuration/configuring-multi-arch-compute-machines/multiarch-tuning-operator.html). + references: + - https://docs.openshift.com/container-platform/4.17/post_installation_configuration/configuring-multi-arch-compute-machines/multiarch-tuning-operator.html + - https://github.com/openshift/multiarch-tuning-operator + ``` +11. Watch the `status` of the `Release` Object or look in the Konflux UI to confirm that images and bundle were published + as expected. Note that the peipeline is run in a different namespace (rhtap-releng-tenant). -6. Duplicate the prow config to target the new branch. Add - `ci-operator/config/openshift/multiarch-tuning-operator/openshift-multiarch-tuning-operator-.yaml` by - copping `openshift-multiarch-tuning-operator-main.yaml` and updating references from `main` to the new branch name. - (ex. https://github.com/openshift/release/pull/56835) +### Publish a released operator in the OCP's OperatorHub's FBCs +Note: these steps need to be applied to each FBC -7. Create a new `ReleasePlanAdmission` file in the directory - `konflux-release-data/config/stone-prd-rh01.pg1f.p1/product/ReleasePlanAdmission/multiarch-tuning-ope`, - naming it `multiarch-tuning-operator-.yaml` where `` is the `konfluxVersion` without the " - v" (e.g., for `v1-0`, name it `multiarch-tuning-operator-1-0.yaml`). - Duplicate the contents of the existing ReleasePlanAdmission from the `multiarch-tuning-operator.yaml` file, update - the - - tags - - set the appropriate release notes version - - change metadata name from `multiarch-tuning-operator` to `multiarch-tuning-operator-` - - change the spec application name to `multiarch-tuning-operator-` - - change the components to include ``

- Run `build-manifests.sh` to generate auxiliary files. After making the changes, create a new pull request. -8. Update the `fbc-4.x` branches to use the selected container image for both the bundle and operator. +1. Update the `fbc-4.x` branches to use the selected container image for both the bundle and operator. Example [commit](https://github.com/openshift/multiarch-tuning-operator/pull/341). The process will generate and render a new bundle—rather than modifying the existing reference, simply add a new bundle and introduce a new channel. When updating the version of `registry.redhat.io/openshift4/ose-operator-registry:v4.1X`, ensure that all bundles are @@ -124,7 +177,8 @@ and ensure all post-submit checks have successfully passed. oc get snapshots --sort-by .metadata.creationTimestamp -l pac.test.appstudio.openshift.io/event-type=push,appstudio.openshift.io/application=fbc-v4-x ``` -10. Create a new Release for the fbc snapshot created after the commit in the previous step. +10. Create a new Release for the fbc snapshot created after the commit in the previous step. + Note that we can run a staging release to test the release pipeline ```yaml # oc create -f - <