DOCSEARCHbyAlgolia
Submit Docs

talhelper

repository·master·Indexed 20 days ago

https://github.com/budimanjojo/talhelper

A specialized tool for managing Talos Linux cluster configurations in a GitOps-friendly manner. It functions as a template and overlay engine for Talos manifests with built-in SOPS support. Key capabilities include generating Talos configuration files via `genconfig`, creating secrets with `gensecret`, and producing `talosctl` commands (apply, bootstrap, health, kubeconfig, reset, upgrade) through `gencommand`. It also includes `tsehelper` for mapping Talos versions to system extensions and utilities for generating Talos image and installer URLs.

Tokens
19.6K
Snippets
90
Records
103
Agent score
71%

What's inside talhelper

  1. Overview of talhelper

    master

    What is talhelper?

    talhelper is a tool designed for creating Talos configuration files declaratively. It functions similarly to kustomize but is specifically tailored for Talos manifest files and includes native support for SOPS (Secrets Operations).

    Core Workflow

    When you run talhelper, it performs the following steps:

    1. Read and validate talconfig.yaml.
    2. Read and decrypt talsecret.yaml or talsecret.sops.yaml using sops if required.
    3. Read and decrypt talenv.yaml or talenv.sops.yaml using sops and load the values into environment variables.
    4. Perform envsubst to replace environment variables within configuration files.
    5. Validate and generate Talos and machine configuration files inside the ./clusterconfig directory.
    6. Generate a .gitignore file to prevent committing generated configuration files to version control.

  2. Overview of tsehelper

    master
    tsehelper is a tool designed to generate a mapping schema between Talos versions and their corresponding system extensions. It works by pulling version information from a specified Talos system extension container registry and producing a JSON schema. The tool is idempotent: it only pulls versions that are not already present in its local cache. To force a refresh of cached versions, you must manually delete the cache file or remove specific versions from it.

  3. Important security and operational warnings

    master

    When using talhelper, adhere to these critical safety rules:

    • Never push unencrypted files: Do not commit generated files (which contain unencrypted secrets) to public Git repositories. talhelper creates a .gitignore by default to prevent this; do not override it with --no-gitignore unless you are certain.
    • Protect talsecret.sops.yaml: Once a cluster is running, do not modify this file unless you intend to recreate the cluster or are an expert user, as changes can break cluster access.
    • talconfig rotation: Running talhelper genconfig requests a new talosconfig valid for 365 days. Consequently, the content of your generated files will change every time you run this command.

  4. Use Helm-like templating for node annotations

    master

    Certain configuration fields in talhelper support Helm-like templating, allowing you to use Sprig functions and reference other configuration fields.

    A common use case is passing the generated Talos installer image to Kubernetes workloads like the system-upgrade-controller via node annotations:

    ---
