### Install kubelogin via Krew

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Installs the kubelogin CLI tool using the kubectl krew plugin manager. This is a common method for managing kubectl plugins.

```bash
# Krew (macOS, Linux, Windows and ARM)
kubectl krew install oidc-login
```

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

### Install kubelogin via Chocolatey

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Installs the kubelogin CLI tool using the Chocolatey package manager on Windows. This is a convenient option for Windows users.

```bash
# Chocolatey (Windows)
choco install kubelogin
```

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

### Install kubelogin via Homebrew

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Installs the kubelogin CLI tool using the Homebrew package manager. This tool is used for OIDC authentication with kubectl.

```bash
# Homebrew (macOS and Linux)
brew install kubelogin
```

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

### Hetzner Cloud Token Example

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/api-reference.md

Example of how to provide the Hetzner Cloud API token. This is a sensitive variable and should be managed securely.

```hcl
hcloud_token = var.hcloud_api_token  # From environment or secrets
```

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

### Cluster Name Example

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/api-reference.md

Example of how to set the cluster_name input variable. This name must be unique and adhere to specific naming constraints.

```hcl
cluster_name = "production-k8s"
```

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

### Initialize and Apply Terraform/OpenTofu Configuration

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Use these commands to initialize your Terraform or OpenTofu environment and apply the cluster configuration defined in your .tf files. Ensure you have the necessary prerequisites installed.

```sh
terraform init -upgrade
terraform apply
```

```sh
tofu init -upgrade
tofu apply
```

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

### Verify Cilium CNI Installation

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Confirm that the Cilium CNI (Container Network Interface) is installed and running correctly in the 'kube-system' namespace.

```bash
# Verify Cilium CNI
kubectl -n kube-system get ds cilium
```

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

### Get Kubernetes API Information

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Retrieve information about the Kubernetes API server and its components.

```bash
# Get API info
kubectl cluster-info
```

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

### Control Plane Nodepools Example

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/api-reference.md

Example configuration for control_plane_nodepools. Specifies node attributes like name, type, location, and count. Validation rules apply to names, counts, and locations.

```hcl
control_plane_nodepools = [
  {
    name     = "control"
    type     = "cpx22"
    location = "nbg1"
    count    = 3
  },
  {
    name     = "control-fsn"
    type     = "cpx22"
    location = "fsn1"
    count    = 1
  }
]
```

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

### Setup OIDC Authentication with kubectl

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Configures kubectl to use OIDC authentication by setting up the necessary issuer URL, client ID, and other parameters. This command typically opens a browser for authentication.

```bash
kubectl oidc-login setup \
  --oidc-issuer-url=https://your-oidc-provider.com \
  --oidc-client-id=your-client-id \
  --oidc-client-secret=your-client-secret \
  --oidc-extra-scope=openid,email,profile             # Add or change the scopes according to your IDP
```

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

### Kubernetes Network Policy Example

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Example of a Kubernetes NetworkPolicy to allow ingress traffic only from pods with specific labels to a target pod.

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: app-policy
spec:
  podSelector:
    matchLabels:
      app: myapp
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              role: frontend
      ports:
        - protocol: TCP
          port: 8080
```

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

### Switch to OIDC Context and Authenticate

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Switch to the OIDC context and perform an action like 'kubectl get pods' to trigger OIDC authentication. This command will initiate the authentication flow with your identity provider.

```bash
kubectl config use-context your-cluster-oidc
kubectl get pods  # This will trigger OIDC authentication
```

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

### Describe a Network Policy

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Get detailed information about a specific network policy in a given namespace.

```bash
# Describe a policy
kubectl describe networkpolicy my-policy -n default
```

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

### TrustedCertificate Example

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/types.md

Example of how to define trusted CA certificates. Keys must be lowercase alphanumeric with hyphens. Values can be a single PEM string or a list of PEM strings loaded from files.

```hcl
talos_certificates = {
  "corporate-ca" = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  "ca-chain" = [
    file("root.crt"),
    file("intermediate.crt")
  ]
}
```

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

### Example OIDC JWT Token

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

An example of a JSON Web Token (JWT) returned after successful OIDC authentication. This token contains user and group information used by Kubernetes.

```json
{
  "aud": "your-client-id",
  "email": "user@example.com",
  "email_verified": true,
  "exp": 1749867571,
  "groups": [
    "developers",
    "kubernetes-users"
  ],
  "iat": 1749863971,
  "iss": "https://your-oidc-provider.com",
  "nonce": "random-nonce-string",
  "sub": "user-unique-identifier"
}
```

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

### Hetzner Cloud Kubernetes Module Usage

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/configuration.md

Example of how to configure and deploy a Kubernetes cluster on Hetzner Cloud using the provided Terraform module. This includes basic cluster settings, node pool configurations, enabling optional components like Cilium Gateway API, Cert-Manager, Longhorn, and Cluster Autoscaler, as well as Talos and Kubernetes version specifications, firewall rules, API load balancing, and OIDC authentication.

```hcl
module "kubernetes" {
  source  = "hcloud-k8s/kubernetes/hcloud"
  version = "1.0.0"

