### Example Usage of talos_machine_bootstrap

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine_bootstrap.md

This example demonstrates how to use the talos_machine_bootstrap resource to bootstrap a Talos node. It requires other resources like talos_machine_secrets and talos_machine_configuration to be defined first.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name     = "example-cluster"
  machine_type     = "controlplane"
  cluster_endpoint = "https://cluster.local:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}

data "talos_client_configuration" "this" {
  cluster_name         = "example-cluster"
  client_configuration = talos_machine_secrets.this.client_configuration
  nodes                = ["10.5.0.2"]
}

resource "talos_machine_configuration_apply" "this" {
  client_configuration        = talos_machine_secrets.this.client_configuration
  machine_configuration_input = data.talos_machine_configuration.this.machine_configuration
  node                        = "10.5.0.2"
  config_patches = [
    yamlencode({
      machine = {
        install = {
          disk = "/dev/sdd"
        }
      }
    })
  ]
}

resource "talos_machine_bootstrap" "this" {
  depends_on = [
    talos_machine_configuration_apply.this
  ]
  node                 = "10.5.0.2"
  client_configuration = talos_machine_secrets.this.client_configuration
}
```

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

### talos_machine_configuration_apply Resource Example

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine_configuration_apply.md

This example demonstrates how to use the talos_machine_configuration_apply resource to apply a machine configuration to a specific node. It requires pre-defined machine secrets and client configuration, and allows for custom configuration patches.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name     = "example-cluster"
  machine_type     = "controlplane"
  cluster_endpoint = "https://cluster.local:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}

data "talos_client_configuration" "this" {
  cluster_name         = "example-cluster"
  client_configuration = talos_machine_secrets.this.client_configuration
  nodes                = ["10.5.0.2"]
}

resource "talos_machine_configuration_apply" "this" {
  client_configuration        = talos_machine_secrets.this.client_configuration
  machine_configuration_input = data.talos_machine_configuration.this.machine_configuration
  node                        = "10.5.0.2"
  config_patches = [
    yamlencode({
      machine = {
        install = {
          disk  = "/dev/sdd"
          image = "ghcr.io/siderolabs/installer:v1.12.6"
        }
      }
    })
  ]
}
```

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

### Get Talos Image Factory Versions

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_versions.md

Use this data source to fetch a list of available Talos versions. The example shows how to configure the provider, declare the data source, and output the latest version from the returned list.

```terraform
provider "talos" {}

data "talos_image_factory_versions" "this" {}

output "latest" {
  value = element(data.talos_image_factory_versions.this.talos_versions, length(data.talos_image_factory_versions.this.talos_versions) - 1)
}
```

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

### Importing talos_machine_bootstrap

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine_bootstrap.md

This example shows how to import an existing machine bootstrap into Terraform state. This is useful to let Terraform manage a machine that has already been bootstrapped.

```terraform
# machine bootstrap can be imported to let terraform know that the machine is already bootstrapped
terraform import talos_machine_bootstrap.this <any id>
```

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

### Standard Talos Machine Configuration

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/guides/using_ephemeral_resources.md

Initial setup using standard data sources to generate and apply machine configurations.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name     = "my-cluster"
  cluster_endpoint = "https://10.5.0.2:6443"
  machine_type     = "controlplane"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}

resource "talos_machine_configuration_apply" "this" {
  client_configuration        = talos_machine_secrets.this.client_configuration
  machine_configuration_input = data.talos_machine_configuration.this.machine_configuration
  node                        = "10.5.0.2"
}
```

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

### Example Usage of talos_cluster_kubeconfig Data Source

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/cluster_kubeconfig.md

This example demonstrates how to use the talos_cluster_kubeconfig data source to retrieve the kubeconfig for a Talos cluster. It depends on several other resources being created first, including machine secrets, machine configuration, client configuration, machine configuration apply, and machine bootstrap.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name     = "example-cluster"
  machine_type     = "controlplane"
  cluster_endpoint = "https://cluster.local:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}

data "talos_client_configuration" "this" {
  cluster_name         = "example-cluster"
  client_configuration = talos_machine_secrets.this.client_configuration
  nodes                = ["10.5.0.2"]
}

resource "talos_machine_configuration_apply" "this" {
  client_configuration        = talos_machine_secrets.this.client_configuration
  machine_configuration_input = data.talos_machine_configuration.this.machine_configuration
  node                        = "10.5.0.2"
  config_patches = [
    yamlencode({
      machine = {
        install = {
          disk = "/dev/sdd"
        }
      }
    })
  ]
}

resource "talos_machine_bootstrap" "this" {
  depends_on = [
    talos_machine_configuration_apply.this
  ]
  node                 = "10.5.0.2"
  client_configuration = talos_machine_secrets.this.client_configuration
}


data "talos_cluster_kubeconfig" "this" {
  depends_on = [
    talos_machine_bootstrap.this
  ]
  client_configuration = talos_machine_secrets.this.client_configuration
  node                 = "10.5.0.2"
}
```

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

