### Install Project Tools

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Installs the required project dependencies using Mise.

```bash
cd cluster-template (or your cloned repo)
mise install
```

--------------------------------

### Example #Node Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/cue-schema.md

A concrete example of a node configuration object that satisfies the #Node schema requirements.

```cue
{
    name = "control-0"
    address = "192.168.1.20"
    controller = true
    disk = "/dev/sda"
    mac_addr = "aa:bb:cc:dd:ee:01"
    schematic_id = "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
    mtu = 1500
    encrypt_disk = true
}
```

--------------------------------

### Install Flux

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Deploy Flux using either Helmfile or Kustomize.

```bash
# Option 1: Using Helmfile (legacy)
cd bootstrap
helmfile apply

# Option 2: Using Kustomize
kubectl apply -k bootstrap/
```

--------------------------------

### Bootstrap Talos

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Initiates the Talos installation process.

```sh
just bootstrap talos
```

--------------------------------

### Verify Tool Installation

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Checks that the core rendering and configuration tools are correctly installed.

```bash
makejinja --version
cue version
```

--------------------------------

### Example configuration output

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Sample structure of the configuration dictionary returned by the plugin after processing.

```python
{
  'network': {
    'node_cidr': '192.168.1.0/24',
    'default_gateway': '192.168.1.1',  # Computed
    'dns_servers': ['1.1.1.1', '1.0.0.1']
  },
  'kubernetes': {
    'pod_cidr': '10.42.0.0/16',
    'svc_cidr': '10.43.0.0/16',
    'api': {'addr': '192.168.1.10'}
  },
  'nodes': [...]
}
```

--------------------------------

### Install required CLI tools with Mise

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Trust the local configuration and install dependencies defined in the project.

```sh
mise trust
pip install pipx
mise install
```

--------------------------------

### Install dependencies via Mise

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/quick-reference.md

Use these commands to trust and install the required project dependencies defined in the environment.

```bash
mise trust
mise install
```

--------------------------------

### Install Mise CLI

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Initializes the Mise tool manager on the local workstation.

```bash
curl https://mise.jdx.dev/install.sh | sh
mise trust
```

--------------------------------

### Troubleshoot HelmRelease Installation

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Inspect Helm repositories and chart availability to diagnose installation failures.

```bash
# Check Helm repository
kubectl get helmrepository -n flux-system

# View HelmRelease error
kubectl describe helmrelease <name> -n <namespace>

# Check Helm chart availability
helm repo update
helm search repo <chart>
```

--------------------------------

### Construct Webhook URL

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Example format for the full GitHub webhook URL.

```text
https://flux-webhook.${cloudflare_domain}/hook/12ebd1e363c641dc3c2e430ecf3cee2b3c7a5ac9e1234506f6f5f3ce1230e123
```

--------------------------------

### Bootstrap Cluster Applications

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Installs core components including cilium, coredns, spegel, and flux.

```sh
just bootstrap apps
```

--------------------------------

### Map input to output file paths

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Example showing how input template paths map to the rendered output directory structure.

```text
Input:  template/config/kubernetes/apps/default/echo/app/helmrelease.yaml.j2
Output: kubernetes/apps/default/echo/app/helmrelease.yaml
```

--------------------------------

### Helm GoTemplate Naming

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/template-structure.md

Examples of file suffixes for templates processed by both Jinja2 and Helm.

```text
release.yaml.gotmpl.j2
values.yaml.gotmpl.j2
```

--------------------------------

### Verify Flux Installation

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Check the status of Flux pods and review logs for the source controller.

```bash
kubectl get -n flux-system pod,helmrelease
kubectl logs -n flux-system deploy/source-controller
```

--------------------------------

### Define and use the #Kubernetes schema

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/cue-schema.md

Defines Kubernetes networking parameters and provides an example of how to populate the configuration.

```cue
#Kubernetes: {
    pod_cidr: *"10.42.0.0/16" | net.IPCIDR
    svc_cidr: *"10.43.0.0/16" | net.IPCIDR
    api: {
        addr: net.IPv4
        tls_sans?: [...net.FQDN]
    }
}
```

```cue
pod_cidr = "10.42.0.0/16"
svc_cidr = "10.43.0.0/16"
api.addr = "192.168.1.10"
api.tls_sans = ["k8s.example.com"]
```

