✨ Add bootCommands to cloud-init file generation

bootstrap/kubeadm/api/v1beta1/kubeadmconfig_types.go

@@ -75,11 +75,20 @@ type KubeadmConfigSpec struct {
 	// +optional
 	Mounts []MountPoints `json:"mounts,omitempty"`
 
-	// preKubeadmCommands specifies extra commands to run before kubeadm runs
+	// bootCommands specifies extra commands to run very early in the boot process via the cloud-init bootcmd
+	// module. This is typically run in the cloud-init.service systemd unit. This has no effect in Ignition.
+	// +optional
+	BootCommands []BootCommand `json:"bootCommands,omitempty"`
+
+	// preKubeadmCommands specifies extra commands to run before kubeadm runs.
+	// With cloud-init, this is prepended to the runcmd module configuration, and is typically executed in
+	// the cloud-final.service systemd unit. In Ignition, this is prepended to /etc/kubeadm.sh.
 	// +optional
 	PreKubeadmCommands []string `json:"preKubeadmCommands,omitempty"`
 
-	// postKubeadmCommands specifies extra commands to run after kubeadm runs
+	// postKubeadmCommands specifies extra commands to run after kubeadm runs.
+	// With cloud-init, this is appended to the runcmd module configuration, and is typically executed in
+	// the cloud-final.service systemd unit. In Ignition, this is appended to /etc/kubeadm.sh.
 	// +optional
 	PostKubeadmCommands []string `json:"postKubeadmCommands,omitempty"`
 
@@ -347,6 +356,16 @@ func (c *KubeadmConfigSpec) validateIgnition(pathPrefix *field.Path) field.Error
 		}
 	}
 
+	if c.BootCommands != nil {
+		allErrs = append(
+			allErrs,
+			field.Forbidden(
+				pathPrefix.Child("bootCommands"),
+				cannotUseWithIgnition,
+			),
+		)
+	}
+
 	if c.DiskSetup == nil {
 		return allErrs
 	}