### Example Usage of talos_machine Resource

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine.md

This snippet demonstrates the full usage of the talos_machine resource, including its dependencies on talos_machine_secrets and talos_machine_configuration, and its role in bootstrapping a Talos node with talos_machine_bootstrap.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name     = "example-cluster"
  machine_type     = "controlplane"
  cluster_endpoint = "https://10.5.0.2:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
  config_patches = [
    yamlencode({
      machine = {
        install = {
          disk  = "/dev/sda"
          image = "ghcr.io/siderolabs/installer:v1.9.0"
        }
      }
    })
  ]
}

resource "talos_machine" "this" {
  node                  = "10.5.0.2"
  client_configuration  = talos_machine_secrets.this.client_configuration
  machine_configuration = data.talos_machine_configuration.this.machine_configuration
  image                 = "ghcr.io/siderolabs/installer:v1.9.0"
}

resource "talos_machine_bootstrap" "this" {
  depends_on           = [talos_machine.this]
  node                 = "10.5.0.2"
  client_configuration = talos_machine_secrets.this.client_configuration
}
```

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

### GET talos_image_factory_overlays_versions

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_overlays_versions.md

Retrieves a list of available overlays for a specified Talos version.

```APIDOC
## GET talos_image_factory_overlays_versions

### Description
The image factory overlays versions data source provides a list of available overlays for a specific talos version from the image factory.

### Parameters
#### Required
- **talos_version** (String) - The talos version to get overlays for.

#### Optional
- **filters** (Attributes) - The filter to apply to the overlays list.
  - **name** (String) - The name of the overlay to filter by.

### Response
#### Read-Only
- **id** (String) - The ID of this resource.
- **overlays_info** (List of Object) - The list of available extensions for the specified talos version.
  - **digest** (String)
  - **image** (String)
  - **name** (String)
  - **ref** (String)

### Request Example
```terraform
data "talos_image_factory_overlays_versions" "this" {
  talos_version = "v1.7.5"
  filters = {
    name = "rock4cplus"
  }
}
```
```

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

### Example Usage of talos_machine_disks Data Source

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/machine_disks.md

Demonstrates how to use the talos_machine_disks data source to retrieve disk information from a node and output the names of NVMe disks. This can be useful for passing disk lists to other resources like rook-ceph.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_disks" "this" {
  client_configuration = talos_machine_secrets.this.client_configuration
  node                 = "10.5.0.2"
  selector             = "disk.size > 6u * GB"
}

# for example, this could be used to pass in a list of disks to rook-ceph
output "nvme_disks" {
  value = data.talos_machine_disks.this.disks.*.name
}
```

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

### Configure Talos and Vault Providers

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/guides/using_ephemeral_resources.md

Initial setup for using the Talos and Vault providers with Terraform 1.11+.

```terraform
terraform {
  required_version = ">= 1.11"
  required_providers {
    talos = {
      source  = "siderolabs/talos"
      version = "~> 0.11"
    }
    vault = {
      source  = "hashicorp/vault"
      version = "~> 5.0"
    }
  }
}

# Step 1: Generate and store secrets in Vault
# The ephemeral resource generates secrets only when needed (first run)
```

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

### Create a Talos Image Schematic

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/image_factory_schematic.md

This example demonstrates how to create a Talos image schematic using the `talos_image_factory_schematic` resource. It first fetches available official extensions for a specific Talos version and then uses these extensions in the schematic definition. The `schematic` argument accepts a YAML-encoded string.

```terraform
provider "talos" {}

data "talos_image_factory_extensions_versions" "this" {
  # get the latest talos version
  talos_version = "v1.7.5"
  filters = {
    names = [
      "amdgpu",
      "tailscale",
    ]
  }
}

resource "talos_image_factory_schematic" "this" {
  schematic = yamlencode(
    {
      customization = {
        systemExtensions = {
          officialExtensions = data.talos_image_factory_extensions_versions.this.extensions_info.*.name
        }
      }
    }
  )
}

output "schematic_id" {
  value = talos_image_factory_schematic.this.id
}
```

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

### talos_machine_configuration Data Source Example

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/machine_configuration.md

Use this data source to generate a machine configuration for a specific node type within a Talos cluster. Ensure 'talos_machine_secrets' is configured to provide necessary secrets.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name     = "example-cluster"
  machine_type     = "controlplane"
  cluster_endpoint = "https://cluster.local:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}