--------------------------------

### Bootstrap Flux Components

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/quick-reference.md

Apply secrets and install Flux to manage the cluster state.

```bash
# Apply bootstrap secrets
kubectl apply -f bootstrap/sops-age.sops.yaml
kubectl apply -f bootstrap/github-deploy-key.sops.yaml

# Install Flux components
kubectl apply -k bootstrap/

# Monitor Flux
flux status
flux logs --follow --all-namespaces
```

--------------------------------

### Define variable_start delimiter

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Example usage of the custom variable_start delimiter.

```jinja2
pod_cidr: #{ kubernetes.pod_cidr }#
```

--------------------------------

### Talos Node Installation

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/quick-reference.md

Commands to apply configurations to Talos nodes and retrieve the cluster kubeconfig.

```bash
# Apply first control plane node
talosctl apply-config --insecure \
  --nodes 192.168.1.20 \
  --file talos/control-0.yaml

# Get kubeconfig
talosctl kubeconfig -n 192.168.1.20

# Apply remaining nodes
talosctl apply-config --nodes 192.168.1.21 --file talos/control-1.yaml
talosctl apply-config --nodes 192.168.1.22 --file talos/control-2.yaml

# Verify all nodes ready
kubectl get nodes
```

--------------------------------

### Define block_start delimiter

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Example usage of the custom block_start delimiter for control structures.

```jinja2
#% if kubernetes.bgp_enabled #%
  # BGP configuration
#% endif #%
```

--------------------------------

### Define comment_start delimiter

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Example usage of the custom comment_start delimiter.

```jinja2
#| This is a Jinja2 comment, not rendered |#
```

--------------------------------

### Define Cluster Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Example structure for the cluster.toml configuration file including network, repository, cloudflare, and node definitions.

```toml
[network]
node_cidr = "192.168.1.0/24"

[kubernetes.api]
addr = "192.168.1.10"

[gateways]
internal = "192.168.1.50"
dns = "192.168.1.51"
external = "192.168.1.52"

[repository]
name = "myuser/home-ops"

[cloudflare]
domain = "example.com"
token = "eyJhbGc..."

[[nodes]]
name = "control-0"
address = "192.168.1.20"
controller = true
disk = "/dev/sda"
mac_addr = "aa:bb:cc:dd:ee:01"
schematic_id = "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"

[[nodes]]
name = "control-1"
address = "192.168.1.21"
controller = true
disk = "/dev/sda"
mac_addr = "aa:bb:cc:dd:ee:02"
schematic_id = "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"

[[nodes]]
name = "control-2"
address = "192.168.1.22"
controller = true
disk = "/dev/sda"
mac_addr = "aa:bb:cc:dd:ee:03"
schematic_id = "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
```

--------------------------------

### SOPS Encryption Example

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/generated-artifacts.md

Demonstrates the transformation of sensitive data from plain text to encrypted format using SOPS.

```yaml
stringData:
  token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```yaml
stringData:
    token: ENC[AES256_GCM,data:Zm9vYmFyYmF6==,iv:...,tag:...,type:string]
```

--------------------------------

### Jinja2 Template Example

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

A HelmRelease template using custom delimiters for Jinja2 variable injection.

```yaml
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: echo
spec:
  values:
    config:
      kubernetes: true
      trustedProxies:
        - "#{ kubernetes.pod_cidr }#"
    httpRoute:
      hostnames:
        - "{{ .Release.Name }}.#{ cloudflare.domain }#"
      parentRefs:
        - name: envoy-external
```

--------------------------------

### Rendered Output Example

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

The final YAML output after Jinja2 processing, showing substituted values while retaining Helm syntax.

```yaml
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: echo
spec:
  values:
    config:
      kubernetes: true
      trustedProxies:
        - "10.42.0.0/16"
    httpRoute:
      hostnames:
        - "{{ .Release.Name }}.example.com"
      parentRefs:
        - name: envoy-external