  cluster_name = "my-cluster"
  hcloud_token = var.hcloud_token

  cluster_kubeconfig_path  = "kubeconfig"
  cluster_talosconfig_path = "talosconfig"

  network_ipv4_cidr = "10.0.0.0/16"

  control_plane_nodepools = [
    {
      name     = "control"
      type     = "cpx22"
      location = "nbg1"
      count    = 3
    }
  ]

  worker_nodepools = [
    {
      name     = "worker"
      type     = "cpx22"
      location = "nbg1"
      count    = 3
    }
  ]

  # Enable optional components
  cilium_gateway_api_enabled = true
  cert_manager_enabled       = true
  longhorn_enabled           = true
  cluster_autoscaler_enabled = true

  # Talos and Kubernetes configuration
  talos_version      = "v1.13.5"
  kubernetes_version = "v1.34.9"

  # Firewall rules for external access
  firewall_use_current_ipv4 = true
  firewall_use_current_ipv6 = false

  # API load balancer for high availability
  kube_api_load_balancer_enabled = true

  # OIDC authentication
  oidc_enabled    = true
  oidc_issuer_url = "https://auth.example.com"
  oidc_client_id  = "my-client-id"
}

```

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

### Monitor Cluster Infrastructure IPs

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

List control plane and worker node IPs, and retrieve the API load balancer endpoint for monitoring and setup purposes.

```bash
# List all node IPs for monitoring setup
echo "Control Plane IPs:"
terraform output -json control_plane_public_ipv4_list | jq -r '.[]'
```

```bash
echo "Worker IPs:"
terraform output -json worker_public_ipv4_list | jq -r '.[]'
```

```bash
# Get API load balancer endpoint
terraform output -json kube_api_load_balancer | \
  jq -r '.public_ipv4 + ":" + "6443"'
```

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

### Minimal Kubernetes Cluster Configuration

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

This is the most basic configuration to get a Kubernetes cluster running on Hetzner Cloud. It defines essential parameters like the source, version, cluster name, API token, and node pool configurations for both control plane and workers. The outputs provide access to the kubeconfig and talosconfig.

```hcl
module "kubernetes" {
  source  = "hcloud-k8s/kubernetes/hcloud"
  version = "~> 1.0"

  cluster_name = "my-cluster"
  hcloud_token = var.hcloud_token

  control_plane_nodepools = [
    { name = "control", type = "cpx22", location = "nbg1", count = 1 }
  ]

  worker_nodepools = [
    { name = "worker", type = "cpx22", location = "nbg1", count = 1 }
  ]
}

output "kubeconfig" {
  value       = module.kubernetes.kubeconfig
  sensitive   = true
}

