API conventions: CRD columns: status vs intent

[sbueringer]

This issue is based on a discussion on: #5304 (comment)

do we may be want to recommend printing status vs intent or do we want to set any convention?
@enxebre

Context: Afaik we cannot have columns in CRDs based on multiple values, e.g. Kubernetes Pod 4/5 containers are ready.
I think the only thing we can do is try to avoid misunderstandings if something is spec or status through good column names. Let's see what we currently have:

I think for a lot of columns the distinction doesn't matter (or is already obvious): e.g.: Cluster, Age, NodeName
It seems like our replica columns are also easy to understand: Replicas is .spec.Replicas and all others are from status, e.g. Ready, Updated, Unavailable
Similar for our "object lifecycle flags", like: Initialized, API Server Available
I think the main problem is when, based on the column name, the column could be spec or status and if the status could be different from spec until the object is entirely reconciled. For me that's mostly Version (although the MHC fields and columns could also need some improvement => #5291).

Regarding Version: One idea to clear this up would be to rename the column in cases where it's not clear to something like SPEC_VERSION or DESIRED_VERSION (I don't have good ideas :)). I think this would apply to Cluster and MachineDeployment (Machines only ever have one version and afaik MachineSets too (?)).

But back to topic, I'm not entirely sure what the convention could or should be. I think for me it would be let's try to make clear through the column name if something is spec or status for fields where there could be misunderstandings.
@sbueringer

I would add the following: (next to the other Note)
NOTE: In cases where it's not clear if the column field is part of spec or status, we SHOULD try to make it obvious by choosing the column name accordingly.
Regarding VERSION. Should we make a change to the VERSION column of Cluster and MachineDeployment before the v1beta1 release? As mentioned, my best idea for another name is probably DESIRED_VERSION (alternative SPEC_VERSION).
@sbueringer

AFAIK we currently are reporting spec, but I'm not sure this is out of chance or intentional.
@fabriziopandini

So there are the following questsions:

1. Do we want to add the note I suggested above to the API conventions
2. Do we want to rename the VERSION column in Cluster and MachineDeployment to make it more clear that the version is just the spec and not the status

/kind feature

[sbueringer]

/cc @enxebre
/area api

[vincepri]

Cluster and MachineDeployment could share some of the code from KCP to have a version in Status based on what's running on the cluster.

/milestone v1.0

[vincepri]

/kind cleanup

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[fabriziopandini]

/remove-lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[fabriziopandini]

/lifecycle frozen
/kind api-change

To re-consider for the next API version

[fabriziopandini]

/milestone Next

[fabriziopandini]

/triage accepted

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[sbueringer]

/triage accepted

[fabriziopandini]

/priority important-longterm

[sbueringer]

A solution to this is proposed in #10897

/close

[k8s-ci-robot]

@sbueringer: Closing this issue.

In response to this:

A solution to this is proposed in #10897

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.