@@ -720,3 +739,6 @@ type Filesystem struct {
 
 // MountPoints defines input for generated mounts in cloud-init.
 type MountPoints []string
+
+// BootCommand defines input for each bootcmd command in cloud-init.
+type BootCommand []string

bootstrap/kubeadm/internal/cloudinit/boot_commands.go

@@ -0,0 +1,29 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package cloudinit
+
+const (
+	bootCommandsTemplate = `{{ define "boot_commands" -}}
+{{- if . }}
+bootcmd:{{ range . }}
+  - {{ range . }}- {{ . }}
+    {{ end -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+`
+)

bootstrap/kubeadm/internal/cloudinit/cloudinit.go

@@ -45,6 +45,7 @@ const (
 // BaseUserData is shared across all the various types of files written to disk.
 type BaseUserData struct {
 	Header               string
+	BootCommands         []bootstrapv1.BootCommand
 	PreKubeadmCommands   []string
 	PostKubeadmCommands  []string
 	AdditionalFiles      []bootstrapv1.File
@@ -83,6 +84,10 @@ func generate(kind string, tpl string, data interface{}) ([]byte, error) {
 		return nil, errors.Wrap(err, "failed to parse files template")
 	}
 
+	if _, err := tm.Parse(bootCommandsTemplate); err != nil {
+		return nil, errors.Wrap(err, "failed to parse boot commands template")
+	}
+
 	if _, err := tm.Parse(commandsTemplate); err != nil {
 		return nil, errors.Wrap(err, "failed to parse commands template")
 	}

bootstrap/kubeadm/internal/cloudinit/cloudinit_test.go

@@ -34,6 +34,7 @@ func TestNewInitControlPlaneAdditionalFileEncodings(t *testing.T) {
 	cpinput := &ControlPlaneInput{
 		BaseUserData: BaseUserData{
 			Header:              "test",
+			BootCommands:        nil,
 			PreKubeadmCommands:  nil,
 			PostKubeadmCommands: nil,
 			AdditionalFiles: []bootstrapv1.File{
@@ -94,9 +95,12 @@ func TestNewInitControlPlaneCommands(t *testing.T) {
 
 	cpinput := &ControlPlaneInput{
 		BaseUserData: BaseUserData{
+			BootCommands: []bootstrapv1.BootCommand{
+				{"echo", "$(date) hello BootCommands!"},
+			},
 			Header:              "test",
-			PreKubeadmCommands:  []string{`"echo $(date) ': hello world!'"`},
-			PostKubeadmCommands: []string{"echo $(date) ': hello world!'"},
+			PreKubeadmCommands:  []string{`"echo $(date) ': hello PreKubeadmCommands!'"`},
+			PostKubeadmCommands: []string{"echo $(date) ': hello PostKubeadmCommands!'"},
 			AdditionalFiles:     nil,
 			WriteFiles:          nil,
 			Users:               nil,
@@ -117,13 +121,18 @@ func TestNewInitControlPlaneCommands(t *testing.T) {
 	out, err := NewInitControlPlane(cpinput)
 	g.Expect(err).ToNot(HaveOccurred())
 
-	expectedCommands := []string{
-		`"\"echo $(date) ': hello world!'\""`,
-		`"echo $(date) ': hello world!'"`,
-	}
-	for _, f := range expectedCommands {
-		g.Expect(out).To(ContainSubstring(f))
-	}
+	expectedBootCmd := `bootcmd:
+  - - echo
+    - $(date) hello BootCommands!`
+
+	g.Expect(out).To(ContainSubstring(expectedBootCmd))
+
+	expectedRunCmd := `runcmd:
+  - "\"echo $(date) ': hello PreKubeadmCommands!'\""
+  - 'kubeadm init --config /run/kubeadm/kubeadm.yaml  && echo success > /run/cluster-api/bootstrap-success.complete'
+  - "echo $(date) ': hello PostKubeadmCommands!'"`
+
+	g.Expect(out).To(ContainSubstring(expectedRunCmd))
 }
 
 func TestNewInitControlPlaneDiskMounts(t *testing.T) {
@@ -132,6 +141,7 @@ func TestNewInitControlPlaneDiskMounts(t *testing.T) {
 	cpinput := &ControlPlaneInput{
 		BaseUserData: BaseUserData{
 			Header:              "test",
+			BootCommands:        nil,
 			PreKubeadmCommands:  nil,
 			PostKubeadmCommands: nil,
 			WriteFiles:          nil,
@@ -194,6 +204,7 @@ func TestNewJoinControlPlaneAdditionalFileEncodings(t *testing.T) {
 
 	cpinput := &ControlPlaneJoinInput{
 		BaseUserData: BaseUserData{
+			BootCommands:        nil,
 			Header:              "test",
 			PreKubeadmCommands:  nil,
 			PostKubeadmCommands: nil,
@@ -247,6 +258,7 @@ func TestNewJoinControlPlaneExperimentalRetry(t *testing.T) {
 	cpinput := &ControlPlaneJoinInput{
 		BaseUserData: BaseUserData{
 			Header:               "test",
+			BootCommands:         nil,
 			PreKubeadmCommands:   nil,
 			PostKubeadmCommands:  nil,
 			UseExperimentalRetry: true,
@@ -315,3 +327,83 @@ func Test_useKubeadmBootstrapScriptPre1_31(t *testing.T) {
 		})
 	}
 }
+
+func TestNewJoinControlPlaneCommands(t *testing.T) {
+	g := NewWithT(t)
+
+	cpinput := &ControlPlaneJoinInput{
+		BaseUserData: BaseUserData{
+			BootCommands: []bootstrapv1.BootCommand{
+				{"echo", "$(date) hello BootCommands!"},
+			},
+			Header:              "test",
+			PreKubeadmCommands:  []string{`"echo $(date) ': hello PreKubeadmCommands!'"`},
+			PostKubeadmCommands: []string{"echo $(date) ': hello PostKubeadmCommands!'"},
+			AdditionalFiles:     nil,
+			WriteFiles:          nil,
+			Users:               nil,
+			NTP:                 nil,
+		},
+		Certificates:      secret.Certificates{},
+		JoinConfiguration: "my-join-config",
+	}
+
+	for _, certificate := range cpinput.Certificates {
+		certificate.KeyPair = &certs.KeyPair{
+			Cert: []byte("some certificate"),
+			Key:  []byte("some key"),
+		}
+	}
+
+	out, err := NewJoinControlPlane(cpinput)
+	g.Expect(err).ToNot(HaveOccurred())
+
+	expectedBootCmd := `bootcmd:
+  - - echo
+    - $(date) hello BootCommands!`
+
+	g.Expect(out).To(ContainSubstring(expectedBootCmd))
+
+	expectedRunCmd := `runcmd:
+  - "\"echo $(date) ': hello PreKubeadmCommands!'\""
+  - kubeadm join --config /run/kubeadm/kubeadm-join-config.yaml  && echo success > /run/cluster-api/bootstrap-success.complete
+  - "echo $(date) ': hello PostKubeadmCommands!'"`
+
+	g.Expect(out).To(ContainSubstring(expectedRunCmd))
+}
+
+func TestNewJoinNodeCommands(t *testing.T) {
+	g := NewWithT(t)
+
+	nodeinput := &NodeInput{
+		BaseUserData: BaseUserData{
+			BootCommands: []bootstrapv1.BootCommand{
+				{"echo", "$(date) hello BootCommands!"},
+			},
+			Header:              "test",
+			PreKubeadmCommands:  []string{`"echo $(date) ': hello PreKubeadmCommands!'"`},
+			PostKubeadmCommands: []string{"echo $(date) ': hello PostKubeadmCommands!'"},
+			AdditionalFiles:     nil,
+			WriteFiles:          nil,
+			Users:               nil,
+			NTP:                 nil,
+		},
+		JoinConfiguration: "my-join-config",
+	}
+
+	out, err := NewNode(nodeinput)
+	g.Expect(err).ToNot(HaveOccurred())
+
+	expectedBootCmd := `bootcmd:
+  - - echo
+    - $(date) hello BootCommands!`
+
+	g.Expect(out).To(ContainSubstring(expectedBootCmd))
+
+	expectedRunCmd := `runcmd:
+  - "\"echo $(date) ': hello PreKubeadmCommands!'\""
+  - kubeadm join --config /run/kubeadm/kubeadm-join-config.yaml  && echo success > /run/cluster-api/bootstrap-success.complete
+  - "echo $(date) ': hello PostKubeadmCommands!'"`
+
+	g.Expect(out).To(ContainSubstring(expectedRunCmd))
+}

bootstrap/kubeadm/internal/cloudinit/controlplane_init.go

@@ -35,6 +35,7 @@ const (
     owner: root:root
     permissions: '0640'
     content: "This placeholder file is used to create the /run/cluster-api sub directory in a way that is compatible with both Linux and Windows (mkdir -p /run/cluster-api does not work with Windows)"
+{{- template "boot_commands" .BootCommands }}
 runcmd:
 {{- template "commands" .PreKubeadmCommands }}
   - 'kubeadm init --config /run/kubeadm/kubeadm.yaml {{.KubeadmVerbosity}} && {{ .SentinelFileCommand }}'

bootstrap/kubeadm/internal/cloudinit/controlplane_join.go

@@ -34,6 +34,7 @@ const (
     owner: root:root
     permissions: '0640'
     content: "This placeholder file is used to create the /run/cluster-api sub directory in a way that is compatible with both Linux and Windows (mkdir -p /run/cluster-api does not work with Windows)"
+{{- template "boot_commands" .BootCommands }}
 runcmd:
 {{- template "commands" .PreKubeadmCommands }}
   - {{ .KubeadmCommand }} && {{ .SentinelFileCommand }}