output "talosconfig" {
  value       = module.kubernetes.talosconfig
  sensitive   = true
}
```

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

### Initialize Terraform

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Use this command to initialize your Terraform working directory. It downloads the necessary provider plugins.

```bash
terraform init
```

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

### Deploy Applications with kubectl

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Create a namespace and apply Kubernetes manifests to deploy your applications. Ensure your application YAML files are correctly configured.

```bash
kubectl create namespace my-app
kubectl apply -f app.yaml -n my-app
```

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

### Test External Connectivity

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Verify external network connectivity from within a pod by attempting to fetch a resource from example.com.

```bash
# Test external connectivity
/ # wget -O- http://example.com
```

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

### Create HTTPRoute for example.com

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Defines routing rules for a hostname, forwarding traffic to a specified Kubernetes service and port. Ensure the parent Gateway is correctly configured.

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-app
  namespace: default
spec:
  hostnames:
    - example.com
  parentRefs:
    - name: cilium-gateway
      namespace: default
  rules:
    - backendRefs:
        - name: example-service
          port: 8080
```

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

### Configure Cert Manager

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/components.md

Set up Cert Manager for automated certificate lifecycle management. Requires Helm repository and chart details.

```hcl
cert_manager_enabled = false

cert_manager_helm_repository = "https://charts.jetstack.io"
cert_manager_helm_chart      = "cert-manager"
cert_manager_helm_version    = "v1.16.1"
cert_manager_helm_values     = {}

cert_manager_replicas = 2
```

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

### Module Entry Point

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/api-reference.md

Standard Terraform syntax to access the Kubernetes module.

```hcl
module "kubernetes" {
  source = "hcloud-k8s/kubernetes/hcloud"
  # ... configuration
}
```

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

### Get Talos Node Status

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Check the current status of the Talos nodes in your cluster.

```bash
# Get node status
talosctl status
```

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

### KernelModule

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/types.md

Configures kernel modules to be loaded on boot, including the module name and optional parameters.

```APIDOC
## KernelModule

### Description
Kernel module configuration for loading on boot.

### Fields
- **name** (string) - Required - Name of the kernel module to load
- **parameters** (list(string)) - Optional - Optional parameters to pass to the module
```

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

### List All Network Policies

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Retrieve a list of all network policies across all namespaces.

```bash
# List all network policies
kubectl get networkpolicies --all-namespaces
```

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

### Terraform Variable Definitions

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Example definitions for Terraform variables, including type, description, default values, and validation rules.

```hcl
# variables.tf
variable "cluster_name" {
  type        = string
  description = "Kubernetes cluster name"
  default     = "my-cluster"
}

variable "hcloud_token" {
  type        = string
  description = "Hetzner Cloud API token"
  sensitive   = true
}

variable "node_count" {
  type        = number
  description = "Number of worker nodes"
  default     = 3
  
  validation {
    condition     = var.node_count >= 1 && var.node_count <= 100
    error_message = "Node count must be between 1 and 100."
  }
}
```

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

### Check Kubernetes Storage Classes

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

View the available storage classes, which define different types of storage that can be provisioned.

```bash
# Check storage classes
kubectl get storageclass
```

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

### Pod Egress Bandwidth Limit

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Set a maximum egress bandwidth for a Pod using Cilium annotations. This example limits the Pod to 10 Mbps.

```yaml
apiVersion: v1
kind: Pod
metadata:
  annotations:
    cilium.io/egress-bandwidth: "10M"  # 10 Mbps limit
spec:
  containers:
    - name: app
      image: myapp:latest
```

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

### Get Talosconfig Data Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Retrieve structured Talos configuration data for programmatic access. This sensitive output is useful for custom scripts and tooling for Talos management.

```terraform
output "talosconfig_data" {
  description = "Structured Talos configuration data, suitable for use with other Terraform providers or tools."
  value       = local.talosconfig_data
  sensitive   = true
}
```

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

### Talos Worker Machine Configurations Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Outputs the Talos machine configurations for all worker nodes. This is sensitive and useful for debugging worker node configurations and validating the setup.

```terraform
output "talos_machine_configurations_worker" {
  description = "Talos machine configurations for all worker nodes."
  value       = data.talos_machine_configuration.worker
  sensitive   = true
}
```

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

### Test Pod-to-Pod Connectivity

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Test pod-to-pod connectivity by running a busybox container and attempting to access the Kubernetes service.

```bash
# Test pod-to-pod connectivity
kubectl run test-pod --image=busybox --rm -it -- sh
/ # wget -O- http://kubernetes.default
/ # nslookup kubernetes.default
```

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

### Define Kubelet Mount Configuration

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/types.md

