1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00

OSDK 1.38.0 migration docs for OCP 4.18 GA

This commit is contained in:
Alex Dellapenta
2025-02-18 21:33:42 -07:00
committed by openshift-cherrypick-robot
parent 70fafcdb05
commit bdd1aa689a
6 changed files with 429 additions and 16 deletions

View File

@@ -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

View File

@@ -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]
----

View File

@@ -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: <operator-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::[]

View File

@@ -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]

View File

@@ -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]

View File

@@ -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]