```

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

### Get Talos Image Factory Overlays Versions

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_overlays_versions.md

Use this data source to fetch a list of available overlays for a specific Talos version. Specify the Talos version and optionally filter by overlay name.

```terraform
provider "talos" {}

data "talos_image_factory_overlays_versions" "this" {
  # get the latest talos version
  talos_version = "v1.7.5"
  filters = {
    name = "rock4cplus"
  }
}
```

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

### Retrieve Talos Image Factory URLs

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_urls.md

Use this data source to fetch URLs for various Talos assets like installers and disk images. Ensure the schematic_id and talos_version are correctly specified for the desired image.

```terraform
data "talos_image_factory_urls" "this" {
  talos_version = "v1.7.5"
  schematic_id  = "376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba"
  platform      = "metal"
}

output "installer_image" {
  value = data.talos_image_factory_urls.this.urls.installer
}
```

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

### Store secrets in Azure Key Vault

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/guides/using_ephemeral_resources.md

Example of storing Talos secrets in Azure Key Vault using standard resources.

```terraform
# Store secrets in Azure Key Vault
resource "azurerm_key_vault_secret" "talos_secrets" {
  name         = "talos-cluster-${var.cluster_name}"
  value        = jsonencode({
    machine_secrets      = talos_machine_secrets.this.machine_secrets
    client_configuration = talos_machine_secrets.this.client_configuration
  })
  key_vault_id = azurerm_key_vault.main.id
}
```

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

### Sequential Multi-Node Upgrade with depends_on

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine.md

For multi-node clusters, use `depends_on` to chain upgrades sequentially, ensuring each node is fully back before the next one starts. This prevents losing etcd quorum during parallel upgrades.

```terraform
resource "talos_machine" "cp0" {
  node             = "10.5.0.1"
  image            = "ghcr.io/siderolabs/installer:v1.10.0"
  drain_on_upgrade = true
  # ...
}

resource "talos_machine" "cp1" {
  depends_on       = [talos_machine.cp0]
  node             = "10.5.0.2"
  image            = "ghcr.io/siderolabs/installer:v1.10.0"
  drain_on_upgrade = true
  # ...
}

resource "talos_machine" "cp2" {
  depends_on       = [talos_machine.cp1]
  node             = "10.5.0.3"
  image            = "ghcr.io/siderolabs/installer:v1.10.0"
  drain_on_upgrade = true
  # ...
}
```

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

### Build Debug Provider Binary

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/README.md

Builds a debug version of the provider binary. This is the first step in setting up a debug session.

```bash
make build-debug
```

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

### Apply Terraform Configuration

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/examples/ephemeral-resources/basic/README.md

Initialize and apply the Terraform configuration to bootstrap the cluster.

```bash
terraform init
terraform apply
```

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

### Store secrets in AWS Secrets Manager

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/guides/using_ephemeral_resources.md

Example of storing Talos secrets in AWS Secrets Manager using standard resources.

```terraform
# Store secrets in AWS Secrets Manager
resource "aws_secretsmanager_secret" "talos_secrets" {
  name = "talos-cluster-${var.cluster_name}"
}

resource "aws_secretsmanager_secret_version" "talos_secrets" {
  secret_id = aws_secretsmanager_secret.talos_secrets.id
  secret_string = jsonencode({
    machine_secrets      = talos_machine_secrets.this.machine_secrets
    client_configuration = talos_machine_secrets.this.client_configuration
  })
}
```

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

### Verify Terraform Plan

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/examples/ephemeral-resources/basic/README.md

Run a plan to ensure infrastructure state is stable and deterministic.

```bash
terraform plan
```

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

### Create and Manage a Talos Cluster

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/cluster.md

This snippet demonstrates how to create and manage a Talos cluster. It depends on the `talos_machine_configuration_apply` resource to ensure the machine configuration is applied before creating the cluster. It also fetches the kubeconfig after the cluster is created.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name       = "example-cluster"
  machine_type       = "controlplane"
  cluster_endpoint   = "https://10.5.0.2:6443"
  machine_secrets    = talos_machine_secrets.this.machine_secrets
  kubernetes_version = "v1.32.0"
}

resource "talos_machine_configuration_apply" "this" {
  client_configuration        = talos_machine_secrets.this.client_configuration
  machine_configuration_input = data.talos_machine_configuration.this.machine_configuration
  node                        = "10.5.0.2"
  config_patches = [
    yamlencode({
      machine = {
        install = {
          disk = "/dev/sda"
        }
      }
    })
  ]
}

resource "talos_cluster" "this" {
  depends_on           = [talos_machine_configuration_apply.this]
  node                 = "10.5.0.2"
  client_configuration = talos_machine_secrets.this.client_configuration
  kubernetes_version   = "v1.32.0"
}

data "talos_cluster_kubeconfig" "this" {
  client_configuration = talos_machine_secrets.this.client_configuration
  node                 = "10.5.0.2"
  depends_on           = [talos_cluster.this]
}
```

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