Use this object to configure extra mount points for the Kubelet. Ensure destinations are unique and avoid '/var/lib/longhorn' if Longhorn is enabled.

```hcl
object({
  source      = string
  destination = optional(string)
  type        = optional(string, "bind")
  options     = optional(list(string), ["bind", "rshared", "rw"])
})
```

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

### Add Custom Labels to Worker Nodes

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Assign custom labels to worker nodes for easier identification and selection. This example labels nodes with workload type and performance tier.

```hcl
worker_nodepools = [
  {
    name   = "compute"
    type   = "cpx41"
    location = "nbg1"
    count  = 3
    labels = {
      workload-type = "compute"
      performance   = "high"
    }
  }
]
```

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

### Define Kernel Module Configuration

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/types.md

Configure kernel modules to be loaded on boot using this object. Specify the module name and any optional parameters.

```hcl
object({
  name       = string
  parameters = optional(list(string))
})
```

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

### Verify Kubernetes System Namespaces

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

List all namespaces in the Kubernetes cluster to identify system-related ones.

```bash
# Check system namespaces
kubectl get ns
```

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

### Customize Helm Chart Values for Components

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/components.md

Override default Helm chart values for specific components to customize their behavior and configuration. This example shows Cilium and Cert Manager customizations.

```hcl
# Cilium customization
cilium_helm_values = {
  metrics = {
    enabled = true
  }
  bpf = {
    masquerade = "eBPF"
  }
}

# Cert Manager customization
cert_manager_helm_values = {
  global = {
    leaderElection = {
      enabled = true
    }
  }
}
```

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

### Access Talosconfig and Set Environment Variable

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Outputs the talosconfig content and saves it to a file, then sets the TALOSCONFIG environment variable to use it.

```bash
terraform output -raw talosconfig > talosconfig
export TALOSCONFIG=$PWD/talosconfig
```

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

### Terraform Variable Assignments

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Example of assigning values to Terraform variables using a .tfvars file. Sensitive variables like API tokens should ideally be managed via environment variables.

```hcl
# terraform.tfvars (or -var flags)
cluster_name = "production"
hcloud_token = "..."  # Use environment variable instead!
```

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

### Access Kubeconfig and Set Environment Variable

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Outputs the kubeconfig content and saves it to a file, then sets the KUBECONFIG environment variable to use it.

```bash
terraform output -raw kubeconfig > kubeconfig
export KUBECONFIG=$PWD/kubeconfig
```

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

### Add Custom Taints to Control Plane Nodes

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Apply custom taints to control plane nodes to control pod scheduling. This example taints control plane nodes with 'NoSchedule'.

```hcl
control_plane_nodepools = [
  {
    name   = "control"
    type   = "cpx22"
    location = "nbg1"
    count  = 3
    taints = [
      "node-role.kubernetes.io/control-plane=:NoSchedule"
    ]
  }
]
```

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

### Verify Metrics Server Deployment

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Ensure the metrics-server is deployed and running, which is essential for collecting resource metrics.

```bash
# Verify metrics server
kubectl -n kube-system get deploy metrics-server
```

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

### Get Kubeconfig Data Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Retrieve structured kubeconfig data for programmatic access. This sensitive output is suitable for use with other Terraform providers or tools that require structured authentication information.

```terraform
output "kubeconfig_data" {
  description = "Structured kubeconfig data, suitable for use with other Terraform providers or tools."
  value       = local.kubeconfig_data
  sensitive   = true
}
```

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

### Get Kubeconfig Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Retrieve the raw kubeconfig file for authenticating with the Kubernetes cluster. This sensitive output can be written to a file using the `cluster_kubeconfig_path` input variable and is suitable for use with `kubectl`.

```terraform
output "kubeconfig" {
  description = "Raw kubeconfig file for authenticating with the Kubernetes cluster."
  value       = local.kubeconfig
  sensitive   = true
}
```

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

### Configure Kubernetes Provider with Module Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/api-reference.md

Set up the Kubernetes provider to connect to the managed cluster using outputs from the Kubernetes module. This includes host, token, and certificate authority data for authentication.

