Install

This doc will guide you through the installation of the Tinkerbell stack.

• Kubectl
• Helm
• A Kubernetes cluster running version 1.26 or later
• Network connectivity
  • Layer 2 network connectivity between the Tinkerbell stack and the machines to be provisioned OR
  • a DHCP relay agent in your environment that is configured to forward DHCP traffic to the Tinkerbell stack.

This is the recommended way to install a production grade Tinkerbell stack. This will install all services and optionally (enabled by default) download HookOS images to the cluster.

# Get the pod CIDRs to set as trusted proxies
TRUSTED_PROXIES=$(kubectl get nodes -o jsonpath='{.items[*].spec.podCIDR}' | tr ' ' ',')

# Set the LoadBalancer IP for Tinkerbell services
LB_IP=192.0.2.116

# Set the artifacts file server URL for HookOS
ARTIFACTS_FILE_SERVER=http://192.0.2.117:7173

# Specify the Tinkerbell Helm chart version, here we use the latest release.
TINKERBELL_CHART_VERSION=v0.19.0


helm install tinkerbell oci://ghcr.io/tinkerbell/charts/tinkerbell \
  --version $TINKERBELL_CHART_VERSION \
  --create-namespace \
  --namespace tinkerbell \
  --wait \
  --set "trustedProxies={${TRUSTED_PROXIES}}" \
  --set "publicIP=$LB_IP" \
  --set "artifactsFileServer=$ARTIFACTS_FILE_SERVER"

This section describes the procedure to install the Tinkerbell stack using Helm. The general syntax for a Helm installation is:

helm install <release> <chart> --version <version> --create-namespace --namespace <namespace> --wait [--set <other_parameters>]

The variables specified in the command are as follows:

• <chart> A path to a packaged chart, a path to an unpacked chart directory or a URL.
• <release> A name to identify and manage the Helm chart once installed.
• <version> The version of the chart to install.
• <namespace> The namespace in which the chart is to be installed.

Default configuration values can be changed using one or more --set <parameter>=<value> arguments. Alternatively, you can specify several parameters in a custom values file using the --values <file> argument.

You can display the default values of configuration parameters using the helm show values oci://ghcr.io/tinkerbell/charts/tinkerbell --version v0.19.0 command.

1. Configure the Helm values for your environment.

   The following values are required to get the stack up and running in your environment. They are set either in a values file or as --set arguments.

   • trustedProxies: A comma-separated list of trusted proxies. This is used to configure the X-Forwarded-For header in HTTP requests for Tootles and auto.ipxe in Smee.
   • publicIP: The IP address to use for the Kubernetes North/South load balancer. This should be a free IP address in the network where the Tinkerbell stack is deployed. See the upstream Kubernetes docs on load balancers for more information.
   • artifactsFileServer: The full URL to the HTTP server serving HookOS artifacts like the kernel and initramfs, for example http://192.0.2.117:7173

   For further settings, have a look at the Chart’s Readme and values.yaml file.

2. Install the Tinkerbell Helm chart.

   # Get the pod CIDRs to set as trusted proxies
   TRUSTED_PROXIES=$(kubectl get nodes -o jsonpath='{.items[*].spec.podCIDR}' | tr ' ' ',')
   
   # Set the LoadBalancer IP for Tinkerbell services
   LB_IP=192.0.2.116
   
   # Set the artifacts file server URL for HookOS
   ARTIFACTS_FILE_SERVER=http://192.0.2.117:7173
   
   # Specify the Tinkerbell Helm chart version, here we use the latest release.
   TINKERBELL_CHART_VERSION=v0.19.0
   
   
   helm install tinkerbell oci://ghcr.io/tinkerbell/charts/tinkerbell \
     --version $TINKERBELL_CHART_VERSION \
     --create-namespace \
     --namespace tinkerbell \
     --wait \
     --set "trustedProxies={${TRUSTED_PROXIES}}" \
     --set "publicIP=$LB_IP" \
     --set "artifactsFileServer=$ARTIFACTS_FILE_SERVER"
   

3. Verify the stack is up and running.

   kubectl get pods -n tinkerbell # verify all pods are running
   kubectl get svc -n tinkerbell # Verify the tinkerbell service has the IP you specified with $LB_IP under the EXTERNAL-IP column
   

In order to start using the Tinkerbell stack and running Workflows, you will need to have Machines to provision and you’ll need to create Hardware, Template, and Workflow objects. See the docs on Hardware, Templates, and Workflows for more information.

Uninstall the Tinkerbell stack via Helm.

helm uninstall tinkerbell -n tinkerbell

To allow for DHCP broadcast traffic to reach Tinkerbell, the chart has an init container that creates an additional network interface on the host running Tinkerbell and then moves this interface into the Tinkerbell Pod. This allows Tinkerbell to receive and send broadcast traffic on the layer 2 network.