### Retrieve and Use Kubeconfig

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/examples/ephemeral-resources/basic/README.md

Commands to extract the ephemeral kubeconfig and set it for kubectl access.

```bash
terraform output -raw kubeconfig > kubeconfig.yaml
export KUBECONFIG=kubeconfig.yaml
kubectl get nodes
```

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

### Machine Configuration Apply Schema

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine_configuration_apply.md

Defines the schema for the machine configuration resource, including required and optional fields for applying configurations and managing client settings.

```APIDOC
## Schema

### Required

- `node` (String) The name of the node to bootstrap

### Optional

> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.

- `apply_mode` (String) The mode of the apply operation. Use 'staged_if_needing_reboot' for automatic reboot prevention: performs a dry-run and uses 'staged' mode if reboot is needed, 'auto' otherwise
- `client_configuration` (Attributes) The client configuration data (see [below for nested schema](#nestedatt--client_configuration))
- `client_configuration_wo` (Attributes, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) The client configuration data (write-only). Use this instead of client_configuration when using ephemeral resources. Requires Terraform 1.11+ (see [below for nested schema](#nestedatt--client_configuration_wo))
- `config_patches` (List of String) The list of config patches to apply
- `endpoint` (String) The endpoint of the machine to bootstrap
- `machine_configuration_input` (String, Sensitive) The machine configuration to apply
- `machine_configuration_input_wo` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) The machine configuration to apply (write-only). Use this instead of machine_configuration_input when using ephemeral resources. Requires Terraform 1.11+
- `on_destroy` (Attributes) Actions to be taken on destroy, if *reset* is not set this is a no-op.

> Note: Any changes to *on_destroy* block has to be applied first by running *terraform apply* first, then a subsequent *terraform destroy* for the changes to take effect due to limitations in Terraform provider framework. (see [below for nested schema](#nestedatt--on_destroy))
- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))

### Read-Only

- `id` (String) This is a unique identifier for the machine
- `machine_configuration` (String, Sensitive) The generated machine configuration after applying patches
- `machine_configuration_hash` (String) SHA256 hex digest of the rendered machine configuration (input plus patches). Persisted in state so that changes to machine_configuration_input_wo — which is write-only and itself invisible to state — still surface as plan diffs.
- `resolved_apply_mode` (String) The actual apply mode used. When apply_mode is 'staged_if_needing_reboot', shows the resolved mode ('auto' or 'staged') based on dry-run analysis. Equals apply_mode for other modes.

<a id="nestedatt--client_configuration">
### Nested Schema for `client_configuration`

Required:

- `ca_certificate` (String) The client CA certificate
- `client_certificate` (String) The client certificate
- `client_key` (String, Sensitive) The client key


<a id="nestedatt--client_configuration_wo">
### Nested Schema for `client_configuration_wo`

Required:

- `ca_certificate` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) The client CA certificate
- `client_certificate` (String, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) The client certificate
- `client_key` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) The client key


<a id="nestedatt--on_destroy">
### Nested Schema for `on_destroy`

Optional:

- `graceful` (Boolean) Graceful indicates whether node should leave etcd before the upgrade, it also enforces etcd checks before leaving. Default true
- `reboot` (Boolean) Reboot indicates whether node should reboot or halt after resetting. Default false
- `reset` (Boolean) Reset the machine to the initial state (STATE and EPHEMERAL will be wiped). Default false


<a id="nestedatt--timeouts">
### Nested Schema for `timeouts`

Optional:

- `create` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
- `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
- `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
```

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

### talos_machine_bootstrap Resource

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine_bootstrap.md

Defines the configuration and schema for the talos_machine_bootstrap resource.

```APIDOC
## talos_machine_bootstrap (Resource)

### Description
The machine bootstrap resource allows you to bootstrap a Talos node.

### Parameters
#### Required
- **node** (String) - The name of the node to bootstrap

#### Optional
- **client_configuration** (Attributes) - The client configuration data
- **client_configuration_wo** (Attributes) - The client configuration data (write-only). Requires Terraform 1.11+
- **endpoint** (String) - The endpoint of the machine to bootstrap
- **timeouts** (Attributes) - Configuration for operation timeouts

### Read-Only
- **id** (String) - A unique identifier for the machine

### Nested Schema for client_configuration
- **ca_certificate** (String) - The client CA certificate
- **client_certificate** (String) - The client certificate
- **client_key** (String) - The client key

### Import
terraform import talos_machine_bootstrap.this <any id>
```

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

