Is comment line just above document start `---` prohibited on YAML?

General Discussions
1

I have encountered some strange behavior on kubeadm init with ClusterConfiguration YAML.
As I have no idea whether this is a kind of bug in kubeadm or just a YAML formatting spec, I’m posting here to get your thoughts.

Details

This cluster-config.yaml works perfectly.

---
apiVersion: kubeadm.k8s.io/v1beta2
kind: ClusterConfiguration
kubernetesVersion: v1.26.3
apiServer:
  extraArgs:
    feature-gates: HPAContainerMetrics=true
networking:
  podSubnet: "10.244.0.0/16"

but adding comment line on top of document start ---:

# some comment
---
apiVersion: kubeadm.k8s.io/v1beta2
kind: ClusterConfiguration
kubernetesVersion: v1.26.3
apiServer:
  extraArgs:
    feature-gates: HPAContainerMetrics=true
networking:
  podSubnet: "10.244.0.0/16"

makes kubeadm output an error

$ kubeadm init --config cluster-config.yaml --v=5
I0324 12:24:42.883760  116435 initconfiguration.go:254] loading configuration from "cluster-config.yaml"
invalid configuration for GroupVersionKind /, Kind=: kind and apiVersion is mandatory information that must be specified
k8s.io/kubernetes/cmd/kubeadm/app/util.SplitYAMLDocuments
        cmd/kubeadm/app/util/marshal.go:105
k8s.io/kubernetes/cmd/kubeadm/app/util/config.BytesToInitConfiguration
        cmd/kubeadm/app/util/config/initconfiguration.go:284
k8s.io/kubernetes/cmd/kubeadm/app/util/config.LoadInitConfigurationFromFile
        cmd/kubeadm/app/util/config/initconfiguration.go:261
k8s.io/kubernetes/cmd/kubeadm/app/util/config.LoadOrDefaultInitConfiguration
        cmd/kubeadm/app/util/config/initconfiguration.go:273
k8s.io/kubernetes/cmd/kubeadm/app/cmd.newInitData
        cmd/kubeadm/app/cmd/init.go:300
k8s.io/kubernetes/cmd/kubeadm/app/cmd.newCmdInit.func3
        cmd/kubeadm/app/cmd/init.go:153
k8s.io/kubernetes/cmd/kubeadm/app/cmd/phases/workflow.(*Runner).InitData
        cmd/kubeadm/app/cmd/phases/workflow/runner.go:183
k8s.io/kubernetes/cmd/kubeadm/app/cmd.newCmdInit.func1
        cmd/kubeadm/app/cmd/init.go:104
github.com/spf13/cobra.(*Command).execute
        vendor/github.com/spf13/cobra/command.go:916
github.com/spf13/cobra.(*Command).ExecuteC
        vendor/github.com/spf13/cobra/command.go:1040
github.com/spf13/cobra.(*Command).Execute
        vendor/github.com/spf13/cobra/command.go:968
k8s.io/kubernetes/cmd/kubeadm/app.Run
        cmd/kubeadm/app/kubeadm.go:50
main.main
        cmd/kubeadm/kubeadm.go:25
runtime.main
        /usr/local/go/src/runtime/proc.go:250
runtime.goexit
        /usr/local/go/src/runtime/asm_amd64.s:1594

Both v1beta2 and v1beta3 seem to have the same behavior.

Is this a bug or just a YAML spec?

Cluster information:

Kubernetes version: v1.26.3
Cloud being used: GCE
Installation method: kubeadm
Host OS: Debian 11.6
CNI and version: flannel v0.21.4
CRI and version: containerd 1.7.0

2

This is a bit of an odd case, semantically --- is the marker for the end of a yaml document, allowing you to have multiple yaml configurations in one file.

I would guess the parser here is able to ignore the case where there are zero bytes before end of document. With the comment case it must be trying to find a valid configuration, and this isn’t a valid configuration document because it doesn’t have any kind or apiVersion.

Removing the --- line is probably the most reasonable thing to do. It’s meant to mark the end of one document before the beginning of another.

https://yaml.org/spec/1.2.2/#912-document-markers