```hcl
provider "kubernetes" {
  host  = module.kubernetes.kubeconfig_data.clusters[0].cluster.server
  token = module.kubernetes.kubeconfig_data.users[0].user.token
  cluster_ca_certificate = base64decode(
    module.kubernetes.kubeconfig_data.clusters[0].cluster.certificate-authority-data
  )
}

resource "kubernetes_namespace" "example" {
  metadata {
    name = "example"
  }
}
```

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

### Configure Persistent Storage with kubectl

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

View available storage classes and apply PersistentVolumeClaim (PVC) manifests to configure persistent storage for your applications. Ensure a StorageClass is available.

```bash
kubectl get storageclass
kubectl apply -f pvc.yaml
```

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

### Use Kubeconfig Directly with kubectl

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Pipes the raw kubeconfig output directly to kubectl for immediate use, without saving to a file. This is convenient for temporary access.

```bash
# Or use directly
export KUBECONFIG=/dev/stdin
terraform output -raw kubeconfig | kubectl cluster-info
```

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

### Get Talos Machine Secrets Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Retrieve Talos machine secrets for bootstrapping additional nodes or disaster recovery. This sensitive output contains cryptographic material and must be stored securely.

```terraform
output "talos_machine_secrets" {
  description = "Talos machine secret, suitable for use with other Terraform providers or tools."
  value       = talos_machine_secrets.this.machine_secrets
  sensitive   = true
}
```

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

### Get Talos Client Configuration Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Retrieve detailed configuration data for the Talos client. This sensitive output is useful for creating additional Talos client connections or integrating with Talos-based automation.

```terraform
output "talos_client_configuration" {
  description = "Detailed configuration data for the Talos client."
  value       = data.talos_client_configuration.this
  sensitive   = true
}
```

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

### Configure NGINX Ingress Controller

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/components.md

Set up NGINX Ingress Controller for Kubernetes-native HTTP/HTTPS ingress management. Requires Helm configuration and replica count for HA.

```hcl
ingress_nginx_enabled = false

ingress_nginx_helm_repository = "https://kubernetes.github.io/ingress-nginx"
ingress_nginx_helm_chart      = "ingress-nginx"
ingress_nginx_helm_version    = "4.11.3"
ingress_nginx_helm_values     = {}

ingress_nginx_replica_count = 2  # For HA
```

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

### Talos Control Plane Machine Configurations Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Outputs the Talos machine configurations for all control plane nodes. This is sensitive and useful for debugging node-specific configurations and auditing the control plane setup.

```terraform
output "talos_machine_configurations_control_plane" {
  description = "Talos machine configurations for all control plane nodes."
  value       = data.talos_machine_configuration.control_plane
  sensitive   = true
}
```

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

### Get Talosconfig Output

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Retrieve the raw Talos OS configuration file for cluster access and management. This sensitive output can be written to a file using the `cluster_talosconfig_path` input variable and is intended for use with `talosctl`.

```terraform
output "talosconfig" {
  description = "Raw Talos OS configuration file used for cluster access and management."
  value       = local.talosconfig
  sensitive   = true
}
```

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

### Set Cluster Access Environment Variables

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Configure your shell environment to point to the generated Talos and Kubernetes configuration files. This allows `talosctl` and `kubectl` to connect to your cluster.

```sh
export TALOSCONFIG=talosconfig
export KUBECONFIG=kubeconfig
```

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

### Configure Talos Backups with Other Object Storage Providers

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Configure your Kubernetes.tf file for Talos backups using a generic object storage provider. This requires specifying region, endpoint, bucket, and credentials. Path-style URLs and encryption can also be configured.

```hcl
talos_backup_s3_region   = "<region>"
talos_backup_s3_endpoint = "<endpoint>"
talos_backup_s3_bucket   = "<bucket>"
talos_backup_s3_prefix   = "<prefix>"

# Use path-style URLs (set true if required by your provider)
talos_backup_s3_path_style = true

# Access credentials
talos_backup_s3_access_key = "<access-key>"
talos_backup_s3_secret_key = "<secret-key>"

# Optional: AGE X25519 Public Key for encryption
talos_backup_age_x25519_public_key = "<age-public-key>"

# Optional: Change schedule (cron syntax)
talos_backup_schedule = "0 * * * *"
```

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

