Cluster-api: Define required provider-specific metadata location and format

[detiber]

/kind feature

Describe the solution you'd like
Currently we don't have any way to determine which provider versions are compatible with which versions of cluster-api, which bootstrap providers they support, or even what the latest versions of each are. I propose that we formalize a location and format for metadata that can be used for this purpose.

We should also formalize the process of releasing pre-generated "provider components" for each "type" of provider as part of a release, so that those can be more easily referenced by other providers and/or higher level cluster-api oriented tooling.

proposed metadata file name: /metadata.yaml
proposed format (v1alpha1 used only for example purposes to show multiple defined versions, and bootstrap provider info would only be required for an "infrastructure" provider):

---
providerType: infrastructure
apiSupport:
  v1alpha1:
    releaseSeries: ["v0.2", "v0.3"]
  v1alpha2:
    releaseSeries: ["v0.4"]
releaseSeries:
  "v0.2":
    clusterApiCompatibleSeries: ["v0.1"]
    latestRelease: "v0.2.3"
  "v0.3":
    clusterApiCompatibleSeries: ["v0.1"]
    latestRelease: "v0.3.9"
  "v0.4":
    clusterApiCompatibleSeries: ["v0.2"]
    bootstrapProvidersSupported:
    - name: "cluster-api-bootstrap-provider-kubeadm"
      supportedVersionSeries: ["v0.1"]
    latestRelease: "v0.4.0"

For the published "provider components", my proposal is to name the file "bootstrap-components.yaml" for bootstrap providers, "infrastructure-components.yaml" for infrastructure providers, and "cluster-api-components.yaml" for the core cluster-api components.

[vincepri]

I'm not sure if we should include the latestRelease as part of this manifest, unless it's something that gets automatically synced and doesn't require frequent user intervention. Also does this assume GitHub?

[detiber]

I'm not sure if we should include the latestRelease as part of this manifest, unless it's something that gets automatically synced and doesn't require frequent user intervention.

It would probably require some manual intervention on the part of each project, but it's better than having to use git to parse and sort tags.

Also does this assume GitHub?

I think that is a safe assumption to make for now, we could always provide a way to specify a download url pattern to use (defaulting to the GitHub pattern) at a later date if we need to.

[timothysc]

IMO this should be in the .next milestone, the API is cut and some of this would require api-changes.

[ncdc]

Agree
/milestone Next

[vincepri]

/area clusterctl

[vincepri]

/assign @fabriziopandini @timothysc @akutz

[fabriziopandini]

I'm giving a try at this, and I would like to use a simple API (without nesting).

The current working assumption is :

each provider should publish its own "metadata.yaml", with the description of its own release series
e.g. for CAPA

apiVersion: v1alpha3
kind: ReleaseSeriesList
items:
- major: 0
  minor: 4
  clusterAPIVersion: v1alpha2
- major: 0
  minor: 3
  clusterAPIVersion: v1alpha1

Glossary:
ReleaseSeries --> An object that links a release serie (Major, Minor) to a Cluster API - API version
clusterAPIVersion --> The Cluster API - API version

Then clusterctl will combine the "metadata.yaml" for all the provider in a cluster and ensure everything is at the same clusterAPIVersion

@akutz @ncdc @vincepri @detiber @timothysc
opinions?

[detiber]

@fabriziopandini I think that is likely fine for now, however at some point we might have to deal with behavioral changes that might not be tied to an API version, but rather the binary and/or image version of CAPI. We can always cross that bridge when we get there, though.

[akutz]

Hi @fabriziopandini,

I'm curious what decisions are being made based on this information? The location of infra components? Building some path like $HOME/.clusterapi/0/4/v1alpha2?

[vincepri]

I'm wondering given the simplicity of the solution proposed if we can actually hardcode the known providers in clusterctl instead? And provide configuration options for others.

[fabriziopandini]

@akutz that information is required for:

• clusterctl init --> check if the User is going to install a set of providers/versions that can work together (if CAPI v1alpha3, also the selected CAPV version MUST work with v1alpha3)
• clusterctl upgrade plan --> given the installed providers all in v1alpha3, suggest the next available versions compatible with v1alpha3 or propose a consistent set of versions for the upgrade to v1alpha4 (when it will be available)

BTW I'm trying to create a demo to share ASAP, but if you want we can chat about it

[akutz]

Don’t let me keep you from a demo. I just didn’t feel I could answer your question without understanding what you were tying to accomplish.

[akutz]

I wouldn’t hardcode providers. Seems like the anthesis of what the point of all this is.

I’d be okay with clusterctl shipping with a default config file that included known providers, and if a provider defined their own metadata files then those are preferred.

[akutz]

If the metadata file is specific to clusterctl, then why not call it clusterctl.yaml and have each provider supply the info (and possibly more) in that?

[fabriziopandini]

why not call it clusterctl.yaml

Clusterctl is a consumer of this info, but nothing prevents other tools to use them as well, so I prefer metadata.yaml

have each provider supply the info (and possibly more) in that?

@akutz have in in mind some specific use case for "more"?