diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index 1691cf58ca..0e17a1c1e9 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -224,9 +224,9 @@ endif::[] :lvms-first: Logical Volume Manager (LVM) Storage :lvms: LVM Storage //Operator SDK version -:osdk_ver: 1.36.1 +:osdk_ver: 1.38.0 //Operator SDK version that shipped with the previous OCP 4.x release -:osdk_ver_n1: 1.31.0 +:osdk_ver_n1: 1.36.1 //Version-agnostic OLM :olm-first: Operator Lifecycle Manager (OLM) :olm: OLM diff --git a/modules/osdk-ansible-inside-operator-logs-full-result.adoc b/modules/osdk-ansible-inside-operator-logs-full-result.adoc index de8806af83..d346d28e1e 100644 --- a/modules/osdk-ansible-inside-operator-logs-full-result.adoc +++ b/modules/osdk-ansible-inside-operator-logs-full-result.adoc @@ -10,7 +10,7 @@ You can set the environment variable `ANSIBLE_DEBUG_LOGS` to `True` to enable ch .Procedure -* Edit the `config/manager/manager.yaml` and `config/default/manager_auth_proxy_patch.yaml` files to include the following configuration: +* Edit the `config/manager/manager.yaml` and `config/default/manager_metrics_patch.yaml` files to include the following configuration: + [source,terminal] ---- diff --git a/modules/osdk-updating-1361-to-138.adoc b/modules/osdk-updating-1361-to-138.adoc new file mode 100644 index 0000000000..ea31057a34 --- /dev/null +++ b/modules/osdk-updating-1361-to-138.adoc @@ -0,0 +1,419 @@ +// Module included in the following assemblies: +// +// * operators/operator_sdk/golang/osdk-golang-updating-projects.adoc +// * operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc +// * operators/operator_sdk/helm/osdk-helm-updating-projects.adoc + +ifeval::["{context}" == "osdk-golang-updating-projects"] +:golang: +:type: Go +endif::[] +ifeval::["{context}" == "osdk-ansible-updating-projects"] +:ansible: +:type: Ansible +endif::[] +ifeval::["{context}" == "osdk-helm-updating-projects"] +:helm: +:type: Helm +endif::[] + +:_mod-docs-content-type: PROCEDURE +[id="osdk-upgrading-projects_{context}"] += Updating {type}-based Operator projects for Operator SDK {osdk_ver} + +The following procedure updates an existing {type}-based Operator project for compatibility with {osdk_ver}. + +.Prerequisites + +* Operator SDK {osdk_ver} installed +* An Operator project created or maintained with Operator SDK {osdk_ver_n1} + +.Procedure + +// The following few steps should be retained/updated for each new migration procedure, as they're just bumping the OSDK version for each language type. + +. Edit the Makefile of your Operator project to update the Operator SDK version to {osdk_ver}, as shown in the following example: ++ +.Example Makefile +[source,make,subs="attributes+"] +---- +# Set the Operator SDK version to use. By default, what is installed on the system is used. +# This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit. +OPERATOR_SDK_VERSION ?= v{osdk_ver} <1> +---- +<1> Change the version from `{osdk_ver_n1}` to `{osdk_ver}`. +ifdef::helm[] +. Edit the Makefile of your Operator project to update the `ose-helm-rhel9-operator` image tag to `{product-version}`, as shown in the following example: ++ +.Example Dockerfile +[source,docker,subs="attributes+"] +---- +FROM registry.redhat.io/openshift4/ose-helm-rhel9-operator:v{product-version} +---- +endif::helm[] + +ifdef::ansible[] +. Edit the Dockerfile of your Operator project to update the `ose-ansible-operator` image tag to `{product-version}`, as shown in the following example: ++ +.Example Dockerfile +[source,docker,subs="attributes+"] +---- +FROM registry.redhat.io/openshift4/ose-ansible-operator:v{product-version} +---- +endif::ansible[] + +. You must upgrade the Kubernetes versions in your Operator project to use 1.30 and Kubebuilder v4. ++ +[TIP] +==== +This update include complex scaffolding changes due to the removal of link:https://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy]. If these migrations become difficult to follow, scaffold a new sample project for comparison. +==== + +ifdef::helm,ansible[] +.. Update the Kustomize version in your Makefile by making the following changes: ++ +[source,diff] +---- +- curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v5.3.0/kustomize_v5.3.0_$(OS)_$(ARCH).tar.gz | \ ++ curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v5.4.2/kustomize_v5.4.2_$(OS)_$(ARCH).tar.gz | \ +---- +endif::helm,ansible[] + +ifdef::golang[] +.. Update your `go.mod` file with the following changes to upgrade your dependencies: ++ +[source,go] +---- +go 1.22.0 + +github.com/onsi/ginkgo/v2 v2.17.1 +github.com/onsi/gomega v1.32.0 +k8s.io/api v0.30.1 +k8s.io/apimachinery v0.30.1 +k8s.io/client-go v0.30.1 +sigs.k8s.io/controller-runtime v0.18.4 +---- + +.. Download the upgraded dependencies by running the following command: ++ +[source,terminal] +---- +$ go mod tidy +---- + +.. Update your Makefile with the following changes: ++ +[source,diff] +---- +- ENVTEST_K8S_VERSION = 1.29.0 ++ ENVTEST_K8S_VERSION = 1.30.0 +---- ++ +[source,diff] +---- +- KUSTOMIZE ?= $(LOCALBIN)/kustomize-$(KUSTOMIZE_VERSION) +- CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen-$(CONTROLLER_TOOLS_VERSION) +- ENVTEST ?= $(LOCALBIN)/setup-envtest-$(ENVTEST_VERSION) +- GOLANGCI_LINT = $(LOCALBIN)/golangci-lint-$(GOLANGCI_LINT_VERSION) ++ KUSTOMIZE ?= $(LOCALBIN)/kustomize ++ CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen ++ ENVTEST ?= $(LOCALBIN)/setup-envtest ++ GOLANGCI_LINT = $(LOCALBIN)/golangci-lint +---- ++ +[source,diff] +---- +- KUSTOMIZE_VERSION ?= v5.3.0 +- CONTROLLER_TOOLS_VERSION ?= v0.14.0 +- ENVTEST_VERSION ?= release-0.17 +- GOLANGCI_LINT_VERSION ?= v1.57.2 ++ KUSTOMIZE_VERSION ?= v5.4.2 ++ CONTROLLER_TOOLS_VERSION ?= v0.15.0 ++ ENVTEST_VERSION ?= release-0.18 ++ GOLANGCI_LINT_VERSION ?= v1.59.1 +---- ++ +[source,diff] +---- +- $(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,${GOLANGCI_LINT_VERSION}) ++ $(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION)) +---- ++ +[source,diff] +---- +- $(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,${GOLANGCI_LINT_VERSION}) ++ $(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION)) +---- ++ +[source,diff] +---- +- @[ -f $(1) ] || { \ ++ @[ -f "$(1)-$(3)" ] || { \ + echo "Downloading $${package}" ;\ ++ rm -f $(1) || true ;\ +- mv "$$(echo "$(1)" | sed "s/-$(3)$$//")" $(1) ;\ +- } ++ mv $(1) $(1)-$(3) ;\ ++ } ;\ ++ ln -sf $(1)-$(3) $(1) +---- + +.. Update your `.golangci.yml` file with the following changes: ++ +[source,diff] +---- +- exportloopref ++ - ginkgolinter + - prealloc ++ - revive ++ ++ linters-settings: ++ revive: ++ rules: ++ - name: comment-spacings +---- + +.. Update your Dockerfile with the following changes: ++ +[source,diff] +---- +- FROM golang:1.21 AS builder ++ FROM golang:1.22 AS builder +---- + +.. Update your `main.go` file with the following changes: ++ +[source,diff] +---- + "sigs.k8s.io/controller-runtime/pkg/log/zap" ++ "sigs.k8s.io/controller-runtime/pkg/metrics/filters" + + var enableHTTP2 bool +- flag.StringVar(&metricsAddr, "metrics-bind-address", ":8080", "The address the metric endpoint binds to.") ++ var tlsOpts []func(*tls.Config) ++ flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+ ++ "Use :8443 for HTTPS or :8080 for HTTP, or leave as 0 to disable the metrics service.") + flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.") + flag.BoolVar(&enableLeaderElection, "leader-elect", false, + "Enable leader election for controller manager. "+ + "Enabling this will ensure there is only one active controller manager.") +- flag.BoolVar(&secureMetrics, "metrics-secure", false, +- "If set the metrics endpoint is served securely") ++ flag.BoolVar(&secureMetrics, "metrics-secure", true, ++ "If set, the metrics endpoint is served securely via HTTPS. Use --metrics-secure=false to use HTTP instead.") + +- tlsOpts := []func(*tls.Config){} + ++ // Metrics endpoint is enabled in 'config/default/kustomization.yaml'. The Metrics options configure the server. ++ // More info: ++ // - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.18.4/pkg/metrics/server ++ // - https://book.kubebuilder.io/reference/metrics.html ++ metricsServerOptions := metricsserver.Options{ ++ BindAddress: metricsAddr, ++ SecureServing: secureMetrics, ++ // TODO(user): TLSOpts is used to allow configuring the TLS config used for the server. If certificates are ++ // not provided, self-signed certificates will be generated by default. This option is not recommended for ++ // production environments as self-signed certificates do not offer the same level of trust and security ++ // as certificates issued by a trusted Certificate Authority (CA). The primary risk is potentially allowing ++ // unauthorized access to sensitive metrics data. Consider replacing with CertDir, CertName, and KeyName ++ // to provide certificates, ensuring the server communicates using trusted and secure certificates. ++ TLSOpts: tlsOpts, ++ } ++ ++ if secureMetrics { ++ // FilterProvider is used to protect the metrics endpoint with authn/authz. ++ // These configurations ensure that only authorized users and service accounts ++ // can access the metrics endpoint. The RBAC are configured in 'config/rbac/kustomization.yaml'. More info: ++ // https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.18.4/pkg/metrics/filters#WithAuthenticationAndAuthorization ++ metricsServerOptions.FilterProvider = filters.WithAuthenticationAndAuthorization ++ } ++ + mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{ +- Scheme: scheme, +- Metrics: metricsserver.Options{ +- BindAddress: metricsAddr, +- SecureServing: secureMetrics, +- TLSOpts: tlsOpts, +- }, ++ Scheme: scheme, ++ Metrics: metricsServerOptions, +---- +endif::golang[] + +.. Update your `config/default/kustomization.yaml` file with the following changes: ++ +[source,diff] +---- + # [PROMETHEUS] To enable prometheus monitor, uncomment all sections with 'PROMETHEUS'. + #- ../prometheus ++ # [METRICS] Expose the controller manager metrics service. ++ - metrics_service.yaml + ++ # Uncomment the patches line if you enable Metrics, and/or are using webhooks and cert-manager + patches: +- # Protect the /metrics endpoint by putting it behind auth. +- # If you want your controller-manager to expose the /metrics +- # endpoint w/o any authn/z, please comment the following line. +- - path: manager_auth_proxy_patch.yaml ++ # [METRICS] The following patch will enable the metrics endpoint using HTTPS and the port :8443. ++ # More info: https://book.kubebuilder.io/reference/metrics ++ - path: manager_metrics_patch.yaml ++ target: ++ kind: Deployment +---- + +.. Remove the `config/default/manager_auth_proxy_patch.yaml` and `config/default/manager_config_patch.yaml` files. + +.. Create a `config/default/manager_metrics_patch.yaml` file with the following content: ++ +[source,text,subs="attributes+"] +---- +# This patch adds the args to allow exposing the metrics endpoint using HTTPS +- op: add + path: /spec/template/spec/containers/0/args/0 + value: --metrics-bind-address=:8443 +ifdef::helm,ansible[] +# This patch adds the args to allow securing the metrics endpoint +- op: add + path: /spec/template/spec/containers/0/args/0 + value: --metrics-secure +# This patch adds the args to allow RBAC-based authn/authz the metrics endpoint +- op: add + path: /spec/template/spec/containers/0/args/0 + value: --metrics-require-rbac +endif::helm,ansible[] +---- + +.. Create a `config/default/metrics_service.yaml` file with the following content: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Service +metadata: + labels: + control-plane: controller-manager + app.kubernetes.io/name: + app.kubernetes.io/managed-by: kustomize + name: controller-manager-metrics-service + namespace: system +spec: + ports: + - name: https + port: 8443 + protocol: TCP + targetPort: 8443 + selector: + control-plane: controller-manager +---- + +.. Update your `config/manager/manager.yaml` file with the following changes: ++ +[source,diff,subs="attributes+"] +---- + - --leader-elect +ifdef::golang,helm[] ++ - --health-probe-bind-address=:8081 +endif::[] +ifdef::ansible[] ++ - --health-probe-bind-address=:6789 +endif::[] +---- + +.. Update your `config/prometheus/monitor.yaml` file with the following changes: ++ +[source,diff] +---- + - path: /metrics +- port: https ++ port: https # Ensure this is the name of the port that exposes HTTPS metrics + tlsConfig: ++ # TODO(user): The option insecureSkipVerify: true is not recommended for production since it disables ++ # certificate verification. This poses a significant security risk by making the system vulnerable to ++ # man-in-the-middle attacks, where an attacker could intercept and manipulate the communication between ++ # Prometheus and the monitored services. This could lead to unauthorized access to sensitive metrics data, ++ # compromising the integrity and confidentiality of the information. ++ # Please use the following options for secure configurations: ++ # caFile: /etc/metrics-certs/ca.crt ++ # certFile: /etc/metrics-certs/tls.crt ++ # keyFile: /etc/metrics-certs/tls.key + insecureSkipVerify: true +---- + +.. Remove the following files from the `config/rbac/` directory: ++ +-- +* `auth_proxy_client_clusterrole.yaml` +* `auth_proxy_role.yaml` +* `auth_proxy_role_binding.yaml` +* `auth_proxy_service.yaml` +-- + +.. Update your `config/rbac/kustomization.yaml` file with the following changes: ++ +[source,diff] +---- + - leader_election_role_binding.yaml +- # Comment the following 4 lines if you want to disable +- # the auth proxy (https://github.com/brancz/kube-rbac-proxy) +- # which protects your /metrics endpoint. +- - auth_proxy_service.yaml +- - auth_proxy_role.yaml +- - auth_proxy_role_binding.yaml +- - auth_proxy_client_clusterrole.yaml ++ # The following RBAC configurations are used to protect ++ # the metrics endpoint with authn/authz. These configurations ++ # ensure that only authorized users and service accounts ++ # can access the metrics endpoint. Comment the following ++ # permissions if you want to disable this protection. ++ # More info: https://book.kubebuilder.io/reference/metrics.html ++ - metrics_auth_role.yaml ++ - metrics_auth_role_binding.yaml ++ - metrics_reader_role.yaml +---- + +.. Create a `config/rbac/metrics_auth_role_binding.yaml` file with the following content: ++ +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: metrics-auth-rolebinding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: metrics-auth-role +subjects: + - kind: ServiceAccount + name: controller-manager + namespace: system +---- + +.. Create a `config/rbac/metrics_reader_role.yaml` file with the following content: ++ +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: metrics-reader +rules: +- nonResourceURLs: + - "/metrics" + verbs: + - get +---- + +ifeval::["{context}" == "osdk-golang-updating-projects"] +:!golang: +:!type: +endif::[] +ifeval::["{context}" == "osdk-ansible-updating-projects"] +:!ansible: +:!type: +endif::[] +ifeval::["{context}" == "osdk-helm-updating-projects"] +:!helm: +:!type: +endif::[] \ No newline at end of file diff --git a/operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc b/operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc index ddb935b12d..f0e5f17a51 100644 --- a/operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc +++ b/operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc @@ -12,15 +12,11 @@ include::snippets/osdk-deprecation.adoc[] However, to ensure your existing Operator projects maintain compatibility with Operator SDK {osdk_ver}, update steps are required for the associated breaking changes introduced since {osdk_ver_n1}. You must perform the update steps manually in any of your Operator projects that were previously created or maintained with {osdk_ver_n1}. -include::modules/osdk-updating-131-to-1361.adoc[leveloffset=+1] +include::modules/osdk-updating-1361-to-138.adoc[leveloffset=+1] [id="additional-resources_osdk-ansible-upgrading-projects"] [role="_additional-resources"] == Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html-single/operators/index#osdk-upgrading-projects_osdk-ansible-updating-projects[Upgrading projects for Operator SDK v1.25.4] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.11/html-single/operators/index#osdk-upgrading-projects_osdk-ansible-updating-projects[Upgrading projects for Operator SDK v1.22.0] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.10/html-single/operators/index#osdk-upgrading-v1101-to-v1160_osdk-upgrading-projects[Upgrading projects for Operator SDK v1.16.0] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.9/html/operators/developing-operators#osdk-upgrading-v180-to-v1101_osdk-upgrading-projects[Upgrading projects for Operator SDK v1.10.1] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.8/html/operators/developing-operators#osdk-upgrading-v130-to-v180_osdk-upgrading-projects[Upgrading projects for Operator SDK v1.8.0] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html-single/operators/index#osdk-upgrading-projects_osdk-ansible-updating-projects[Updating Ansible-based Operator projects for Operator SDK 1.36.1] ({product-title} 4.17) * xref:../../../operators/operator_sdk/osdk-pkgman-to-bundle.adoc#osdk-pkgman-to-bundle[Migrating package manifest projects to bundle format] diff --git a/operators/operator_sdk/golang/osdk-golang-updating-projects.adoc b/operators/operator_sdk/golang/osdk-golang-updating-projects.adoc index 80b6643145..3f0b2e7d10 100644 --- a/operators/operator_sdk/golang/osdk-golang-updating-projects.adoc +++ b/operators/operator_sdk/golang/osdk-golang-updating-projects.adoc @@ -12,11 +12,11 @@ include::snippets/osdk-deprecation.adoc[] However, to ensure your existing Operator projects maintain compatibility with Operator SDK {osdk_ver}, update steps are required for the associated breaking changes introduced since {osdk_ver_n1}. You must perform the update steps manually in any of your Operator projects that were previously created or maintained with {osdk_ver_n1}. -include::modules/osdk-updating-131-to-1361.adoc[leveloffset=+1] +include::modules/osdk-updating-1361-to-138.adoc[leveloffset=+1] [id="additional-resources_osdk-upgrading-projects-golang"] [role="_additional-resources"] == Additional resources -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html-single/operators/index#osdk-upgrading-projects_osdk-golang-updating-projects[Upgrading projects for Operator SDK 1.31.0] ({product-title} 4.16) +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html-single/operators/index#osdk-upgrading-projects_osdk-golang-updating-projects[Updating Go-based projects for Operator SDK 1.36.1] ({product-title} 4.17) * xref:../../../operators/operator_sdk/osdk-pkgman-to-bundle.adoc#osdk-pkgman-to-bundle[Migrating package manifest projects to bundle format] \ No newline at end of file diff --git a/operators/operator_sdk/helm/osdk-helm-updating-projects.adoc b/operators/operator_sdk/helm/osdk-helm-updating-projects.adoc index 0b441a0293..ebe3067e47 100644 --- a/operators/operator_sdk/helm/osdk-helm-updating-projects.adoc +++ b/operators/operator_sdk/helm/osdk-helm-updating-projects.adoc @@ -12,13 +12,11 @@ include::snippets/osdk-deprecation.adoc[] However, to ensure your existing Operator projects maintain compatibility with Operator SDK {osdk_ver}, update steps are required for the associated breaking changes introduced since {osdk_ver_n1}. You must perform the update steps manually in any of your Operator projects that were previously created or maintained with {osdk_ver_n1}. -include::modules/osdk-updating-131-to-1361.adoc[leveloffset=+1] +include::modules/osdk-updating-1361-to-138.adoc[leveloffset=+1] [id="additional-resources_osdk-helm-upgrading-projects"] [role="_additional-resources"] == Additional resources -* xref:../../../operators/operator_sdk/osdk-pkgman-to-bundle.adoc#osdk-pkgman-to-bundle[Migrating package manifest projects to bundle format] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.10/html-single/operators/index#osdk-upgrading-v1101-to-v1160_osdk-upgrading-projects[Upgrading projects for Operator SDK 1.16.0] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.9/html/operators/developing-operators#osdk-upgrading-v180-to-v1101_osdk-upgrading-projects[Upgrading projects for Operator SDK v1.10.1] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.8/html/operators/developing-operators#osdk-upgrading-v130-to-v180_osdk-upgrading-projects[Upgrading projects for Operator SDK v1.8.0] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html-single/operators/index#osdk-upgrading-projects_osdk-helm-updating-projects[Updating Helm-based Operator projects for Operator SDK 1.36.1] ({product-title} 4.17) +* xref:../../../operators/operator_sdk/osdk-pkgman-to-bundle.adoc#osdk-pkgman-to-bundle[Migrating package manifest projects to bundle format] \ No newline at end of file