### View Talos Logs

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Access logs from the Talos controller-runtime to troubleshoot issues.

```bash
# View logs
talosctl logs -e controller-runtime
```

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

### Create Hcloud Object Storage Bucket with Retention

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Create a new bucket with versioning and a default governance retention policy using the MinIO Client. This protects your backups by preventing accidental deletion.

```sh
mc mb --with-lock --region <location> <alias>/<bucket>
mc retention set GOVERNANCE 14d --default <alias>/<bucket>
```

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

### Set up MinIO Client Alias for Hcloud Object Storage

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Create an alias for your Hcloud Object Storage endpoint using the MinIO Client. Ensure you replace placeholders with your actual credentials and location.

```sh
mc alias set <alias> \
  https://<location>.your-objectstorage.com \
  <access-key> <secret-key> \
  --api "s3v4" \
  --path "off"
```

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

### Use Talosconfig Directly with talosctl

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Pipes the raw talosconfig output directly to talosctl for immediate use, without saving to a file. This is convenient for temporary access to Talos nodes.

```bash
# Or use directly
terraform output -raw talosconfig | talosctl --talosconfig=/dev/stdin nodes
```

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

### KubeletMount

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/types.md

Defines extra mount configurations for Kubelet, specifying source, destination, type, and options.

```APIDOC
## KubeletMount

### Description
Kubelet extra mount configuration.

### Fields
- **source** (string) - Required - mount source
- **destination** (string) - Optional - Defaults to source. Destination path.
- **type** (string) - Optional - Defaults to "bind". Mount type.
- **options** (list(string)) - Optional - Defaults to ["bind", "rshared", "rw"]. Mount options.

### Validation Constraints
- Each destination must be unique
- If Longhorn is enabled, "/var/lib/longhorn" cannot be used as destination
```

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

### Configure Persistent Storage

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Enable Hetzner Cloud CSI (Container Storage Interface) for persistent storage. Optionally enable encryption for data at rest.

```hcl
hcloud_csi_enabled = true
hcloud_csi_encryption_enabled = true
```

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

### Configure Cert Manager Webhook for Hetzner DNS

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/components.md

Enable DNS-01 ACME challenges using Hetzner DNS with Cert Manager. Requires Helm configuration.

```hcl
cert_manager_webhook_hetzner_enabled = false

cert_manager_webhook_hetzner_helm_repository = "https://charts.hetzner.cloud"
cert_manager_webhook_hetzner_helm_chart      = "cert-manager-webhook-hetzner"
cert_manager_webhook_hetzner_helm_version    = "1.15.0"
cert_manager_webhook_hetzner_helm_values     = {}
```

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

### Enable Talos Backup Configuration

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/api-reference.md

Configure hourly backups to an S3 bucket using Talos. Ensure your S3 endpoint, bucket name, and region are correctly set.

```hcl
module "kubernetes" {
  # ... other configuration
  
  talos_backup_enabled       = true
  talos_backup_s3_bucket     = "my-backup-bucket"
  talos_backup_s3_endpoint   = "s3.hetzner.com"
  talos_backup_s3_region     = "fsn1"
  talos_backup_schedule      = "0 * * * *"  # Hourly
}
```

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

### Define Static Host Mapping

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/types.md

Use this object to define a static host mapping for DNS-like resolution. Specify the IP address and a list of hostnames.

```hcl
object({
  ip        = string          # Required: IP address (IPv4 or IPv6)
  hostnames = list(string)    # Required: list of hostnames
})
```

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

### Configure Load Balancer Algorithm

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Set the load balancer algorithm type. 'least_connections' is recommended for long-lived connections, while 'round_robin' is better for short-lived ones.

```hcl
hcloud_ccm_load_balancers_algorithm_type = "least_connections"  # Better for long connections
# vs "round_robin"                                                # Better for short-lived
```

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

### Describe Hetzner Cloud Firewall

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Retrieve details about a specific Hetzner Cloud firewall using its ID.

```bash
# Check applied firewall rules
hcloud firewall describe <firewall-id>
```

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

### Enable Dual-Stack Networking

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Enable both IPv4 and IPv6 networking. This configuration enables IPv6 on Talos, public IPv6 assignment, and within Cilium.

