Clarify files to edit & not edit to ease upgrade

[JohnStrunk]

Type of question

Are you asking about community best practices, how to implement a specific feature, or about general context and help around the operator-sdk?

Best practices

Question

In reading the docs, it's clear that the operator developer should modify the *_types.go and *_controller.go files for their CRDs. What isn't as clear is what other files should or should not be modified.

Presumably as the SDK evolves, the template code that is created by operator-sdk new will change. What are good recommendations for operator developers to keep in mind so that it remains easy to upgrade the SDK? For example:

• Should we consider all *.go files to be owned by the SDK and avoid modifying them (with the exception of the two mentioned above)?
• What about the Dockerfile and the various yamls?

[joelanford]

For reference here's what a simple go operator project looks like with a single added api and controller.

$ tree ./ -I vendor
./
├── build
│   └── Dockerfile
├── cmd
│   └── manager
│       └── main.go
├── deploy
│   ├── crds
│   │   ├── example_v1alpha1_app_crd.yaml
│   │   └── example_v1alpha1_app_cr.yaml
│   ├── operator.yaml
│   ├── role_binding.yaml
│   ├── role.yaml
│   └── service_account.yaml
├── Gopkg.lock
├── Gopkg.toml
├── pkg
│   ├── apis
│   │   ├── addtoscheme_example_v1alpha1.go
│   │   ├── apis.go
│   │   └── example
│   │       └── v1alpha1
│   │           ├── app_types.go
│   │           ├── doc.go
│   │           ├── register.go
│   │           └── zz_generated.deepcopy.go
│   └── controller
│       ├── add_app.go
│       ├── app
│       │   └── app_controller.go
│       └── controller.go
└── version
    └── version.go

Since the SDK is still alpha, it's hard to answer this question with a strong guarantee.

To answer your specific questions:

Should we consider all *.go files to be owned by the SDK and avoid modifying them (with the exception of the two mentioned above)?

Using the example about, I think the following are expected to be changed by an operator developer:

• cmd/manager/main.go
• pkg/apis/example/v1alpha1/app_types.go
• pkg/apis/example/v1alpha1/doc.go
• pkg/apis/example/v1alpha1/zz_generated.deepcopy.go
• pkg/controller/app/app_controller.go
• version/version.go

Outside of those, do you have a use case for changing the other *.go files?

What about the Dockerfile and the various yamls?

The SDK is primarily concerned that these files exist in their scaffolded location and that they are valid syntactically.

For deploy/role.yaml, the SDK will automatically add new rules as new APIs and CRDs are added. But if your operator needs different permissions than what are in the default role.yaml, it should be okay to update it to add or remove them.

For the Dockerfile, operator-sdk build builds your operator image using ./build/Dockerfile. So it needs to be there. However, operator developers can modify it to install dependencies, run setup commands, etc. There are some changes in the works to be aware of though (#782 and #431)

[JohnStrunk]

Thanks for the reply. I don't currently have a good reason to change the other files.
My big concern is getting a feel for what it will mean to "upgrade" the sdk version and trying to make sure merging changes into the operator is as simple as possible.

I think this is sufficient for my purposes.

[estroz]

@JohnStrunk once we reach non-alpha status, only major version changes, ex. v1.x.x -> v2.x.x, will break compatibility with old operator projects. Because we're in alpha, changes to operator project file structure can still occur with minor version changes, ex. v0.1.x -> v0.2.x. We will be sure to make documentation available for migration when we make breaking changes, like we did for v0.0.x -> v0.1.0. Hopefully that helps. If you're satisfied I'll close this issue.

[JohnStrunk]

That works for me. My takeaway is...

Non-breaking upgrades amount to:

1. using the latest sdk release
2. running print-deps to update Gopkg

Breaking upgrades will have specific documentation, but in general, I can expect to re-run operator-sdk new and merge in my current operator code.

Assuming this is approximately correct, I'm good w/ closing this.