Skip to content

doc/migration: add sections for v0.8.x and v0.9.x #1891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 29, 2019
Merged

doc/migration: add sections for v0.8.x and v0.9.x #1891

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e137da3
doc/migration: add sections for v0.8.x and v0.9.x
hasbro17 Sep 9, 2019
7c02e36
add instructions for the breaking change from regenerating CRDs
hasbro17 Sep 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
173 changes: 172 additions & 1 deletion doc/migration/version-upgrade-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -168,8 +168,179 @@ 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Ensure that you have Go 1.12+ and [Mercurial][mercurial] 3.9+ installed.
- Ensure that you have Go 1.12+ (I do not think that The Mercurial is required at all)

Copy link
Contributor

@camilamacedo86 camilamacedo86 Sep 9, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, is required to:

  • create the group.go
  • Ensure in the api files ( for the open API )

For the Object Struct

// +k8s:openapi-gen=true
// +kubebuilder:subresource:status//

For the Object Status and Spec

// +k8s:openapi-gen=true
  • Re-run the gen-code commands as well.
	operator-sdk generate k8s
	operator-sdk generate openapi

At least I need to check it too in the projects, so I'd recommend checking these points as well.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding group.go isn't really necessary since it's not a breaking change. It only suppresses a warning from gengo when running the gen-code commands.

But you're right on the second point: I should highlight the need for +kubebuilder tags now that CRD manifests are overwritten in v0.8.x and will remove any manual edits made by users to the CRD.
From the CHANGELOG:

- Go operator CRDs are overwritten when being regenerated by operator-sdk generate openapi. 
Users can now rely on +kubebuilder annotations in their API code, which provide access to most OpenAPIv3
 validation properties (the full set will be supported in the near future, see this PR) and other CRD fields. (#1278)

This probably should have been marked as breaking change to begin with. Well spotted.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also I can't recall if I had to setup mercurial when I used Go modules but it's definitely part of our pre-reqs:
https://github.com/operator-framework/operator-sdk#prerequisites

Although it might be one of git or mercurial:
https://github.com/golang/go/wiki/GoGetTools

I'll need to double check and remove it from the SDK's pre-reqs if that's not the case.

Copy link
Member

@joelanford joelanford Sep 19, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fairly sure mercurial was/is required. I'm pretty sure some transitive dependency somewhere comes from a mercurial repo.

Also, just be careful about which kubebuilder tags are mentioned about being needed/supported. We won't switch to controller-tools 0.2.x until the next release, so tags like +kubebuilder:subresource:status that were added in controller-tools 0.2.0 should not be mentioned.

EDIT: Nevermind - looks like you have that covered in line 229 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I've linked to the legacy kubebuilder docs to show that not all marker comments are supported for the controller-tools version tied SDK release v0.8.2.

But // +kubebuilder:subresource:status specifically is supported pre controller-tools v0.2.0 so I've kept that in the example.

Copy link
Contributor

@camilamacedo86 camilamacedo86 Sep 20, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HI @joelanford, @hasbro17

I just would like to share that I have NO mercurial installed locally and all are working. Maybe it is specific to some kind of operator so. Also, I could not find anything in the code over it. If it is there let's keep but if possible, I'd like to understand to learn where it has been used.

$ mercurial
-bash: mercurial: command not found

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@camilamacedo86 The mercurial command is hg, so check if you have that.

Here's the original issue: #1681

Looks like it affected 0.9 at least, not sure about 0.8 or 0.10.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I lot of shame now :-P Yes, I have it! All explained tks for the patient with me.

- 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.
Copy link
Contributor

@camilamacedo86 camilamacedo86 Sep 20, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WDYT about we tell to the user's use the make commands in order to add use the GOPROXY? See

operator-sdk/Makefile

Line 31 in 8bdd7c5

export GOPROXY?=https://proxy.golang.org/

Suggested change
- Run `go mod tidy` to clean up the `go.mod` file.
- Run `make tidy` to clean up the `go.mod` file.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Users don't have a Makefile in their projects, so make tidy wouldn't apply to them. That's just a convenience make target we have for the SDK repo.

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

### 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/<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.

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).

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 (
Copy link
Contributor

@camilamacedo86 camilamacedo86 Sep 16, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May it needs to be updated as #1899

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My first thought is probably not.
There are other ways to solve this problem, e.g using the proxy cache by setting GOPROXY=https://proxy.golang.org.

I don't want to add it to the guide since this isn't an issue specifically with the SDK and something that's easily if you run into the issue.

Although it looks like https://status.apache.org/ is down quite often so maybe if we merge #1899 I can do a follow up.

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

[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
[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
Expand Down