chore: initialize k3s master iac skeleton

terraform/README.md

@@ -0,0 +1,27 @@
+# Terraform K3s Master Scaffold
+
+## Purpose
+This module provisions K3s control-plane virtual machines on vSphere. It only includes the provider bootstrap today; VM resources and data sources are added in future iterations.
+
+## Required Inputs
+| Variable | Description |
+| --- | --- |
+| `vsphere_user` / `vsphere_password` | Service account stored in CI secrets (never commit plaintext). |
+| `vsphere_server` | vCenter hostname or IP. |
+| `datacenter`, `cluster`, `resource_pool` | Target placement scope. |
+| `datastore` | Datastore or datastore cluster for disks. |
+| `template` | Hardened golden image for K3s masters. |
+| `network` | Portgroup for primary NIC. |
+| `vm_count`, `vm_cpu`, `vm_memory_mb` | Control-plane sizing knobs. |
+| `tags` | Optional key/value metadata for governance. |
+
+## Security Notes
+- Inject credentials via Terraform Cloud/Enterprise variables, Vault, or Gitea Actions secrets.
+- Rotate the vSphere service account per security policy; constrain RBAC to cloning and tagging only.
+- Validate SSL certificates where possible; set `allow_unverified_ssl` only for lab use.
+- Store generated Terraform state in a remote backend with encryption-at-rest (e.g., Consul, S3 compatible).
+
+## Next Steps
+1. Wire vSphere data sources (datacenter, datastore, network).
+2. Define `vsphere_virtual_machine` resources aligned with K3s sizing guidance.
+3. Emit provisioning outputs consumed by Ansible inventory generation.

terraform/main.tf

@@ -0,0 +1,11 @@
+provider "vsphere" {
+  user           = var.vsphere_user
+  password       = var.vsphere_password
+  vsphere_server = var.vsphere_server
+
+  # CI pipeline injects sensitive certificates and ignores insecure SSL via TF vars if required.
+  allow_unverified_ssl = false
+}
+
+# Placeholder resource block intentionally omitted.
+# Actual VM cloning, tagging, and network configuration will be added in follow-up stories.

terraform/variables.tf

@@ -0,0 +1,73 @@
+variable "vsphere_user" {
+  description = "vSphere username with permissions to deploy K3s master VMs"
+  type        = string
+  sensitive   = true
+}
+
+variable "vsphere_password" {
+  description = "vSphere password stored in CI secrets manager"
+  type        = string
+  sensitive   = true
+}
+
+variable "vsphere_server" {
+  description = "vCenter endpoint (FQDN or IP)"
+  type        = string
+}
+
+variable "datacenter" {
+  description = "Target vSphere datacenter name"
+  type        = string
+}
+
+variable "cluster" {
+  description = "Target vSphere compute cluster"
+  type        = string
+}
+
+variable "resource_pool" {
+  description = "Resource pool for the K3s master instances"
+  type        = string
+  default     = ""
+}
+
+variable "datastore" {
+  description = "Primary datastore to host the VM disks"
+  type        = string
+}
+
+variable "template" {
+  description = "Hardened golden image used to clone K3s masters"
+  type        = string
+}
+
+variable "network" {
+  description = "Primary portgroup the masters attach to"
+  type        = string
+}
+
+variable "vm_count" {
+  description = "Number of K3s control-plane VMs to provision"
+  type        = number
+  default     = 3
+}
+
+variable "vm_cpu" {
+  description = "vCPU count per K3s control-plane VM"
+  type        = number
+  default     = 4
+}
+
+variable "vm_memory_mb" {
+  description = "Memory in MB per control-plane VM"
+  type        = number
+  default     = 8192
+}
+
+variable "tags" {
+  description = "Map of tags applied to all created resources"
+  type        = map(string)
+  default     = {}
+}
+
+# Sensitive values are marked and must flow through secrets management, never plain text.

terraform/versions.tf

@@ -0,0 +1,12 @@
+terraform {
+  required_version = ">= 1.8.0"
+
+  required_providers {
+    vsphere = {
+      source  = "hashicorp/vsphere"
+      version = ">= 2.5.0"
+    }
+  }
+}
+
+# Locking Terraform and provider versions prevents pipeline drift.