crossplane / crossplane/crossplane

Crossplane upgrades hit CRD versioning issues too easily

Open
#6,864 4 comments 0 reactions 0 assignees View on GitHub
enhancement reliability roadmap
Dominant language
Go
Stars
12.1k
Forks
1.3k
Avg merge
1d 6h
Merged PRs (30d)
46

Description

### What problem are you facing?

It is far too easy to upgrade Crossplane and run into an issue with CRD versioning. One concrete way to visualize this is the following query that shows how many issues we have had over the years for `must appear in spec.versions`:

https://github.com/crossplane/crossplane/issues?q=is%3Aissue%20%22must%20appear%20in%20spec.versions%22

We have approached this with a couple improvements so far:

* [API promotion guide](https://github.com/crossplane/crossplane/blob/main/contributing/guide-api-promotion.md) for developers so the project does the right things for CRD versioning across versions of the Crossplane software
* [Documentation warning](https://docs.crossplane.io/latest/guides/upgrade-crossplane/) to always upgrade Crossplane `one minor version at a time`

However, this isn't enough and it's still too easy to run into problems.

### How could Crossplane help solve your problem?

We need further guardrails and/or support so that Crossplane adopters don't upgrade and hit a fatal error because of improper CRD versioning. This could be something like upgrade hooks that forcefully prevent upgrades for more than one minor version of a time, but perhaps there are better ideas.

Contributor guide

Open the contributing guide

Research direction

Start by reading contributing/guide-api-promotion.md and the upgrade guidance linked in the issue, then review the reported “must appear in spec.versions” failures. The issue does not select an implementation, so first define the guardrail and upgrade scenarios to support. Done would be a concrete, validated way to prevent or clearly detect unsafe multi-minor upgrades.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes
Domain
devops, infrastructure
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.