Documentation request: Cluster-Stack Hosting Format

The cluster-stack-operator has the task to render and apply helmcharts from a GitHub Release assets into a kubernetes cluster. I was not able to find information about the format that the operator expects the GitHub Release to be in (which orga, which repo, which release-name, which release assets it expects and in which format). I have an example CRD to describe my question:

apiVersion: clusterstack.x-k8s.io/v1alpha1
kind: ClusterStack
metadata:
  name: clusterstack-openstack
  namespace: scs-cs
spec:
  provider: openstack # this influences the path where the controller searches for releases
  name: scs           # same here
  kubernetesVersion: "1.27"
  channel: stable
  autoSubscribe: false
  noProvider: true    # do not require dedicated image controller 
  versions:
    - v1

GitHub Orga and Repo

is provided via an env variable to the operator (needs to be documented).

-> also this leads to the issue that it is not possible to consume clusterstacks from two different Repositories, it would be better to reference the github-release-source via the clusterstack CRD

GitHub Release Name

The cluster-stack-operator does not track a git-repo but GitHub Releases (Files downloadable via HTTP and accessible via a JSON-API https://docs.github.com/en/rest/releases?apiVersion=2022-11-28). As far as i found out the release has to have the name "{{.spec.provider}}-{{.spec.name}}-{{.spec.kubernetesVersion}}-{{.spec.versions[x]}}" where x is a valid index of the spec.versions list. Also the dot in the kubernetesVersion has to be replaed with a dash.

GitHub Release assets

Now my findings include a good portion of guessing:

metadata.yaml

Each GitHub release needs a metadata.yaml, below is one that is working

apiVersion: metadata.clusterstack.x-k8s.io/v1alpha1
versions:
  clusterStack: v1
  kubernetes: v1.27.3
  components:
    clusterAddon: v1
    nodeImage: v1

It is not clear to me what this file does, nor why it is needed. But if it is missing the cluster-stack operator throws an error. If a clusterstack wants to bundle different assets (addons and clusterclass for example) would it not be enough to do so via the release as containing structure?

{{.spec.provider}}-{{.spec.name}}-{{.spec.kubernetesVersion}}-cluster-class-vx.tgz

where x is 1 or 2 in the provided examples but i really do not know which vx references which vx. In the example that i use, i used 1 everywhere that works, but it would be great to find out which vx references which. Also i am a bit confused because i found this in the sourcecode: https://github.com/SovereignCloudStack/cluster-stack-operator/blob/main/internal/controller/clusterstackrelease_controller.go#L220 It seems that the operator looks up 4 hardcoded release assets: "metadata.yaml", "cluster-addon-values.yaml", "cluster-addon", "cluster-class". Does that work too? From my point of view that would be an even better solution because all the bundling and versioning already took place on the layer of the release, so i see no need to version it again.

So this issue is half-documentation and and half-guessing, so a lot of it may be wrong, which is why we need correct documentation (if we dont have that already).

Start with the ClusterStack example and the operator configuration for the GitHub organization and repository. Read internal/controller/clusterstackrelease_controller.go around line 220, then verify the release name, metadata.yaml, and cluster-addon/cluster-class asset conventions against the documented GitHub Releases API. Done means documenting the supported format and noting whether repository selection requires a CRD change.