```

--------------------------------

### Template error handling example

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Illustrates how template functions report errors when required files are missing.

```jinja2
#{ age_key('private') }#
# If file not found:
# RuntimeError: FileNotFoundError: File not found: age.key
```

--------------------------------

### Partial Template Naming

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/template-structure.md

Example of a file suffix used for template fragments intended for inclusion.

```text
readme.partial.yaml.j2
```

--------------------------------

### Define and Configure Cloudflare Settings

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/cue-schema.md

Defines the schema for Cloudflare DNS and tunnel configuration, including an example usage.

```cue
#Cloudflare: {
    domain: net.FQDN
    token: string
}
```

```cue
domain = "example.com"
token = "eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyJ9..."
```

--------------------------------

### Initialize Configuration File

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Create the initial cluster configuration file from the provided sample.

```bash
cp cluster.sample.toml cluster.toml
```

--------------------------------

### Create and clone repository with GitHub CLI

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Initialize a new repository from the template and enter the directory.

```sh
export REPONAME="home-ops"
gh repo create $REPONAME --template onedr0p/cluster-template --public --clone
cd $REPONAME
```

--------------------------------

### Create Repository from Template

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Initializes a new repository using the cluster-template as a base.

```bash
gh repo create home-ops --template onedr0p/cluster-template --public --clone
cd home-ops
```

--------------------------------

### Define variable_end delimiter

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Example usage of the custom variable_end delimiter.

```jinja2
gateway_ip: #{ gateways.internal }#
```

--------------------------------

### Configure and Validate Cluster Settings

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/quick-reference.md

Use these commands to initialize the configuration file from the sample and validate it against the CUE schema.

```bash
# Create configuration from sample
cp cluster.sample.toml cluster.toml
# Edit with your settings, save

# Validate configuration
cue export cluster.toml template/resources/config.schema.cue --out json

# View computed defaults
cue export cluster.toml template/resources/config.schema.cue --out json | jq .
```

--------------------------------

### Define comment_end delimiter

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Example usage of the custom comment_end delimiter.

```jinja2
#| Build date: 2024-01-15 |#
# File: helmrelease.yaml
```

--------------------------------

### Initialize Cluster Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Generates initial configuration files from samples.

```sh
just init
```

--------------------------------

### Plugin.__init__(data)

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Constructor for the Makejinja plugin.

```APIDOC
## Plugin.__init__(data: dict[str, Any])

### Description
Constructor for Makejinja plugin.

### Parameters
- **data** (dict) - Required - Initial data dictionary from Makejinja.
```

--------------------------------

### Initialize Git Repository

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Commit and push the initial cluster configuration files to the remote repository.

```bash
git add cluster.toml bootstrap/ kubernetes/ talos/ .sops.yaml
git commit -m "chore: initialize cluster configuration"
git push origin main
```

--------------------------------

### Define block_end delimiter

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Example usage of the custom block_end delimiter for control structures.

```jinja2
#% for node in nodes #%
  - name: #{ node.name }#
#% endfor #%
```

--------------------------------

### Render and Verify Manifests

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/quick-reference.md

Commands for generating templates and verifying the resulting Kubernetes manifests.

```bash
# Render all templates
makejinja

# Validate rendered manifests
bash template/resources/kubeconform.sh

# View diffs before committing
git diff kubernetes/ talos/
```

--------------------------------

### Render Templates

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/README.md

Execute this command to process and render the project templates using makejinja.

```bash
makejinja
```

--------------------------------

### Apply configuration to new node

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Renders the configuration and applies it to a new node to join the cluster.

```sh
# Render your talosconfig based on the talconfig.yaml file
just talos generate-config

# Apply the configuration to the node
just talos apply-node <ip>
# e.g. just talos apply-node 10.10.10.10
```

--------------------------------

### SOPS Encrypted File Naming

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/template-structure.md

Examples of file suffixes used for encrypted YAML secrets.

```text
github-deploy-key.sops.yaml.j2
sops-age.sops.yaml.j2
secret.sops.yaml.j2
```

--------------------------------

### Commit and Deploy

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/README.md

Standard workflow for staging, committing, and pushing configuration changes to trigger automated validation.

```bash
# Stage and commit
git add cluster.toml bootstrap/ kubernetes/ talos/ .sops.yaml
git commit -m "chore: update cluster configuration"
git push origin main

