Documentation Enhancement for Updating of a Restricted Installation

[grant-zietsman]

Proposal

Problem

The current Helm installation documentation defines a restricted installation. However, the upgrade documentation doesn't explicitly state how to upgrade a restricted installation.

For example, Upgrading from ECK 2.0 or later only clarifies how the cluster-wide (global) installation should be upgraded.

If you are using Helm.

helm upgrade elastic-operator elastic/eck-operator -n elastic-system

This will update the ECK installation to the latest binary and update the CRDs and other ECK resources in the cluster.

Specifically, it would help to specify the order of upgrading CRDs and the operator. The most obvious assumption seems to be to upgrade CRDs followed by the operator.

This warning also raises uncertainty about what to expect during the intermediate state where the CRDs release is of a newer version than the operator release (compatibility).

Suggestion

• Clarify how the restricted installation should be upgraded (notably order), especially in light of the version compatibility warning.
• If this is something that can be easily clarified through external documentation, then perhaps a reference could be added. I recognise that I lack familiarity with CRDs (including distribution and versioning).

[pebrc]

@grant-zietsman we can definetely make some improvements in this area.

Some initial thoughts:

• CRD should be upgraded first. Main reason is potentiall addition of new API resources that the new version of the operator might rely on. Absence of those API resources types will otherwise leave the operator in crash loop backoff until the CRDs are upgraded
• for restricted installation the upgrade documentation could be amended to mention that the CRD upgrade needs to be done by a cluster admin while the operator upgrade can be done by any user with sufficient privileges in the target namespace (analoguous to the initial installation)

[grant-zietsman]

@pebrc thanks for your feedback. Both of these points would be a helpful clarification in the documentation.