Improve documentation of required non-standard components

[lindhe]

Since there is no documentation available on Rancher's website regarding RKE2 cluster templates, I think this repo should do a better job of documenting the special features.

I'm mainly thinking of questions.yaml, which is a very important file for this project. I find no reference at all as to how it works, so it's currently all trail and error to figure it out. That's no fun.

Furthermore, it should be clarified exactly what Rancher is looking for when a cluster template repo is added to it. As mentioned in #17, the tgz file and index.yaml files are just decoys. But what about the (oddly named) charts/ directory, does it have to have exactly that name for things to work? It's unclear. I continue to poke and prod my way forward to figure out that too eventually, but it would be better if it was documented.

If I've just missed the documentation, please correct me here! :)

Standard components of Helm charts (like the standard fields in the Chart.yaml file and the templates/ directory) need not to be documented here, since they are described in Helm's documentation.

Rancher-specific CRD's like VmwarevsphereConfig or ManagedChart should ideally be documented somewhere, but I don't think this repo is the right place for those objects. Also, one can find information about their specification via kubectl explain, so Rancher's lacking documentation for them is not such a big issue.

[lindhe]

But what about the (https://github.com/rancher/cluster-template-examples/issues/23) charts/ directory, does it have to have exactly that name for things to work?

I tried renaming it to foo and it seems like Rancher still detects it just fine.

[lindhe]

Another thing that should be documented: are the chart annotations required?

https://github.com/rancher/cluster-template-examples/blob/dc5c201c5415c430cdf4bcb6af975f9e516e970b/charts/Chart.yaml#L5-L7

[lindhe]

I found that there is actually documentation for questions.yaml!

https://ranchermanager.docs.rancher.com/v2.7/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps#questionsyml

Also some here:

https://github.com/rancher/rancher/wiki/Understanding-How-Rancher-Configures-Helm-Charts#questionsyaml

[lindhe]

I ran into the following error when deploying a custom chart:

Secret "helm-operation-ncddt" is invalid:
[
  data[foo cluster template-0.35.0.tgz]:
    Invalid value:
      "foo cluster template-0.35.0.tgz":
        a valid config key must consist of alphanumeric characters, '-', '_' or '.'
        (e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+'),

  data[values-foo cluster template-0.35.0.yaml]:
    Invalid value:
      "values-foo cluster template-0.35.0.yaml":
        a valid config key must consist of alphanumeric characters, '-', '_' or '.'
        (e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+')
]

This makes it look like Rancher requires there to be files with certain names. WHY ARE THESE REQUIREMENTS NOT DOCUMENTED? 😠

Relates to #17 and #18.

EDIT: I stand to be corrected. This error is completely my fault. My chart had a name that did not conform to the Helm chart naming standards (see Helm documentation or just run helm lint).

[lindhe]

Please clarify if this is a "Rancher chart".

[lindhe]

Found some details regarding the Helm annotations:

In order to show in the form for creating new clusters, the cluster template's Helm chart must have the catalog.cattle.io/type: cluster-template annotation.

https://ranchermanager.docs.rancher.com/v2.7/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates#creating-a-cluster-from-a-cluster-template

[lindhe]

The README says this:

https://github.com/rancher/cluster-template-examples/blob/dc5c201c5415c430cdf4bcb6af975f9e516e970b/README.md?plain=1#L149

So I'm no wiser as to whether it requires a specific naming scheme or not for the values files.

[k-laughman]

Is this repo still maintained and supported or has SUSE deprecated or given up on this feature? I agree with the items above and I am currently struggling with deciphering the lack of documentation to make this work with vsphere. It is seemingly a cool feature but I have wasted too much time trying to make the examples work and there is a lack of documentation out there that make this consumable by most. I appreciate the links above that were found by @lindhe but I am still unable to spin up a cluster with a template file at the moment.