From e137da34f8647852e1db9ce0dd7bf59b03b2d8e0 Mon Sep 17 00:00:00 2001 From: hasbro17 Date: Sun, 8 Sep 2019 22:25:20 -0700 Subject: [PATCH 1/2] doc/migration: add sections for v0.8.x and v0.9.x --- doc/migration/version-upgrade-guide.md | 133 ++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 1 deletion(-) diff --git a/doc/migration/version-upgrade-guide.md b/doc/migration/version-upgrade-guide.md index 7224de885e2..c918cfbef9f 100644 --- a/doc/migration/version-upgrade-guide.md +++ b/doc/migration/version-upgrade-guide.md @@ -144,7 +144,7 @@ The following sections outline the upgrade steps for each SDK version along with ```TOML [[constraint]] name = "github.com/operator-framework/operator-sdk" - version = "=v0.4.1" + version = "=v0.6.0" ``` - The `operator-sdk olm-catalog` command now expects and generates manifests in the operator-registry [manifest format][manifest-format]. Generate your CSVs in the new layout by using `operator-sdk olm-catalog gen-csv` command, or modify the layout of your existing CSV manifests directory similar to the example below. @@ -168,8 +168,139 @@ The following sections outline the upgrade steps for each SDK version along with version = "=v0.7.1" ``` +## `v0.8.x` + +The SDK version `v0.8.x` supports scaffolding projects to use Go modules by default. It is recommended that you migrate your operator project to use modules for dependency management, however you can choose to keep using `dep`. The upgrade steps for both are outlined below: + +### `dep` +- Update the SDK constraint in `Gopkg.toml` to version `v0.8.2`. + ```TOML + [[constraint]] + name = "github.com/operator-framework/operator-sdk" + version = "=v0.8.2" + ``` +- Pin the controller-tools dependency to the following revision. See the release notes or [#1278](https://github.com/operator-framework/operator-sdk/pull/1278/) for why this is needed. + ```TOML + [[override]] + name = "sigs.k8s.io/controller-tools" + revision = "9d55346c2bde73fb3326ac22eac2e5210a730207" + ``` +- Run `dep ensure` to update the vendor directory. + +### `modules` + +To get familiar with Go modules read the [modules wiki][modules-wiki]. In particular the section on [migrating to modules][migrating-to-modules]. + +- Ensure that you have Go 1.12+ and [Mercurial][mercurial] 3.9+ installed. +- Activate Go modules support for your project in `$GOPATH/src` by setting the env `GO111MODULES=on`. See [activating modules][activating-modules] for more details. +- Initialize a new `go.mod` file by running `go mod init`. +- Append the following to the end of your `go.mod` file to pin the operator-sdk and other upstream dependencies to the required versions. +``` +// Pinned to kubernetes-1.13.1 +replace ( + k8s.io/api => k8s.io/api v0.0.0-20181213150558-05914d821849 + k8s.io/apiextensions-apiserver => k8s.io/apiextensions-apiserver v0.0.0-20181213153335-0fe22c71c476 + k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20181127025237-2b1284ed4c93 + k8s.io/client-go => k8s.io/client-go v0.0.0-20181213151034-8d9ed539ba31 +) + +replace ( + github.com/coreos/prometheus-operator => github.com/coreos/prometheus-operator v0.29.0 + k8s.io/code-generator => k8s.io/code-generator v0.0.0-20181117043124-c2090bec4d9b + k8s.io/kube-openapi => k8s.io/kube-openapi v0.0.0-20180711000925-0cf8f7e6ed1d + sigs.k8s.io/controller-runtime => sigs.k8s.io/controller-runtime v0.1.10 + sigs.k8s.io/controller-tools => sigs.k8s.io/controller-tools v0.1.11-0.20190411181648-9d55346c2bde +) + +replace github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v0.8.2 +``` +- Run `go mod tidy` to clean up the `go.mod` file. + - In case of any go module loading errors, consult the default [`v0.8.2` go.mod dependencies][v0.8.2-go-mod] scaffolded by the operator-sdk to resolve any differences. You can also view this file by scaffolding a new project with operator-sdk `v0.8.2`. +- Ensure that you can build the project with `operator-sdk build` +- Finally remove `Gopkg.lock`, `Gopkg.toml` and the vendor directory. + +## `v0.9.x` + +- The function `ExposeMetricsPort()` has been replaced with `CreateMetricsService()` [#1560](https://github.com/operator-framework/operator-sdk/pull/1560). + + Replace the following line in `cmd/manager/main.go` + ```Go + _, err = metrics.ExposeMetricsPort(ctx, metricsPort) + ``` + with + ```Go + servicePorts := []v1.ServicePort{ + {Port: metricsPort, Name: metrics.OperatorPortName, Protocol: v1.ProtocolTCP, TargetPort: intstr.IntOrString{Type: intstr.Int, IntVal: metricsPort}}, + {Port: operatorMetricsPort, Name: metrics.CRPortName, Protocol: v1.ProtocolTCP, TargetPort: intstr.IntOrString{Type: intstr.Int, IntVal: operatorMetricsPort}}, + } + + _, err = metrics.CreateMetricsService(ctx, servicePorts) + ``` + +### `dep` + +- Update the SDK constraint in `Gopkg.toml` to version `v0.9.0`, the kubernetes dependencies to `kubernetes-1.13.4` revisions, and the controller-runtime version to `v0.1.12`. + ```TOML + [[override]] + name = "k8s.io/api" + # revision for tag "kubernetes-1.13.4" + revision = "5cb15d34447165a97c76ed5a60e4e99c8a01ecfe" + [[override]] + name = "k8s.io/apiextensions-apiserver" + # revision for tag "kubernetes-1.13.4" + revision = "d002e88f6236312f0289d9d1deab106751718ff0" + [[override]] + name = "k8s.io/apimachinery" + # revision for tag "kubernetes-1.13.4" + revision = "86fb29eff6288413d76bd8506874fddd9fccdff0" + [[override]] + name = "k8s.io/client-go" + # revision for tag "kubernetes-1.13.4" + revision = "b40b2a5939e43f7ffe0028ad67586b7ce50bb675" + [[override]] + name = "github.com/coreos/prometheus-operator" + version = "=v0.29.0" + [[override]] + name = "sigs.k8s.io/controller-runtime" + version = "=v0.1.12" + [[constraint]] + name = "github.com/operator-framework/operator-sdk" + version = "=v0.9.0" + ``` +- Append the contraint for `k8s.io/kube-state-metrics`. + ```TOML + [[override]] + name = "k8s.io/kube-state-metrics" + version = "v1.6.0" + ``` +- Run `dep ensure` to update the vendor directory. + +### modules + +- Update the `replace` directives in your `go.mod` file for the SDK, kubernetes, controller-runtime and kube-state metrics dependencies to the following versions. + ``` + // Pinned to kubernetes-1.13.4 + replace ( + k8s.io/api => k8s.io/api v0.0.0-20190222213804-5cb15d344471 + k8s.io/apiextensions-apiserver => k8s.io/apiextensions-apiserver v0.0.0-20190228180357-d002e88f6236 + k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20190221213512-86fb29eff628 + k8s.io/client-go => k8s.io/client-go v0.0.0-20190228174230-b40b2a5939e4 + ) + replace ( + github.com/coreos/prometheus-operator => github.com/coreos/prometheus-operator v0.29.0 + sigs.k8s.io/controller-runtime => sigs.k8s.io/controller-runtime v0.1.12 + sigs.k8s.io/controller-tools => sigs.k8s.io/controller-tools v0.1.11-0.20190411181648-9d55346c2bde + k8s.io/kube-state-metrics => k8s.io/kube-state-metrics v1.6.0 + ) + replace github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v0.9.0 + ``` +[v0.8.2-go-mod]: https://github.com/operator-framework/operator-sdk/blob/28bd2b0d4fd25aa68e15d928ae09d3c18c3b51da/internal/pkg/scaffold/go_mod.go#L40-L94 +[activating-modules]: https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support +[mercurial]: https://www.mercurial-scm.org/downloads +[migrating-to-modules]: https://github.com/golang/go/wiki/Modules#migrating-to-modules +[modules-wiki]: https://github.com/golang/go/wiki/Modules#migrating-to-modules [print-deps-cli]: ../sdk-cli-reference.md#print-deps [changelog]: ../../CHANGELOG.md [release-notes]: https://github.com/operator-framework/operator-sdk/releases From 7c02e36b89a569785a6ad02777859305c39b06ac Mon Sep 17 00:00:00 2001 From: hasbro17 Date: Mon, 16 Sep 2019 15:52:38 -0700 Subject: [PATCH 2/2] add instructions for the breaking change from regenerating CRDs --- CHANGELOG.md | 2 +- doc/migration/version-upgrade-guide.md | 40 ++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7950f03f0b..807a55b91a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -147,7 +147,7 @@ - Renamed `--docker-build-args` option to `--image-build-args` option for `build` subcommand, because this option can now be shared with other image build tools than docker when `--image-builder` option is specified. ([#1311](https://github.com/operator-framework/operator-sdk/pull/1311)) - Reduces Helm release information in CR status to only the release name and manifest and moves it from `status.conditions` to a new top-level `deployedRelease` field. ([#1309](https://github.com/operator-framework/operator-sdk/pull/1309)) - **WARNING**: Users with active CRs and releases who are upgrading their helm-based operator should upgrade to one based on v0.7.0 before upgrading further. Helm operators based on v0.8.0+ will not seamlessly transition release state to the persistent backend, and will instead uninstall and reinstall all managed releases. -- Go operator CRDs are overwritten when being regenerated by [`operator-sdk generate openapi`](https://github.com/operator-framework/operator-sdk/blob/master/doc/sdk-cli-reference.md#openapi). Users can now rely on `+kubebuilder` annotations in their API code, which provide access to most OpenAPIv3 [validation properties](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schema-object) (the full set will be supported in the near future, see [this PR](https://github.com/kubernetes-sigs/controller-tools/pull/190)) and [other CRD fields](https://book.kubebuilder.io/beyond_basics/generating_crd.html). ([#1278](https://github.com/operator-framework/operator-sdk/pull/1278)) +- Go operator CRDs are overwritten when being regenerated by [`operator-sdk generate openapi`](https://github.com/operator-framework/operator-sdk/blob/master/doc/sdk-cli-reference.md#openapi). Users can now rely on `+kubebuilder` annotations in their API code, which provide access to most OpenAPIv3 [validation properties](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schema-object) (the full set will be supported in the near future, see [this PR](https://github.com/kubernetes-sigs/controller-tools/pull/190)) and [other CRD fields](https://book-v1.book.kubebuilder.io/beyond_basics/generating_crd.html). ([#1278](https://github.com/operator-framework/operator-sdk/pull/1278)) - Use `registry.access.redhat.com/ubi7/ubi-minimal:latest` base image for the Go and Helm operators and scorecard proxy ([#1376](https://github.com/operator-framework/operator-sdk/pull/1376)) - Allow "Owned CRDs Have Resources Listed" scorecard test to pass if the resources section exists diff --git a/doc/migration/version-upgrade-guide.md b/doc/migration/version-upgrade-guide.md index c918cfbef9f..a294b76c87c 100644 --- a/doc/migration/version-upgrade-guide.md +++ b/doc/migration/version-upgrade-guide.md @@ -220,6 +220,45 @@ replace github.com/operator-framework/operator-sdk => github.com/operator-framew - Ensure that you can build the project with `operator-sdk build` - Finally remove `Gopkg.lock`, `Gopkg.toml` and the vendor directory. +### Breaking changes + +Upon updating the project to `v0.8.2` the following breaking changes apply: + +- On running the command `operator-sdk generate openapi`, the CRD manifests at `deploy/crds/__.crd` for all API types will now be regenerated based on their source files `pkg/apis/..._types.go`. So if you have made any manual edits to the default generated CRD manifest, e.g manually written the validation block or specified the naming (`spec.names`), then that information be overwritten when the CRD is regenerated. + + The correct way to specify CRD fields like naming, validation, subresources etc is by using `// +kubebuilder` marker comments. Consult the [legacy kubebuilder documentation][legacy-kubebuilder-doc-crd] to see what CRD fields can be generated via `// +kubebuilder` marker comments. + + **Note:** The version of controller-tools tied to this release does not support settting the `spec.scope` field of the CRD. Use the marker comment `+genclient:nonNamespaced` to set `spec.scope=Cluster` if necessary. See the example below: + ```Go + // MemcachedSpec defines the desired state of Memcached + type MemcachedSpec struct { + // +kubebuilder:validation:Maximum=5 + // +kubebuilder:validation:Minimum=1 + Size int32 `json:"size"` + } + + // MemcachedStatus defines the observed state of Memcached + type MemcachedStatus struct { + // +kubebuilder:validation:MaxItems=5 + // +kubebuilder:validation:MinItems=1 + Nodes []string `json:"nodes"` + } + + // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object + + // Memcached is the Schema for the memcacheds API + // +kubebuilder:subresource:status + // +kubebuilder:resource:shortName="mc" + // +genclient:nonNamespaced + type Memcached struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec MemcachedSpec `json:"spec,omitempty"` + Status MemcachedStatus `json:"status,omitempty"` + } + ``` + ## `v0.9.x` - The function `ExposeMetricsPort()` has been replaced with `CreateMetricsService()` [#1560](https://github.com/operator-framework/operator-sdk/pull/1560). @@ -296,6 +335,7 @@ replace github.com/operator-framework/operator-sdk => github.com/operator-framew replace github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v0.9.0 ``` +[legacy-kubebuilder-doc-crd]: https://book-v1.book.kubebuilder.io/beyond_basics/generating_crd.html [v0.8.2-go-mod]: https://github.com/operator-framework/operator-sdk/blob/28bd2b0d4fd25aa68e15d928ae09d3c18c3b51da/internal/pkg/scaffold/go_mod.go#L40-L94 [activating-modules]: https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support [mercurial]: https://www.mercurial-scm.org/downloads