# GitHub Actions validates automatically
```

--------------------------------

### Cilium HelmRelease Variable Template

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/generated-artifacts.md

Example of a templated variable for Cilium load balancer mode.

```yaml
spec:
  values:
    ipam:
      mode: kubernetes
    kubeProxyReplacement: true
    loadBalancer:
      mode: #{ cilium.loadbalancer_mode }#
      # Rendered as: mode: dsr
```

--------------------------------

### View Generated Directory Structure

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/generated-artifacts.md

Displays the layout of the repository root after makejinja execution, showing the organization of bootstrap, kubernetes, and talos artifacts.

```text
.
├── bootstrap/                          [Bootstrap secrets and Flux setup]
│   ├── github-deploy-key.sops.yaml
│   ├── sops-age.sops.yaml
│   ├── helmfile/                       [Legacy Helm releases]
│   │   ├── apps.yaml
│   │   ├── crds.yaml
│   │   └── default.yaml
│   ├── mod.just                        [Bootstrap Just commands]
│   └── [other bootstrap configs]
├── kubernetes/                         [Kubernetes manifests]
│   ├── apps/                           [Application workloads]
│   │   ├── cert-manager/
│   │   ├── default/
│   │   ├── flux-system/
│   │   ├── kube-system/
│   │   └── network/
│   ├── flux/                           [Flux source definitions]
│   │   ├── helmrepository.yaml
│   │   ├── ocirepository.yaml
│   │   └── gitrepository.yaml
│   └── talos/                          [Talos-specific objects]
├── talos/                              [Talos node configurations]
│   ├── control-0.yaml                  [One file per node]
│   ├── control-1.yaml
│   ├── control-2.yaml
│   └── patches/                        [Node patches]
│       └── common/
├── .sops.yaml                          [SOPS encryption rules]
├── cluster.toml                        [User configuration (unchanged)]
└── [other generated files]
```

--------------------------------

### Review Configuration Changes

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Compare the generated manifests against previous versions using git diff.

```bash
git diff kubernetes/ talos/
```

--------------------------------

### Envoy Gateway Address Template

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/generated-artifacts.md

Example of templated gateway addresses for internal, DNS, and external traffic.

```yaml
spec:
  addresses:
  - value: #{ gateways.internal }#
    # Rendered as: value: 192.168.1.50
  - value: #{ gateways.dns }#
    # Rendered as: value: 192.168.1.51
  - value: #{ gateways.external }#
    # Rendered as: value: 192.168.1.52
```

--------------------------------

### Debug Talos Node Startup

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Commands to inspect logs, service status, and node health when a Talos node fails to join the cluster.

```bash
# Check node logs
talosctl logs -n <ip> kubelet

# Verify network connectivity
talosctl service -n <ip>

# Check node status
talosctl status -n <ip>
```

--------------------------------

### List pods in a namespace

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Retrieve a list of pods in a specific namespace with wide output format.

```sh
kubectl -n <namespace> get pods -o wide
```

--------------------------------

### Load Custom Kernel Modules

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Specify a list of kernel modules in the node configuration to be loaded at boot time.

```toml
[[nodes]]
...
kernel_modules = ["kvm", "intel_ept", "custom_module"]
```

--------------------------------

### Render and Test Templates

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/README.md

Commands to generate templates, validate Kubernetes manifests, and review pending changes.

```bash
# Render all templates
makejinja

# Validate Kubernetes manifests
bash template/resources/kubeconform.sh

# Review changes
git diff kubernetes/ talos/
```

--------------------------------

### Apply Initial Control Plane Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Apply the configuration to the first control plane node using an insecure connection.

```bash
export CONTROLPLANE_IP=192.168.1.20
talosctl apply-config --insecure \
  --nodes $CONTROLPLANE_IP \
  --file talos/control-0.yaml
```

--------------------------------

### Configure Development Environment with Mise

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Define the makejinja version in your .mise/config.toml file to ensure consistent local development environments.

```toml
[tools]
makejinja = "0.16.0"
```

--------------------------------

### Define makejinja.toml configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

The primary configuration file for defining input directories, output paths, data sources, and custom delimiters.

```toml
[makejinja]
inputs = ["./template/overrides","./template/config"]
output = "./"
exclude_patterns = ["*.partial.yaml.j2"]
data = ["./cluster.toml"]
import_paths = ["./template/scripts"]
loaders = ["plugin:Plugin"]
jinja_suffix = ".j2"
copy_metadata = true
force = true
undefined = "chainable"