### Retrieve Talos Cluster Kubeconfig

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/cluster_kubeconfig.md

Demonstrates the full lifecycle of bootstrapping a Talos node and retrieving its kubeconfig using Terraform resources.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_machine_configuration" "this" {
  cluster_name     = "example-cluster"
  machine_type     = "controlplane"
  cluster_endpoint = "https://cluster.local:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}

data "talos_client_configuration" "this" {
  cluster_name         = "example-cluster"
  client_configuration = talos_machine_secrets.this.client_configuration
  nodes                = ["10.5.0.2"]
}

resource "talos_machine_configuration_apply" "this" {
  client_configuration        = talos_machine_secrets.this.client_configuration
  machine_configuration_input = data.talos_machine_configuration.this.machine_configuration
  node                        = "10.5.0.2"
  config_patches = [
    yamlencode({
      machine = {
        install = {
          disk = "/dev/sdd"
        }
      }
    })
  ]
}

resource "talos_machine_bootstrap" "this" {
  depends_on = [
    talos_machine_configuration_apply.this
  ]
  node                 = "10.5.0.2"
  client_configuration = talos_machine_secrets.this.client_configuration
}


resource "talos_cluster_kubeconfig" "this" {
  depends_on = [
    talos_machine_bootstrap.this
  ]
  client_configuration = talos_machine_secrets.this.client_configuration
  node                 = "10.5.0.2"
}
```

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

### Configure Vault Environment Variables

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/examples/ephemeral-resources/basic/README.md

Set Vault connection details via shell environment variables.

```bash
export VAULT_ADDR="https://vault.example.com:8200"
export VAULT_TOKEN="your-vault-token"
```

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

### Import talos_machine_secrets from existing file

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine_secrets.md

This snippet demonstrates how to import machine secrets from an existing secrets file. This is useful when migrating or managing pre-existing Talos cluster secrets.

```terraform
# machine secrets can be imported from an existing secrets file
terraform import talos_machine_secrets.this <path-to-secrets.yaml>

```

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

### Retrieve Talos Image Factory Extensions

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_extensions_versions.md

Fetches a list of available extensions for a specified Talos version, optionally filtered by name.

```terraform
provider "talos" {}

data "talos_image_factory_extensions_versions" "this" {
  # get the latest talos version
  talos_version = "v1.7.5"
  filters = {
    names = [
      "amdgpu",
      "tailscale",
    ]
  }
}
```

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

### talos_client_configuration Data Source

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/client_configuration.md

Use the `talos_client_configuration` data source to generate client configuration for a Talos cluster. This is useful for obtaining credentials and connection details needed to interact with your cluster.

```APIDOC
## talos_client_configuration (Data Source)

### Description
Generate client configuration for a Talos cluster.

### Method
DATA SOURCE

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```terraform
resource "talos_machine_secrets" "this" {}

data "talos_client_configuration" "this" {
  cluster_name         = "example-cluster"
  client_configuration = talos_machine_secrets.this.client_configuration
  nodes                = ["10.5.0.2"]
}
```

### Response
#### Success Response (200)
- **id** (String) The ID of this resource
- **talos_config** (String, Sensitive) The generated client configuration

#### Response Example
```json
{
  "id": "some-unique-id",
  "talos_config": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}
```

### Nested Schema for `client_configuration`
#### Required
- **ca_certificate** (String) The client CA certificate
- **client_certificate** (String) The client certificate
- **client_key** (String, Sensitive) The client key

#### Optional
- **endpoints** (List of String) endpoints to set in the generated config
- **nodes** (List of String) nodes to set in the generated config
```

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

### Implement Vault-backed stable kubeconfig

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/guides/using_ephemeral_resources.md

Uses a terraform_data resource to pin the certificate validity window, ensuring stable kubeconfig bytes for secret managers.

```terraform
# Persist the admin cert NotBefore timestamp in regular Terraform state.
# Use ignore_changes so it is set once and never updated automatically.
# To rotate the cert: taint this resource and re-apply.
resource "terraform_data" "kubeconfig_nbf" {
  input = plantimestamp()
  lifecycle {
    ignore_changes = [input]
  }
}

# Generate kubeconfig with pinned timestamps
ephemeral "talos_cluster_kubeconfig" "this" {
  cluster_name    = "prod-cluster"
  machine_secrets = local.talos_data.machine_secrets
  endpoint        = "https://10.5.0.2:6443"
  not_before      = terraform_data.kubeconfig_nbf.output
  crt_ttl         = "87600h"
}

