pulumi-talos-cluster (WIP)

pulumi-talos-cluster is a Pulumi component designed to simplify the creation and management of Talos clusters. This component abstracts the complexities of setting up and managing Talos-based Kubernetes clusters, allowing for streamlined deployment and configuration.

This component can be used for bare-metal and cloud installations. Direct access to apid on nodes is required.

Note: This project is in active development, and not all features are complete.

Requirements

Only Linux is supported as the runner operating system. The following tools must be available:

• bash (must be available at /bin/bash)
• printf
• talosctl (version v1.12.0 or compatible recommended to match the default Talos image version)

Quick Start

1. Install bash (at /bin/bash), printf, and talosctl on a Linux machine.
2. Clone this repository.
3. Run an example program, such as those under integration-tests/testdata, using pulumi up. The provider plugin installs automatically.

Existing stacks that use the Pulumiverse Talos provider must follow the migration guide before applying this version.

Generated machine configurations, client credentials, talosconfig, and kubeconfig are Pulumi secret outputs. Use pulumi stack output --show-secrets <name> only in a controlled environment.

Cluster Lifecycle

flowchart TD
    Start[Cluster inputs] --> Secrets[talosctl gen secrets]
    Secrets --> MachineConfig[talosctl gen config: machine configs]
    Secrets --> Talosconfig[talosctl gen config: talosconfig]
    MachineConfig --> InitialApply{skip initial apply?}
    InitialApply -- no --> Insecure[talosctl apply-config --insecure]
    InitialApply -- yes --> Secure
    Insecure --> Secure[talosctl apply-config with talosconfig]
    Talosconfig --> Secure
    Secure --> Bootstrap[talosctl bootstrap]
    Bootstrap --> Upgrade[talosctl upgrade-k8s]
    Upgrade --> Kubeconfig[talosctl kubeconfig]
    Kubeconfig --> Ready[Cluster ready]

The Pulumi command provider executes each CLI operation. Temporary credentials are written with restrictive permissions, sensitive stdout is suppressed, and working directories are removed after execution.

Motivation

The official Terraform (and therefore Pulumi) provider for Talos has certain limitations, particularly around upgrading and configuring clusters, as highlighted in issues like #195. This component directly orchestrates talosctl and utilizes the pulumi/command provider to fully manage Talos clusters, overcoming these limitations and providing a more native experience.

Development

Go

Note: It is recommended to use Pulumi's local storage for development, as using the Pulumi service or self-hosted S3 storage can slow down deployments.

To build the component:

$ make build && make install_provider # This generates all SDKs and builds the provider
$ export PATH=$PATH:~/go/bin

Preparing for release

To build the provider and all SDKs (Go, Node.js, Python, and .NET) in one step, set the desired version explicitly (for example, v0.7.0):

VERSION=v0.7.0 make build
git add .
git commit -m 'regenerate'
VERSION=v0.7.0 make build
git add .
git commit -m 'release'

Example

Refer to the integration-tests/testdata directory for sample Pulumi programs using the pulumi-talos-cluster component.

Roadmap

Current focus

• Refactor tests.
• Add more cloud providers to tests.
• Include all supported languages in tests.

Planned enhancements

• [x] Kubernetes Version Configuration: Allow setting the Kubernetes version directly via the CLI.
• [ ] Tests and Continuous Integration: Implement tests and CI/CD pipelines to ensure code quality and stability.
• [ ] Multi-language Examples: Provide usage examples in four languages (TypeScript, Python, Go, and .NET).
• [ ] Comprehensive Documentation: Enhance documentation with detailed setup, customization, and troubleshooting guides.