[makejinja.delimiter]
block_start = "#%"
block_end = "%#"
comment_start = "#|"
comment_end = "#|"
variable_start = "#{"
variable_end = "}#"
```

--------------------------------

### cue_export()

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Runs the cue export command to validate configuration against schema defaults and returns the parsed configuration.

```APIDOC
## cue_export()

### Description
Runs `cue export` command to validate configuration and apply schema defaults.

### Signature
`def cue_export() -> dict[str, Any]`

### Returns
- **dict** - Validated configuration with all defaults applied, parsed from CUE export JSON output.

### Raises
- **RuntimeError** - If `cue export` fails, includes stderr from subprocess.
```

--------------------------------

### Describe Kubernetes resources

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Inspect the details and status of a specific Kubernetes resource.

```sh
kubectl -n <namespace> describe <resource> <name>
```

--------------------------------

### Validate Configuration Syntax

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Use CUE to validate the TOML configuration against the defined schema.

```bash
# Validate TOML syntax and CUE schema
cue export cluster.toml template/resources/config.schema.cue --out json

# Output should show enriched config with defaults applied
```

--------------------------------

### Verify Core Cluster Components

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Check the status of networking, gateway, DNS, certificate management, and encryption components.

```bash
# Cilium networking
kubectl get pods -n kube-system | grep cilium

# Envoy Gateway
kubectl get gateway -n network
kubectl get httproute -n network

# External DNS
kubectl get service -n network -l app=external-dns
kubectl logs -n network deploy/external-dns

# Cert-Manager
kubectl get certificate -n cert-manager
kubectl describe clusterissuer letsencrypt-production -n cert-manager

# SOPS encryption
kubectl get secret -n flux-system sops-age
```

--------------------------------

### Validate Local Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/README.md

Use these commands to verify TOML syntax against CUE schemas and inspect computed configuration values.

```bash
# Check TOML syntax and CUE schema
cue export cluster.toml template/resources/config.schema.cue --out json

# See computed values and defaults
cue export cluster.toml template/resources/config.schema.cue --out json | jq .
```

--------------------------------

### Create Cloudflare Tunnel

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Initializes a new Cloudflare tunnel for external connectivity.

```bash
cloudflared tunnel create cluster
```

--------------------------------

### Debug Kubernetes API Access

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Troubleshooting steps for connection refused errors, focusing on kube-vip status and API server logs.

```bash
# Verify kube-vip is running
kubectl get pod -n kube-system -l app=kube-vip

# Check API server logs
talosctl logs -n <control-node-ip> kubelet | grep apiserver

# Verify VIP is assigned
ip addr show | grep <kubernetes.api.addr>
```

--------------------------------

### Monitor Flux Progress

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Observe the status of Kustomizations, HelmReleases, and view real-time Flux logs.

```bash
# Watch Kustomization status
kubectl get kustomization -n flux-system -o wide -w

# Check HelmRelease status
kubectl get helmrelease -n cert-manager
kubectl get helmrelease -n network

# View Flux logs
flux logs --follow --all-namespaces
```

--------------------------------

### Export Configuration via CUE

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/api-surface.md

Executes the cue_export function to validate and enrich configuration, or runs the underlying CLI command directly.

```python
def cue_export() -> dict[str, Any]
```

```bash
cue export cluster.toml template/resources/config.schema.cue --out json
```

--------------------------------

### Backup Age Key

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Displays the private key for secure storage.

```bash
cat age.key  # Note private key for backup
```

--------------------------------

### Validate configuration via CUE

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/quick-reference.md

Command used in the CI pipeline to validate the cluster configuration.

```bash
cue export
```

--------------------------------

### Read GitHub Deploy Key

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Retrieves a private key from a file for use in Kubernetes Secrets.

```python
def github_deploy_key(file_path: str = 'github-deploy.key') -> str
```

```jinja2
stringData:
  identity: |
    #{ github_deploy_key() }#