# Store kubeconfig in Vault — kubeconfig_raw is stable so this resource
# only updates when machine_secrets or not_before change.
resource "vault_kv_secret_v2" "kubeconfig" {
  mount = "secret"
  name  = "kubeconfig-prod-cluster"

  data_json_wo         = jsonencode({ kubeconfig = ephemeral.talos_cluster_kubeconfig.this.kubeconfig_raw })
  data_json_wo_version = 1
}
```

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

### talos_image_factory_extensions_versions Data Source

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_extensions_versions.md

Provides a list of available extensions for a specific Talos version from the image factory. It can be filtered by extension names.

```APIDOC
## talos_image_factory_extensions_versions (Data Source)

### Description
The image factory extensions versions data source provides a list of available extensions for a specific talos version from the image factory.

### Method
GET

### Endpoint
/api/v1/imagefactory/extensions/versions

### Parameters
#### Query Parameters
- **talos_version** (String) - Required - The talos version to get extensions for.
- **filters.names** (List of String) - Optional - The name of the extension to filter by.
- **exact_filters.names** (List of String) - Optional - The exact name match of the extension to filter by.

### Request Example
```terraform
provider "talos" {}

data "talos_image_factory_extensions_versions" "this" {
  # get the latest talos version
  talos_version = "v1.7.5"
  filters = {
    names = [
      "amdgpu",
      "tailscale",
    ]
  }
}
```

### Response
#### Success Response (200)
- **extensions_info** (List of Object) - The list of available extensions for the specified talos version.
  - **author** (String)
  - **description** (String)
  - **digest** (String)
  - **name** (String)
  - **ref** (String)

#### Response Example
```json
{
  "extensions_info": [
    {
      "author": "Talos Systems",
      "description": "NVIDIA GPU drivers for Talos Linux",
      "digest": "sha256:abcdef123456...",
      "name": "nvidia",
      "ref": "ghcr.io/siderolabs/talos/nvidia:v1.7.5-amd64"
    }
  ]
}
```
```

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

### talos_client_configuration Ephemeral Resource

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/ephemeral-resources/client_configuration.md

Defines the schema and usage for the talos_client_configuration resource.

```APIDOC
## talos_client_configuration (Ephemeral Resource)

### Description
Generate client configuration for a Talos cluster from machine secrets. This is an ephemeral resource that does not persist secrets in Terraform state.

### Parameters
#### Required
- **cluster_name** (String) - The name of the cluster in the generated config
- **machine_secrets** (Attributes) - The secrets for the talos cluster

#### Optional
- **crt_ttl** (String) - The lifetime of the generated admin client certificate as a Go duration string. Defaults to "87600h".
- **endpoints** (List of String) - Endpoints to set in the generated config
- **nodes** (List of String) - Nodes to set in the generated config
- **not_before** (String) - RFC3339 timestamp to use as the NotBefore field of the generated admin client certificate.

### Read-Only
- **client_configuration** (Attributes) - The generated client configuration data
- **talos_config** (String) - The generated client configuration
```

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

### In-place OS Upgrade

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine.md

To trigger an in-place OS upgrade for a Talos machine, change the `image` attribute in the `talos_machine` resource and the `talos_version` in the `talos_machine_configuration` data source.

```terraform
data "talos_machine_configuration" "this" {
  # ...
  talos_version = "v1.10.0"
}

resource "talos_machine" "this" {
  # ...
  image = "ghcr.io/siderolabs/installer:v1.10.0"
}
```

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

### Configure Terraform and Providers

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/templates/guides/using_ephemeral_resources.md

Specifies the required Terraform version and the Talos and Vault providers with their versions. Ensure you have Terraform v1.11 or later and the specified provider versions.

```terraform
terraform {
  required_version = ">= 1.11"
  required_providers {
    talos = {
      source  = "siderolabs/talos"
      version = "~> 0.11"
    }
    vault = {
      source  = "hashicorp/vault"
      version = "~> 5.0"
    }
  }
}
```

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

### Generate Talos Client Configuration

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/client_configuration.md

Use this data source to generate client configuration for a Talos cluster. It requires the cluster name and client configuration, and optionally accepts a list of nodes and endpoints.

```terraform
resource "talos_machine_secrets" "this" {}

data "talos_client_configuration" "this" {
  cluster_name         = "example-cluster"
  client_configuration = talos_machine_secrets.this.client_configuration
  nodes                = ["10.5.0.2"]
}
```

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

### Basic talos_machine_secrets Resource

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine_secrets.md

This snippet shows the basic usage of the talos_machine_secrets resource. No additional configuration is provided, so default values will be used.

```terraform
resource "talos_machine_secrets" "machine_secrets" {}