```hcl
talos_ipv6_enabled        = true   # IPv6 on Talos
talos_public_ipv6_enabled = true   # Public IPv6 assignment
cilium_ipv6_enabled       = true   # IPv6 in Cilium

```

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

### Configure Talos Backup

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/components.md

Enable and configure automated ETCD backups to S3 storage. Set S3 credentials, region, bucket, and optionally enable encryption and compression. The schedule can be defined using cron syntax.

```hcl
talos_backup_enabled = true

talos_backup_version = "v0.1.0-beta.3-3-g38dad7c"

# S3 Configuration
talos_backup_s3_hcloud_url = null        # Hetzner S3 URL
talos_backup_s3_region     = null        # S3 region
talos_backup_s3_endpoint   = null        # Custom S3 endpoint
talos_backup_s3_bucket     = null        # Bucket name
talos_backup_s3_prefix     = null        # Path prefix
talos_backup_s3_path_style = false       # Use path-style URLs

# Credentials (sensitive)
talos_backup_s3_access_key = ""
talos_backup_s3_secret_key = ""

# Encryption
talos_backup_age_x25519_public_key = null

# Compression
talos_backup_enable_compression = false

# Schedule
talos_backup_schedule = "0 * * * *"      # Hourly by default
```

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

### Configure kubectl for OIDC User

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Add a new user to your ~/.kube/config file for OIDC authentication. Ensure your OIDC provider details are correctly configured.

```yaml
users:
- name: oidc-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubectl
      args:
        - oidc-login
        - get-token
        - --oidc-issuer-url=https://your-oidc-provider.com
        - --oidc-client-id=your-client-id
        - --oidc-client-secret=your-client-secret
        - --oidc-extra-scope=groups
        - --oidc-extra-scope=email
        - --oidc-extra-scope=name                           # Add or change the scopes according to your IDP
```

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

### Create Kubernetes Gateway with Hetzner Load Balancer Annotations

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Defines the external entry point for traffic using the Cilium Gateway controller. Hetzner-specific annotations control the creation and configuration of the Hetzner Cloud Load Balancer. The cert-manager.io/issuer annotation is crucial for TLS termination.

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cilium-gateway
  namespace: default
  annotations:
    cert-manager.io/issuer: letsencrypt-http01
spec:
  gatewayClassName: cilium
  infrastructure:
    annotations:
      load-balancer.hetzner.cloud/name: "cilium-gateway-nbg1"
      load-balancer.hetzner.cloud/location: "nbg1"
      load-balancer.hetzner.cloud/uses-proxyprotocol: "true"
  listeners:
    - name: https
      hostname: example.com
      port: 443
      protocol: HTTPS
      allowedRoutes:
        namespaces:
          from: All
      tls:
        mode: Terminate
        certificateRefs:
          - name: example-com-tls
            kind: Secret
            group: ""
    - name: http
      hostname: example.com
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All
```

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

### Longhorn Optional Storage Configuration

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/components.md

Configure Longhorn as an optional distributed block storage solution. Set up Helm repository, chart, version, and values. Optionally configure Ingress.

```hcl
longhorn_enabled = false

longhorn_helm_repository = "https://charts.longhorn.io"
longhorn_helm_chart      = "longhorn"
longhorn_helm_version    = "1.8.3"
longhorn_helm_values     = {}

longhorn_ingress_enabled = false
longhorn_ingress_class   = "cilium"  # or other ingress class
```

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

### Define Static Host Mappings

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Add custom static host-to-IP mappings for internal services. Supports both IPv4 and IPv6.

```hcl
talos_static_hosts = [
  {
    ip        = "10.0.0.1"
    hostnames = ["registry.internal", "api.internal"]
  },
  {
    ip        = "2001:db8::1"
    hostnames = ["ipv6-service.internal"]
  }
]
```

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

### Define Inline Kubernetes Manifest

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/types.md

Define an inline Kubernetes manifest for bootstrap purposes. Provide a unique name and the YAML content of the manifest.

```hcl
object({
  name     = string    # Required: manifest name/identifier
  contents = string    # Required: YAML manifest content
})
```

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

### Configure Reverse DNS (RDNS)

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Set up reverse DNS resolution patterns for cluster nodes and control plane nodepools. Allows for dynamic generation of RDNS names based on node attributes.

```hcl
cluster_rdns      = "{{ role }}.{{ pool }}.k8s.example.com"
cluster_rdns_ipv4 = "{{ pool }}-{{ id }}.ipv4.k8s.example.com"
cluster_rdns_ipv6 = "{{ pool }}-{{ id }}.ipv6.k8s.example.com"