```

```text
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmU...
...
-----END OPENSSH PRIVATE KEY-----
```

--------------------------------

### Verify Cert-Manager Certificates

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

List all certificates across all namespaces to ensure they are valid.

```bash
kubectl get certificate -A
```

--------------------------------

### Monitor Cluster Rollout

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Watches the status of pods across all namespaces during the deployment.

```sh
kubectl get pods --all-namespaces --watch
```

--------------------------------

### Verify System Pods

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Ensure all pods within the kube-system namespace are running correctly.

```bash
kubectl get pods -n kube-system
```

--------------------------------

### Validate Rendered Manifests

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Run the kubeconform script to verify the generated Kubernetes manifests.

```bash
bash template/resources/kubeconform.sh
```

--------------------------------

### Apply Remaining Node Configurations

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Apply configurations to additional control plane and worker nodes.

```bash
# Apply control-1
talosctl apply-config --nodes 192.168.1.21 \
  --file talos/control-1.yaml

# Apply control-2
talosctl apply-config --nodes 192.168.1.22 \
  --file talos/control-2.yaml

# Apply workers (if any)
talosctl apply-config --nodes 192.168.1.30 \
  --file talos/worker-0.yaml
```

--------------------------------

### Sync Flux resources

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Commands to verify the status of Flux git sources, kustomizations, and helm releases.

```sh
flux get sources git -A
flux get ks -A
flux get hr -A
```

--------------------------------

### Verify Cilium Networking

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Test pod-to-pod connectivity using ping within the cluster.

```bash
kubectl exec -it <pod> -- ping <other-pod>
```

--------------------------------

### Validate Configuration with CUE

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

Use this command to validate the cluster.toml file against the specified CUE schema.

```bash
cue export cluster.toml template/resources/config.schema.cue --out json
```

--------------------------------

### Describe Certificates

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Displays the status of wildcard certificates in the network namespace.

```sh
kubectl -n network describe certificates
```

--------------------------------

### Apply Bootstrap Secrets

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Decrypt and apply SOPS-encrypted secrets to the cluster.

```bash
# Decrypt SOPS secrets and apply to cluster
kubectl apply -f bootstrap/sops-age.sops.yaml
kubectl apply -f bootstrap/github-deploy-key.sops.yaml

# Verify secrets
kubectl get secrets -n flux-system
```

--------------------------------

### Tidy up the repository

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Removes the template directory and related files to reduce clutter after initial configuration.

```sh
just template tidy
```

--------------------------------

### Define Repository Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/cue-schema.md

Specifies the GitHub repository details for Flux synchronization, including branch and visibility settings.

```cue
#Repository: {
    name: string
    branch: *"main" | string & !=""
    visibility: *"public" | "private"
}
```

--------------------------------

### Troubleshoot GitRepository Reconciliation

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Verify authentication secrets and GitHub token validity when GitRepository is stuck.

```bash
# Check authentication
kubectl get secret github-deploy-key -n flux-system
kubectl describe gitrepository cluster-state -n flux-system

# Verify GitHub token
echo $GITHUB_TOKEN | gh auth verify
```

--------------------------------

### Plugin.data()

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Returns the fully processed configuration data for template rendering, including computed defaults.

```APIDOC
## Plugin.data()

### Description
Returns fully processed configuration data for template rendering.

### Returns
- **dict** - Configuration dictionary with CUE schema validation applied and computed fields like `default_gateway`.
```

--------------------------------

### Template Kubernetes and Talos Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Processes configuration files based on the cluster.toml settings.

```sh
just configure
```

--------------------------------

### Generate Deploy Key

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Creates an SSH key pair for repository access if using a private repository.

```bash
ssh-keygen -t ed25519 -f github-deploy.key -N ""
```

--------------------------------

### List namespace events

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

View events in a namespace sorted by creation timestamp to identify recent issues.

```sh
kubectl -n <namespace> get events --sort-by='.metadata.creationTimestamp'
```

--------------------------------

### Function: github_deploy_key

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/api-surface.md

Reads a GitHub deployment SSH private key from a file.

```APIDOC
## github_deploy_key(file_path: str = 'github-deploy.key') -> str

### Description
Read GitHub deployment SSH private key.

### Parameters
- **file_path** (str) - Optional - Path to SSH key (default: 'github-deploy.key')

### Returns
- **str** - Private key file contents (whitespace stripped)