```

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

### talos_image_factory_versions Data Source

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_versions.md

This data source retrieves a list of Talos versions from the image factory. It can optionally filter for stable versions only.

```APIDOC
## talos_image_factory_versions Data Source

### Description
The image factory versions data source provides a list of available talos versions from the image factory.

### Method
GET

### Endpoint
/api/v1/versions

### Parameters
#### Query Parameters
- **stable_versions_only** (Boolean) - Optional - If set to true, only stable versions will be returned. If set to false, all versions will be returned.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **talos_versions** (List of String) - The list of available talos versions.

#### Response Example
{
  "talos_versions": [
    "1.3.0",
    "1.3.1",
    "1.4.0-rc1"
  ]
}
```

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

### Generate Talos Cluster Kubeconfig

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/ephemeral-resources/cluster_kubeconfig.md

Basic usage for generating a kubeconfig and a recommended pattern for ensuring stable output across plan invocations.

```terraform
ephemeral "talos_machine_secrets" "this" {}

ephemeral "talos_cluster_kubeconfig" "this" {
  cluster_name    = "example-cluster"
  machine_secrets = ephemeral.talos_machine_secrets.this.machine_secrets
  endpoint        = "https://10.5.0.2:6443"
}

# Recommended pattern for stable kubeconfig when storing in a secret manager:
# Persist not_before in terraform_data so the admin cert timestamps are fixed
# across plan invocations and kubeconfig_raw is byte-identical on every open.
resource "terraform_data" "kubeconfig_nbf" {
  input = plantimestamp()
  lifecycle {
    ignore_changes = [input]
  }
}

ephemeral "talos_cluster_kubeconfig" "stable" {
  cluster_name    = "example-cluster"
  machine_secrets = ephemeral.talos_machine_secrets.this.machine_secrets
  endpoint        = "https://10.5.0.2:6443"
  not_before      = terraform_data.kubeconfig_nbf.output
  crt_ttl         = "87600h"
}
```

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

### Draining Nodes Before Upgrade

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/machine.md

When `drain_on_upgrade` is true (default) and `image` is set, a kubeconfig must be supplied via `kubeconfig_wo` or `kubeconfig`. This allows the provider to cordon and drain the node before rebooting.

```terraform
ephemeral "talos_cluster_kubeconfig" "this" {
  machine_secrets = talos_machine_secrets.this.machine_secrets
  cluster_name    = "mycluster"
  endpoint        = "https://<cp-ip>:6443"
}

resource "talos_machine" "worker" {
  # ...
  drain_on_upgrade = true
  kubeconfig_wo    = ephemeral.talos_cluster_kubeconfig.this.kubeconfig_raw
}
```

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

### talos_image_factory_urls Data Source

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/data-sources/image_factory_urls.md

This data source retrieves URLs for Talos image factory assets. It requires the Talos version and a schematic ID, and optionally accepts platform and architecture to refine the URL generation.

```APIDOC
## talos_image_factory_urls Data Source

### Description
Generates URLs for different assets supported by the Talos image factory.

### Method
DATA SOURCE

### Endpoint
N/A (Data Source)

### Parameters
#### Required
- **schematic_id** (String) - The schematic ID for which the URLs are generated.
- **talos_version** (String) - The Talos version for which the URLs are generated.

#### Optional
- **architecture** (String) - The platform architecture for which the URLs are generated. Defaults to amd64.
- **platform** (String) - The platform for which the URLs are generated. Supported values include: metal, aws, gcp, equinixMetal, azure, digital-ocean, nocloud, openstack, vmware, akamai, cloudstack, hcloud, oracle, upcloud, vultr, exoscale, opennebula, scaleway.
- **sbc** (String) - The SBC's (Single Board Copmuters) for which the url are generated. Supported values include: rpi_5, rpi_generic, revpi_generic, bananapi_m64, nanopi_r4s, nanopi_r5s, jetson_nano, libretech_all_h3_cc_h5, orangepi_r1_plus_lts, pine64, rock64, rock4cplus, rock4se, rock5a, rock5b, rockpi_4, rockpi_4c, helios64, turingrk1, orangepi-5, orangepi-5-plus, rockpro64, odroid-m1, radxa-zero-3e, rock3b, orangepi-5-max, rock5t, friendlyelec-cm3588-nas, rock5b-plus.

