Boot customization

About boot customization

Passing environment variables through kernel parameters (talos.environment) is deprecated in favor of native Talos configuration documents. For proxy and environment settings, use embeddedMachineConfiguration with EnvironmentConfig.

The boot behavior of an image can be customized to configure essential settings—such as network interfaces, proxy settings, or kernel flags—before a node joins a cluster.

How you customize the boot behavior depends on the Talos version you are using:

Embedded config (Newer)

For v1.13.10-stackit.v1.8.5 and newer, configure boot customization using embedded machine configuration directly inside the image schematic.

Embedded machine configuration is not supported in the STEC web UI. You must use the API (kubectl) to create the EdgeImage resource.

Using embedded machine configuration (CLI)

Prerequisites:

• Successfully authenticated with a STEC instance.
• The kubeconfig for the STEC instance is exported in your terminal session.
• Tools: a generic Linux bash terminal and kubectl.

Steps:

1. Follow the generic image creation steps as described in the getting started guide.

2. In the EdgeImage manifest, define the configuration document inside spec.schematic.customization.embeddedMachineConfiguration. To configure low-level kernel parameters (such as enabling the console or dashboard), define extraKernelArgs:

   cat <<EOF | kubectl apply -f -
   apiVersion: edge.stackit.cloud/v1alpha1
   kind: EdgeImage
   metadata:
     name: custom-boot-image
     namespace: default
   spec:
     talosVersion: v1.13.10-stackit.v1.8.5
     schematic: |
       customization:
         extraKernelArgs:
           - talos.dashboard.disabled=0
         systemExtensions:
           officialExtensions: []
         embeddedMachineConfiguration: |
           apiVersion: v1alpha1
           kind: EnvironmentConfig
           env:
             http_proxy: http://proxy.example.local:8080
             https_proxy: http://proxy.example.local:8080
             no_proxy: localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.cluster.local.,.cluster.local,.svc,.svc.
       overlay: {}
   EOF

3. Confirm that the image resource exists:

   kubectl get edgeimage custom-boot-image

4. Download and flash the boot medium as described in the image creation procedure. When the host boots, it automatically applies the embedded configuration.

Verifying embedded machine configuration

You can check whether your nodes have applied the embedded configuration using talosctl.

Prerequisites:

• You have installed talosctl.
• You have acquired your talosconfig.

Steps:

1. Set your TALOSCONFIG environment variable:

   export TALOSCONFIG=your-edge-cluster.talosconfig.yaml

2. Query the environment configuration from a node:

   talosctl -n $NODE_IP -e $NODE_IP get environments -o yaml

   The output reflects the embedded proxy settings:

   node: 192.168.1.50
   metadata:
     namespace: config
     type: EnvironmentConfigs.config.talos.dev
     id: environment
     version: 1
   spec:
     env:
       http_proxy: http://proxy.example.local:8080
       https_proxy: http://proxy.example.local:8080
       no_proxy: localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.cluster.local.,.cluster.local,.svc,.svc.

Kernel parameters (Legacy)

For Talos versions prior to v1.13.10-stackit.v1.8.5, configure boot customization with kernel parameters (extraKernelArgs).

When you configure settings in the kernel parameters, they take effect only when no machine configuration has been applied yet. Once your host becomes part of a cluster (exits the maintenance stage), those settings are overwritten by the machine configuration. When you reset a host, the initial kernel parameters of the image take effect again.

You can review or change the kernel parameters of a STEC boot medium by pressing the e key during bootloader selection.

Using the UI

Prerequisites:

• Successfully authenticated in the UI of a STEC instance.

Steps:

1. Follow the generic image creation steps as described in the getting started guide.

2. In the Kernel Parameters step, enter one or more supported parameters. The generic syntax is key=value, separated by spaces. Click Next when done.

   

3. Review the image parameters to confirm your options are included, then click Create.

   

4. Complete the remaining steps in the regular image creation procedure.

Using the CLI

Prerequisites:

• Successfully authenticated with a STEC instance.
• Kubeconfig for the STEC instance is exported in your terminal session.
• Tools: a generic Linux bash terminal, kubectl.

Steps:

1. Follow the generic image creation steps as described in the getting started guide.

2. In the EdgeImage manifest, populate extraKernelArgs with supported kernel parameters:

   cat <<EOF | kubectl apply -f -
   apiVersion: edge.stackit.cloud/v1alpha1
   kind: EdgeImage
   metadata:
     name: bootfoo
     namespace: default
   spec:
     schematic: |
       customization:
         extraKernelArgs:
         - talos.hostname=custom
         - talos.dashboard.disabled=0
         systemExtensions:
           officialExtensions: []
       overlay: {}
     talosVersion: v1.10.5-stackit.v0.21.0
   EOF

3. Confirm that the image was created:

   kubectl get edgeimage bootfoo

4. Complete the remaining steps in the regular image creation procedure.

Common parameters (Before v1.13.10-stackit.v1.8.5)

Static network

To configure a static IP address so the STEC node can reach your STEC instance, use the ip kernel parameter.

General syntax:

# kernel args
ip=<CLIENT_IP>:<SERVER_IP>:<GATEWAY_IP>:<NETMASK>:<HOSTNAME>:<DEVICE>:<AUTOCONF>:<DNS_SERVER_IP_0>:<DNS_SERVER_IP_1>:<NTP_SERVER_IP>

Example usage:

# kernel args
ip=172.16.0.11::172.16.0.1:255.255.255.0:foo:eth0:none:1.1.1.1:1.0.0.1:time.cloudflare.com

Internet proxy

STACKIT Edge Cloud requires an outbound HTTPS connection for the STEC node to register with your STEC instance hosted on stackit.cloud. To configure a proxy using kernel parameters, use talos.environment.

General syntax:

# kernel args
talos.environment=KEY=VALUE

Example usage:

# kernel args
talos.environment=http_proxy=http://proxy.example.net:8080 talos.environment=https_proxy=http://proxy.example.net:8443 talos.environment=no_proxy=localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.cluster.local.,.cluster.local,.svc,.svc.

In the UI, enter the parameters in the Kernel Parameters step:

References

• Talos documentation on kernel parameters
• Talos documentation on environment configuration