### Raises
- FileNotFoundError, RuntimeError
```

--------------------------------

### github_deploy_key(file_path: str)

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Reads a GitHub deployment private key from a file, stripping whitespace for use in Kubernetes Secrets.

```APIDOC
## github_deploy_key(file_path: str)

### Description
Reads GitHub deployment private key from a file for use in Kubernetes Secret templates.

### Parameters
- **file_path** (str, optional) - Path to private key file. Default: 'github-deploy.key'

### Returns
- **str** - Contents of private key file, whitespace stripped.

### Example
```jinja2
stringData:
  identity: |
    #{ github_deploy_key() }#
```
```

--------------------------------

### Git Version Control Operations

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/quick-reference.md

Standard workflow for staging and committing rendered cluster configuration and manifests.

```bash
# Stage and commit rendered files
git add cluster.toml bootstrap/ kubernetes/ talos/ .sops.yaml
git commit -m "chore: initialize cluster configuration"
git push origin main

# GitHub Actions validates automatically
```

--------------------------------

### Retrieve Kubeconfig

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Fetch the Kubernetes configuration file from the control plane node.

```bash
talosctl kubeconfig -n $CONTROLPLANE_IP
```

--------------------------------

### Define template directory structure

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

The expected directory layout for template overrides and configuration files.

```text
template/
├── overrides/      (processed first)
│   └── readme.partial.yaml.j2
└── config/         (processed second)
    ├── bootstrap/
    ├── kubernetes/
    └── talos/
```

--------------------------------

### Define the #Network schema

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/cue-schema.md

Defines the physical LAN configuration requirements including CIDR blocks and server lists.

```cue
#Network: {
    node_cidr: net.IPCIDR
    dns_servers: [...net.IPv4]
    ntp_servers: [...net.IPv4]
    default_gateway?: net.IPv4 & !=""
    vlan_tag?: string & !=""
}
```

--------------------------------

### SOPS configuration and secret creation

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Configures SOPS creation rules and defines secret data using age keys.

```yaml
creation_rules:
  - path_regex: talos/.*\.sops\.ya?ml
    age: "#{ age_key('public') }#"
```

```yaml
stringData:
  age-secret: |
    #{ age_key('private') }#
```

--------------------------------

### Define Gateway IP Configuration

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/cue-schema.md

Defines the required IPv4 addresses for internal, DNS, and external gateways.

```cue
#Gateways: {
    internal: net.IPv4
    dns: net.IPv4
    external: net.IPv4
}
```

--------------------------------

### Enable TPM Disk Encryption

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Set encrypt_disk to true in the node configuration within cluster.toml to trigger disk encryption on the next reboot.

```toml
[[nodes]]
...
encrypt_disk = true
```

--------------------------------

### Verify Flux GitRepository

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Check the status and details of the GitRepository resource within the flux-system namespace.

```bash
kubectl get gitrepository -n flux-system
kubectl describe gitrepository -n flux-system cluster-state
```

--------------------------------

### SOPS Configuration Template

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/template-structure.md

Jinja2 template for defining SOPS encryption rules, followed by the rendered output.

```jinja2
---
creation_rules:
  - path_regex: talos/.*\.sops\.ya?ml
    mac_only_encrypted: true
    age: "#{ age_key('public') }#"
  - path_regex: (bootstrap|kubernetes)/.*\.sops\.ya?ml
    encrypted_regex: "^(data|stringData)$"
    mac_only_encrypted: true
    age: "#{ age_key('public') }#"
```

```yaml
---
creation_rules:
  - path_regex: talos/.*\.sops\.ya?ml
    mac_only_encrypted: true
    age: age1abc123def456...xyz789
  - path_regex: (bootstrap|kubernetes)/.*\.sops\.ya?ml
    encrypted_regex: "^(data|stringData)$"
    mac_only_encrypted: true
    age: age1abc123def456...xyz789
```

--------------------------------

### Check Node Status

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Verify that the Kubernetes API is ready and nodes are reporting status.

```bash
kubectl get nodes
# Wait until all nodes appear with Ready status
```

--------------------------------

### Download Tunnel Credentials

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Copies the generated tunnel credentials into the project directory.

```bash
cp ~/.cloudflared/<tunnel-id>.json cloudflare-tunnel.json
```

--------------------------------

### Define Python script directory structure

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

The required directory structure for custom Python plugins to be discoverable by makejinja.

```text
template/
└── scripts/
    └── plugin.py  (importable as `plugin.Plugin`)
