Skip to content

Commit f419ad3

Browse files
Eric Stroczynskihasbro17
Eric Stroczynski
authored and
hasbro17
committed
doc/migration/version-upgrade-guide.md: v0.10 and v0.11 upgrade guides (#1997)
1 parent 8ecad41 commit f419ad3

File tree

2 files changed

+150
-8
lines changed

2 files changed

+150
-8
lines changed

‎doc/migration/version-upgrade-guide.md

Lines changed: 148 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ replace (
215215
216216
replace github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v0.8.2
217217
```
218-
- Run `go mod tidy` to clean up the `go.mod` file.
218+
- Run `go mod tidy` to clean up the `go.mod` file.
219219
- 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`.
220220
- Ensure that you can build the project with `operator-sdk build`
221221
- Finally remove `Gopkg.lock`, `Gopkg.toml` and the vendor directory.
@@ -224,7 +224,7 @@ replace github.com/operator-framework/operator-sdk => github.com/operator-framew
224224

225225
Upon updating the project to `v0.8.2` the following breaking changes apply:
226226

227-
- On running the command `operator-sdk generate openapi`, the CRD manifests at `deploy/crds/<group>_<version>_<kind>.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.
227+
- On running the command `operator-sdk generate openapi`, the CRD manifests at `deploy/crds/<group>_<version>_<kind>.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.
228228

229229
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.
230230

@@ -261,8 +261,8 @@ Upon updating the project to `v0.8.2` the following breaking changes apply:
261261

262262
## `v0.9.x`
263263

264-
- The function `ExposeMetricsPort()` has been replaced with `CreateMetricsService()` [#1560](https://github.com/operator-framework/operator-sdk/pull/1560).
265-
264+
- The function `ExposeMetricsPort()` has been replaced with `CreateMetricsService()` [#1560](https://github.com/operator-framework/operator-sdk/pull/1560).
265+
266266
Replace the following line in `cmd/manager/main.go`
267267
```Go
268268
_, err = metrics.ExposeMetricsPort(ctx, metricsPort)
@@ -335,6 +335,148 @@ Upon updating the project to `v0.8.2` the following breaking changes apply:
335335
replace github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v0.9.0
336336
```
337337

338+
## `v0.10.x`
339+
340+
- The scorecard configuration format for the `operator-sdk scorecard` command has changed. See [`doc/test-framework/scorecard`](../test-framework/scorecard.md) for more info.
341+
- The CSV config field `role-path` is now `role-paths` and takes a list of strings.
342+
Replace:
343+
```yaml
344+
role-path: path/to/role.yaml
345+
```
346+
with:
347+
```yaml
348+
role-paths:
349+
- path/to/role.yaml
350+
```
351+
352+
### modules
353+
354+
- Ensure the the following `replace` directives are present in your `go.mod` file:
355+
```
356+
replace (
357+
github.com/coreos/prometheus-operator => github.com/coreos/prometheus-operator v0.29.0
358+
// Pinned to v2.9.2 (kubernetes-1.13.1) so https://proxy.golang.org can
359+
// resolve it correctly.
360+
github.com/prometheus/prometheus => github.com/prometheus/prometheus v0.0.0-20190424153033-d3245f150225
361+
k8s.io/kube-state-metrics => k8s.io/kube-state-metrics v1.6.0
362+
sigs.k8s.io/controller-runtime => sigs.k8s.io/controller-runtime v0.1.12
363+
sigs.k8s.io/controller-tools => sigs.k8s.io/controller-tools v0.1.11-0.20190411181648-9d55346c2bde
364+
)
365+
366+
replace github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v0.10.0
367+
```
368+
369+
## `v0.11.x`
370+
371+
**NOTE:** this version uses Kubernetes v1.14.x and controller-runtime v0.2.x, both of which have breaking API changes. See the [changelog][changelog] for more details.
372+
373+
### dep
374+
375+
- Remove the `required = [ ... ]` section and comment from the top of your `Gopkg.toml` file.
376+
- Update the following overrides in `Gopkg.toml`:
377+
```TOML
378+
[[override]]
379+
name = "k8s.io/api"
380+
# revision for tag "kubernetes-1.14.1"
381+
revision = "6e4e0e4f393bf5e8bbff570acd13217aa5a770cd"
382+
[[override]]
383+
name = "k8s.io/apiextensions-apiserver"
384+
# revision for tag "kubernetes-1.14.1"
385+
revision = "727a075fdec8319bf095330e344b3ccc668abc73"
386+
[[override]]
387+
name = "k8s.io/apimachinery"
388+
# revision for tag "kubernetes-1.14.1"
389+
revision = "6a84e37a896db9780c75367af8d2ed2bb944022e"
390+
[[override]]
391+
name = "k8s.io/client-go"
392+
# revision for tag "kubernetes-1.14.1"
393+
revision = "1a26190bd76a9017e289958b9fba936430aa3704"
394+
[[override]]
395+
name = "github.com/coreos/prometheus-operator"
396+
version = "=v0.31.1"
397+
[[override]]
398+
name = "sigs.k8s.io/controller-runtime"
399+
version = "=v0.2.2"
400+
[[constraint]]
401+
name = "github.com/operator-framework/operator-sdk"
402+
version = "=v0.11.0"
403+
```
404+
- Append an override for `gopkg.in/fsnotify.v1`, which is required when resolving controller-runtime dependencies:
405+
```TOML
406+
[[override]]
407+
name = "gopkg.in/fsnotify.v1"
408+
source = "https://github.com/fsnotify/fsnotify.git"
409+
```
410+
- Remove the `k8s.io/kube-state-metrics` override.
411+
- Run `dep ensure` to update the vendor directory.
412+
413+
### modules
414+
415+
- Ensure the the following `replace` directives are present in your `go.mod` file:
416+
```
417+
// Pinned to kubernetes-1.14.1
418+
replace (
419+
k8s.io/api => k8s.io/api kubernetes-1.14.1
420+
k8s.io/apiextensions-apiserver => k8s.io/apiextensions-apiserver kubernetes-1.14.1
421+
k8s.io/apimachinery => k8s.io/apimachinery kubernetes-1.14.1
422+
k8s.io/client-go => k8s.io/client-go kubernetes-1.14.1
423+
k8s.io/cloud-provider => k8s.io/cloud-provider kubernetes-1.14.1
424+
)
425+
426+
replace (
427+
github.com/coreos/prometheus-operator => github.com/coreos/prometheus-operator v0.31.1
428+
// Pinned to v2.10.0 (kubernetes-1.14.1) so https://proxy.golang.org can
429+
// resolve it correctly.
430+
github.com/prometheus/prometheus => github.com/prometheus/prometheus d20e84d0fb64aff2f62a977adc8cfb656da4e286
431+
)
432+
433+
replace github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v0.11.0
434+
```
435+
436+
### Import updates
437+
438+
- Replace import `sigs.k8s.io/controller-runtime/pkg/runtime/scheme` with `sigs.k8s.io/controller-runtime/pkg/scheme` in:
439+
- `./pkg/apis/<group>/<version>/register.go`
440+
- Replace import `sigs.k8s.io/controller-runtime/pkg/runtime/log` with `sigs.k8s.io/controller-runtime/pkg/log` in:
441+
- `cmd/manager/main.go`
442+
- `./pkg/controller/<kind>/<kind>_controller.go`
443+
- Replace import `sigs.k8s.io/controller-runtime/pkg/runtime/signals` with `sigs.k8s.io/controller-runtime/pkg/manager/signals` in:
444+
- `cmd/manager/main.go`
445+
446+
### controller-runtime API updates
447+
448+
All method signatures for [`sigs.k8s.io/controller-runtime/pkg/client.Client`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L104) and [`sigs.k8s.io/controller-runtime/pkg/client.StatusWriter`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L91) (except for `Client.Get()`) have been updated. Each now uses a variadic option interface parameter typed for each method.
449+
- `Client.List(ctx context.Context, opts *client.ListOptions, list runtime.Object) error` is now [`Client.List(ctx context.Context, list runtime.Object, opts ...client.ListOption) error`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L61).
450+
Replace:
451+
```go
452+
listOpts := &client.ListOptions{}
453+
listOpts.InNamespace("namespace")
454+
err = r.client.List(context.TODO(), listOps, podList)
455+
```
456+
with:
457+
```go
458+
listOpts := []client.ListOption{
459+
client.InNamespace("namespace"),
460+
}
461+
err = r.client.List(context.TODO(), podList, listOpts...)
462+
```
463+
- `Client.Create(ctx context.Context, obj runtime.Object) error` is now [`Client.Create(ctx context.Context, obj runtime.Object, opts ...client.CreateOption) error`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L67). No updates need to be made. See the [client doc][client-doc] for a discussion of `client.CreateOption`.
464+
- `Client.Update(ctx context.Context, obj runtime.Object) error` is now [`Client.Update(ctx context.Context, obj runtime.Object, opts ...client.UpdateOption) error`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L74). No updates need to be made. See the [client doc][client-doc] for a discussion of `client.UpdateOption`.
465+
- `Client.Delete(ctx context.Context, obj runtime.Object, opts ...DeleteOptionFunc) error` is now [`Client.Delete(ctx context.Context, obj runtime.Object, opts ...DeleteOption) error`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L70). Although the option interface has changed, the way each `client.DeleteOption` is created is the same as before. No updates need to be made. See the [client doc][client-doc] for a discussion of `client.DeleteOption`.
466+
- `StatusWriter.Update(ctx context.Context, obj runtime.Object) error` is now [`Update(ctx context.Context, obj runtime.Object, opts ...UpdateOption) error`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L95). No updates need to be made. See the [client doc][client-doc] for a discussion of `client.UpdateOption`.
467+
468+
### Operator SDK updates
469+
470+
- [`pkg/test.FrameworkClient`](https://github.com/operator-framework/operator-sdk/blob/947a464/pkg/test/client.go#L33) `List()` and `Delete()` method invocations should be updated to match those of `Client.List()` and `Client.Delete()`, described above.
471+
- The annotation to assign a scope to your CRD has changed. For the following changes, note that `<resource>` is the plural lower-case CRD Kind found at `spec.names.plural`.
472+
- For `Namespaced`-scoped operators, add a `+kubebuilder:resource:path=<resource>,scope=Namespaced` comment above your kind type in `pkg/apis/<group>/<version>/<kind>_types.go`.
473+
- For `Cluster`-scoped operators, replace the `+genclient:nonNamespaced` comment above your kind type in `pkg/apis/<group>/<version>/<kind>_types.go` with `+kubebuilder:resource:path=<resource>,scope=Cluster`.
474+
- CRD file names now have the form `<full group>_<resource>_crd.yaml`, and CRD file names now have the form `<full group>_<version>_<kind>_cr.yaml`. `<full group>` is the full group name of your CRD found at `spec.group`, and `<resource>` is the plural lower-case CRD Kind found at `spec.names.plural`. To migrate:
475+
- Run `operator-sdk generate openapi`. CRD manifest files with new names containing versioned validation and subresource blocks will be generated.
476+
- Delete the old CRD manifest files.
477+
- Rename CR manifest file names from `<group>_<version>_<kind>_cr.yaml` to `<full group>_<version>_<kind>_cr.yaml`.
478+
479+
338480
[legacy-kubebuilder-doc-crd]: https://book-v1.book.kubebuilder.io/beyond_basics/generating_crd.html
339481
[v0.8.2-go-mod]: https://github.com/operator-framework/operator-sdk/blob/28bd2b0d4fd25aa68e15d928ae09d3c18c3b51da/internal/pkg/scaffold/go_mod.go#L40-L94
340482
[activating-modules]: https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support
@@ -345,4 +487,5 @@ Upon updating the project to `v0.8.2` the following breaking changes apply:
345487
[changelog]: ../../CHANGELOG.md
346488
[release-notes]: https://github.com/operator-framework/operator-sdk/releases
347489
[v0.1.0-migration-guide]: ./v0.1.0-migration-guide.md
348-
[manifest-format]: https://github.com/operator-framework/operator-registry#manifest-format
490+
[manifest-format]: https://github.com/operator-framework/operator-registry#manifest-format
491+
[client-doc]: ../user/client.md

‎doc/user/unit-testing.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,9 @@ func TestMemcachedController(t *testing.T) {
5252
cl := fake.NewFakeClient(objs...)
5353

5454
// List Memcached objects filtering by labels
55+
opt := client.MatchingLabels(map[string]string{"label-key": "label-value"})
5556
memcachedList := &cachev1alpha1.MemcachedList{}
56-
err := cl.List(context.TODO(), client.MatchingLabels(map[string]string{
57-
"label-key": "label-value",
58-
}), memcachedList)
57+
err := cl.List(context.TODO(), memcachedList, opt)
5958
if err != nil {
6059
t.Fatalf("list memcached: (%v)", err)
6160
}

0 commit comments

Comments
 (0)