### Read-Only Attributes
- **id** (String) - The ID of this resource.
- **urls** (Attributes) - The URLs for different assets supported by the Talos image factory. If the URL is not available for a specific asset, it will be an empty string.
  ### Nested Schema for `urls`
  Read-Only:
  - **disk_image** (String) - The URL for the disk image.
  - **disk_image_secureboot** (String) - The URL for the disk image with secure boot.
  - **initramfs** (String) - The URL for the initramfs image.
  - **installer** (String) - The URL for the installer image.
  - **installer_secureboot** (String) - The URL for the installer image with secure boot.
  - **iso** (String) - The URL for the ISO image.
  - **iso_secureboot** (String) - The URL for the ISO image with secure boot.
  - **kernel** (String) - The URL for the kernel image.
  - **kernel_command_line** (String) - The URL for the kernel command line.
  - **pxe** (String) - The URL for the PXE image.
  - **uki** (String) - The URL for the UKI image.

### Example Usage
```terraform
data "talos_image_factory_urls" "this" {
  talos_version = "v1.7.5"
  schematic_id  = "376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba"
  platform      = "metal"
}

output "installer_image" {
  value = data.talos_image_factory_urls.this.urls.installer
}
```
```

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

### Generate and Store Secrets Externally

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/guides/using_ephemeral_resources.md

Commands to generate Talos secrets manually and store them in Vault using the CLI.

```bash
# Generate secrets manually using talosctl
talosctl gen secrets -o secrets.yaml

# Store in Vault using vault CLI
vault kv put secret/talos-cluster-prod \
  machine_secrets="$(yq -o=json '.machine_secrets' secrets.yaml)" \
  client_configuration="$(yq -o=json '.client_configuration' secrets.yaml)"
```

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

### talos_cluster_kubeconfig Resource

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/resources/cluster_kubeconfig.md

Defines the configuration and schema for the talos_cluster_kubeconfig resource.

```APIDOC
## talos_cluster_kubeconfig (Resource)

### Description
Retrieves the kubeconfig for a Talos cluster from a specified controlplane node.

### Parameters
#### Required
- **client_configuration** (Attributes) - Required - The client configuration data containing ca_certificate, client_certificate, and client_key.
- **node** (String) - Required - The controlplane node to retrieve the kubeconfig from.

#### Optional
- **certificate_renewal_duration** (String) - Optional - The duration in hours before the certificate is renewed, defaults to 720h.
- **endpoint** (String) - Optional - Endpoint to use for the talosclient. If not set, the node value will be used.
- **timeouts** (Attributes) - Optional - Configuration for create and update timeouts.

### Read-Only
- **id** (String) - The ID of this resource.
- **kubeconfig_raw** (String) - The raw kubeconfig.
- **kubernetes_client_configuration** (Attributes) - The kubernetes client configuration including ca_certificate, client_certificate, client_key, and host.
```

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

### Configure Talos Secrets and Machine Configuration

Source: https://github.com/siderolabs/terraform-provider-talos/blob/main/docs/guides/using_ephemeral_resources.md

Defines the ephemeral secrets generation, storage in Vault, and the subsequent application of machine configuration using write-only attributes.

```hcl
# After initial creation, this won't be evaluated because data_json_wo_version is hardcoded
ephemeral "talos_machine_secrets" "this" {}

resource "vault_kv_secret_v2" "talos_secrets" {
  mount = "secret"
  name  = "talos-cluster-${var.cluster_name}"

  # Write-only attributes prevent secrets from being stored in Terraform state
  data_json_wo = jsonencode({
    machine_secrets      = ephemeral.talos_machine_secrets.this.machine_secrets
    client_configuration = ephemeral.talos_machine_secrets.this.client_configuration
  })
  # Hardcoded version prevents unnecessary refreshes after initial creation
  data_json_wo_version = 1
}

# Step 2: Retrieve secrets ephemerally from Vault
# This runs on every terraform operation but values are never stored in state
# Referencing the resource attributes creates implicit dependency on the secret
ephemeral "vault_kv_secret_v2" "talos_secrets" {
  mount = vault_kv_secret_v2.talos_secrets.mount
  name  = vault_kv_secret_v2.talos_secrets.name
}

locals {
  # Decode the secret data
  talos_data = jsondecode(ephemeral.vault_kv_secret_v2.talos_secrets.data_json)
}

# Step 3: Generate machine configuration using retrieved secrets
ephemeral "talos_machine_configuration" "controlplane" {
  cluster_name     = var.cluster_name
  cluster_endpoint = var.cluster_endpoint
  machine_type     = "controlplane"
  machine_secrets  = local.talos_data.machine_secrets
}

# Step 4: Apply configuration using write-only input
resource "talos_machine_configuration_apply" "controlplane" {
  client_configuration_wo        = local.talos_data.client_configuration
  machine_configuration_input_wo = ephemeral.talos_machine_configuration.controlplane.machine_configuration
  node                           = var.controlplane_node

  # Note: machine_configuration computed attribute will be null in state
  # This is expected behavior for secret-free operation
}
```