```

--------------------------------

### Configure SOPS Rules

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/generated-artifacts.md

Configuration file defining encryption rules and Age keys for SOPS-managed files.

```yaml
---
creation_rules:
  - path_regex: talos/.*\.sops\.ya?ml
    mac_only_encrypted: true
    age: age1abc123def456...xyz789
  - path_regex: (bootstrap|kubernetes)/.*\.sops\.ya?ml
    encrypted_regex: "^(data|stringData)$"
    mac_only_encrypted: true
    age: age1abc123def456...xyz789
stores:
  yaml:
    indent: 2
```

--------------------------------

### Access Template Configuration Schema

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/template-structure.md

The structure of the configuration dictionary available to all Jinja2 templates.

```python
{
  'network': {...},
  'kubernetes': {...},
  'gateways': {...},
  'repository': {...},
  'cloudflare': {...},
  'cilium': {...},
  'nodes': [...],
  'spegel_enabled': bool,
  'cilium_bgp_enabled': bool
}
```

--------------------------------

### Verify Node Discoverability

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Use nmap to check for active Talos nodes on the network.

```bash
nmap -Pn -n -p 50000 192.168.1.0/24 -vv | grep 'Discovered'
```

--------------------------------

### Backup Cluster State

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Exports kubeconfig, all Kubernetes manifests, secrets, and Talos machine configurations for disaster recovery.

```bash
# Save kubeconfig
kubectl config view > backup-kubeconfig.yaml

# Save all manifests
kubectl get all --all-namespaces -o yaml > backup-all.yaml

# Save secrets (encrypted with SOPS)
kubectl get secret --all-namespaces -o yaml | sops -e -d > backup-secrets.yaml

# Save Talos machine configs
for ip in 192.168.1.20 192.168.1.21 192.168.1.22; do
  talosctl read /var/lib/talos/config.yaml -n $ip > backup-talos-$ip.yaml
done
```

--------------------------------

### Verify Cluster Node Status

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/deployment-guide.md

Check that all nodes in the cluster are in the Ready state.

```bash
kubectl get nodes
```

--------------------------------

### Plugin Class Signature

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/api-surface.md

The base class structure for the makejinja plugin.

```python
class Plugin(makejinja.plugin.Plugin):
    def __init__(self, data: dict[str, Any]) -> None
    def data(self) -> makejinja.plugin.Data
    def filters(self) -> makejinja.plugin.Filters
    def functions(self) -> makejinja.plugin.Functions
```

--------------------------------

### Verify DNS Resolution

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Tests DNS resolution for the echo service. Replace placeholder variables with actual values.

```sh
dig @${gateways_dns} echo.${cloudflare_domain}
```

--------------------------------

### Check TCP Connectivity

Source: https://github.com/onedr0p/cluster-template/blob/main/README.md

Tests connectivity to internal and external gateways. Replace placeholder variables with actual values before execution.

```sh
nmap -Pn -n -p 443 ${gateways_internal} ${gateways_external} -vv
```

--------------------------------

### Plugin.functions()

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/plugin-api.md

Returns the list of function callables available to Jinja2 templates.

```APIDOC
## Plugin.functions()

### Description
Returns list of function callables available to Jinja2 templates.

### Returns
- **list** - `[age_key, cloudflare_tunnel_id, cloudflare_tunnel_secret, github_deploy_key, github_push_token, talos_patches]`
```

--------------------------------

### Configuration Data Structure

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/makejinja-config.md

The Python dictionary representation of the configuration data used for template rendering.

```python
{
  'kubernetes': {
    'pod_cidr': '10.42.0.0/16'
  },
  'cloudflare': {
    'domain': 'example.com'
  }
}
```

--------------------------------

### Define Default Values

Source: https://github.com/onedr0p/cluster-template/blob/main/_autodocs/cue-schema.md

Sets default values using the * operator, allowing overrides with the | _ syntax.

```cue
pod_cidr: *"10.42.0.0/16" | net.IPCIDR
dns_servers: *["1.1.1.1", "1.0.0.1"] | _
```