8000 fix: document having multiple operators installed by shawkins · Pull Request #33448 · keycloak/keycloak · GitHub
[go: up one dir, main page]
Skip to content

fix: document having multiple operators installed #33448

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
vmuzikar merged 3 commits into from
Oct 4, 2024
Merged

fix: document having multiple operators installed #33448

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
434e86c
fix: document having multiple operators installed
shawkins Oct 1, 2024
55a2d39
Update docs/guides/operator/installation.adoc
shawkins Oct 2, 2024
c06f4db
Update docs/guides/operator/installation.adoc
shawkins Oct 2, 2024
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
18 changes: 17 additions & 1 deletion docs/guides/operator/installation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ Make sure you are installing from the *fast* channel:
+
image::configure-operator.png["Configure {project_name} Operator"]

You may select to either have the Operator watch the namespace where it is installed, or to watch a single namespace of your choosing.

<@profile.ifCommunity>
=== Installing by using kubectl without Operator Lifecycle Manager

Expand All @@ -62,7 +64,21 @@ kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resourc
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/{version}/kubernetes/kubernetes.yml
----

Currently the Operator watches only the namespace where the Operator is installed.
The Operator will watch the namespace where it is installed. You may optionally select a namespace with the `-n` option.
</@profile.ifCommunity>

=== Installing Multiple Operators

It is currently not fully supported for the operator to watch multiple or all namespaces. In circumstances where you want to watch multiple namespaces, you can install multiple operators.

If you do this please be aware:

- all Operators share the CRDs (Custom Resource Definitions) as they are installed cluster wide.
- CRD revisions from newer Operator versions won't introduce breaking changes except for the eventual removal of fields that have been well deprecated. Thus newer CRDs are generally backward compatible.
- the CRDs installed last will be the ones in use. This applies to OLM installations as well where the Operator version, that is installed as the last, also installs and overrides the CRDs if they exists in the cluster already.
- older CRDs may not be forwards compatible with new fields used by newer operators. When using OLM it will check if your custom resources are compatible with the CRDs being installed, so the usage of new fields can prevent the simultaneous installation of older operator versions.
@vmuzikar vmuzikar Oct 2, 2024
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
- older CRDs may not be forwards compatible with new fields used by newer operators. When using OLM it will check if your custom resources are compatible with the CRDs being installed, so the usage of new fields can prevent the simultaneous installation of older operator versions.
- older CRDs may not be forwards compatible with new fields used by newer operators. When using OLM it will check if your custom resources are compatible with the CRDs being installed, so the usage of new fields can prevent the simultaneous installation of older operator versions. In that case you first need to install the older Operator version and then the newer one that introduces new fields to the CRDs.

@shawkins shawkins Oct 2, 2024
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@vmuzikar This note is less about the initial install of an older version, and more about where the user already has two versions of the operator and the older one is eligible for a fix release. Any usage of a new CRD field will then block the ability to upgrade the older one. I don't think we have a good / well supported mechanism for that.

@vmuzikar vmuzikar Oct 4, 2024
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Yeah, that's a good point. I didn't realize the upgrades. This behaviour sucks more than I thought. I think the proper solution would be the cluster-wide Operator. As you suggested somewhere else, an alternative might also be to release the CRDs as an individual bundle but that feels more like a potentially confusing workaround to me.

@shawkins shawkins Oct 4, 2024
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Right. We do also have the option of exposing our cluster wide support, but just document it as preview...

@vmuzikar vmuzikar Oct 4, 2024
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@shawkins We'd need to first figure out our support matrix and also how to communicate to users which fields are supported with which Keycloak versions.

@shawkins shawkins Oct 4, 2024 •
edited
Loading
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The cluster wide support doesn't need to have those kinds of problems - if we simply follow the leader and remove the unsupported fields from the CRDs when support is dropped, then the users will be blocked from migrating to that version until they have dealt with the removal. However there needs to be an inbetween release that has both old and new support - which is what we're breaking wrt to hostname v1 and product users.

Obviously that runs afoul of blast radius concerns, but that is quite complex to address.

- fields introduced by newer CRDs will not be supported by older Operators. Older Operator will fail to handle CRs that use such new fields with an error deserializing an unrecognized field.

It is therefore recommended in a multiple Operator install scenario that you keep versions aligned as closely as possible to minimize the potential problems with different versions.

</@tmpl.guide>
0