control_plane_nodepools = [
  {
    name         = "control"
    rdns         = "control.{{ id }}.example.com"  # Override per-pool
    rdns_ipv4    = "control-v4.{{ id }}.example.com"
    rdns_ipv6    = "control-v6.{{ id }}.example.com"
    # ...
  }
]
```

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

### Configure Native Routing

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Set up non-SNAT native routing for specific IP ranges. Pods with IPs in the configured CIDR will not be masqueraded.

```hcl
network_native_routing_ipv4_cidr = "10.0.0.0/8"

```

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

### Watch Cilium Pod Logs

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/networking.md

Monitor network events by tailing the logs of Cilium pods in the kube-system namespace.

```bash
# Watch network events
kubectl -n kube-system logs -f -l k8s-app=cilium --tail=100
```

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

### Upgrade Kubernetes

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Upgrade the Kubernetes version running on your Talos nodes to a specified version.

```bash
# Upgrade Kubernetes
talosctl upgrade-k8s --to v1.X.Y
```

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

### List Talos Nodes

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Display a list of nodes managed by Talos, showing their IP addresses and other relevant information.

```bash
# List nodes
talosctl nodes
```

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

### Configure Multiple Trusted CA Certificates (List)

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/README.md

Add multiple custom CA certificates by referencing their file paths in a list. This is useful when you have several root or intermediate certificates to trust.

```hcl
talos_certificates = {
  "enterprise-ca" = [
    file("root.crt"),
    file("intermediate.crt")
  ]
}
```

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

### Plan Terraform Changes

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Generates an execution plan for Terraform. This shows what actions Terraform will take to achieve the desired state.

```bash
terraform plan
```

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

### Kubernetes Troubleshooting Commands

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Use these kubectl commands to check the health of your Kubernetes cluster, including nodes, pods, and events.

```bash
# Check cluster health
kubectl get nodes
kubectl get pods -A
kubectl get events -A --sort-by='.lastTimestamp'
```

```bash
# Check networking
kubectl run -it --image=busybox --restart=Never test -- sh
  # Inside pod:
  nslookup kubernetes.default
  wget -O- http://example.com
```

```bash
# Check persistent volumes
kubectl get pv
kubectl get pvc -A
kubectl describe pvc <name> -n <ns>
```

```bash
# Check ingress
kubectl get ing -A
kubectl describe ing <name> -n <ns>
```

```bash
# Check services
kubectl get svc -A
kubectl describe svc <name> -n <ns>
```

```bash
# Check certificates (if cert-manager enabled)
kubectl get cert -A
kubectl describe cert <name> -n <ns>
```

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

### Export Kubernetes and Talos Configurations

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Export the kubeconfig and talosconfig files after deployment to manage your cluster with kubectl and talosctl. Ensure the destination paths are correct.

```bash
terraform output -raw kubeconfig > ~/.kube/hcloud
terraform output -raw talosconfig > ~/.talos/hcloud
```

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

### Upgrade Talos

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/quick-reference.md

Upgrade the Talos operating system on your nodes to a specified image version.

```bash
# Upgrade Talos
talosctl upgrade --image ghcr.io/siderolabs/talos:vX.Y.Z
```

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

### talos_client_configuration

Source: https://github.com/hcloud-k8s/terraform-hcloud-kubernetes/blob/main/_autodocs/outputs.md

Provides the detailed configuration data for the Talos client. This output is sensitive and useful for creating additional Talos client connections or integrating with Talos-based automation.

```APIDOC
## talos_client_configuration

### Description
Detailed configuration data for the Talos client.

### Type
object

### Sensitive
true

### Use Case
Advanced Talos integrations and custom client implementations
```