nodes:
  - hostname: my-node
    nodeAnnotations:
      installerImage: '{{ .MachineConfig.MachineInstall.InstallImage }}'

    This allows an upgrade plan to query the node's metadata to determine which image to use for the talosctl upgrade command.

  5. Use DRY (Don't Repeat Yourself) with controlPlane and worker groups

    master

    To avoid repeating configurations for similar nodes, you can define controlPlane or worker fields at the top level of talconfig.yaml. These act as global configurations for all nodes belonging to those groups.

    • schematic and patches: These are appended to the node's configuration.
    • NodeConfigs: These are overwritten if defined specifically within the nodes[] section.

    If you want to change the default appending behavior for a specific node, you can use overridePatches: true or overrideExtraManifests: true inside the node definition.

    ---
clusterName: my-cluster
nodes:
  - hostname: cp1
    controlPlane: true
    ipAddress: 192.168.200.11
    installDisk: /dev/sda
  - hostname: cp2
    controlPlane: true
    ipAddress: 192.168.200.12
    installDisk: /dev/sda
controlPlane:
  schematic:
    customization:
      extraKernelArgs:
        - net.ifnames=0
  patches:
    - |-
      machine:
        kubelet:
          extraArgs:
            rotate-server-certificates: "true"

  6. Generate talosctl commands with gencommand

    master

    The gencommand sub-command is used to generate specific talosctl commands (such as apply, bootstrap, health, etc.) based on your talhelper configurations.

    Common Flags for all gencommand sub-commands:

    • -c, --config-file string: Path to the talhelper configuration file (default: talconfig.yaml).
    • -e, --env-file strings: List of files containing environment variables (defaults to [talenv.yaml,talenv.sops.yaml,talenv.yml,talenv.sops.yml]).
    • -n, --node string: Generate the command for a specific node. If omitted, commands are generated for all nodes.
    • -o, --out-dir string: Directory where generated config files are stored (default: ./clusterconfig).
    • -d, --debug: Enable debugging mode.
    • --extra-flags strings: Additional flags to be injected into the generated commands.

  7. Generate Talos configuration and secrets with Talhelper CLI

    master

    Talhelper provides two primary commands for generating Talos-related assets:

    1. talhelper genconfig: Use this command to generate your Talos configuration files.
    2. talhelper gensecret: Use this command to generate Talos secrets.

    For detailed usage instructions and advanced configuration, refer to the official documentation at https://budimanjojo.github.io/talhelper.

    # Generate Talos configuration
talhelper genconfig

# Generate Talos secrets
talhelper gensecret

  8. GitOps workflow with talhelper

    master

    Use talhelper to enable a GitOps workflow for Talos configurations, allowing you to version control your cluster state. Unlike the standard talosctl gen config workflow which requires manual file modification, talhelper uses a declarative configuration.

    Recommended Workflow

    1. Define Configuration: Create a talconfig.yaml file.
    2. Manage Secrets:
      • Generate a secret template: talhelper gensecret > talsecret.sops.yaml
      • Encrypt the secret file using sops: sops -e -i talsecret.sops.yaml
    3. Generate Configs: Run talhelper genconfig to produce the machine configurations.
    4. Apply Configuration: Use talosctl to apply the generated files to your nodes:
      talosctl apply-config --insecure -n <ip-address> --file ./clusterconfig/<cluster-name>-<hostname>.yaml
    
By following this process, you can safely commit `talconfig.yaml` and your encrypted `talsecret.sops.yaml` to your Git repository.

    talhelper gensecret > talsecret.sops.yaml
sops -e -i talsecret.sops.yaml
talhelper genconfig
talosctl apply-config --insecure -n <ip-address> --file ./clusterconfig/<cluster-name>-<hostname>.yaml

  10. Create a minimal talconfig.yaml

    master

    A basic talconfig.yaml defines your cluster name, the endpoint for the Talos API, and a list of nodes. Each node requires a hostname, ipAddress, and installDisk. You can also specify if a node is a control plane node using controlPlane: true.

    ---
clusterName: my-cluster
endpoint: https://192.168.200.10:6443
nodes:
  - hostname: master
    controlPlane: true
    ipAddress: 192.168.200.11
    installDisk: /dev/sda

  11. Configure fish autocompletion for talhelper

    master

    Generate and load autocompletion scripts for the fish shell.

    To load completions in your current session:

    talhelper completion fish | source

    To persist completions for every new session:

    talhelper completion fish > ~/.config/fish/completions/talhelper.fish

    Note: You must start a new shell for changes to take effect.

    talhelper completion fish

  12. Configure SOPS for Talhelper

    master

    To use sops for managing secrets in talhelper, follow these steps:

    1. Install sops and age.
    2. Generate an age key: age-keygen -o <sops-config-dir>/age/keys.txt.
    3. Create a .sops.yaml file in the directory containing your talenv.sops.yaml and talsecrets.sops.yaml with the following content:
    ---
creation_rules:
  - age: <age-public-key-from-keys.txt>

    Once configured, talhelper will automatically decrypt talenv.sops.yaml and talsecrets.sops.yaml during configuration generation.

    ---
creation_rules:
  - age: >-
      <age-public-key>