# K3s Kubernetes Cluster Terraform Project

This Terraform project allows you to deploy a lightweight K3s Kubernetes cluster on any infrastructure that supports SSH access. The project uses only the null and local providers, performing all operations via SSH connections and local/remote execution provisioners.

## Project Structure

```
terraform/
├── modules/
│   └── k3s-install/
│       ├── main.tf         # K3s installation logic
│       ├── variables.tf    # Module variables
│       └── outputs.tf      # Module outputs
└── infra/
    └── dev/
        ├── main.tf         # Main entry point
        ├── variables.tf    # Variable definitions
        ├── terraform.tfvars # Variable values
        ├── env.tf          # Environment file handling
        ├── providers.tf    # Provider configurations
        └── .env            # Environment variables (template)
```

## Prerequisites

1. SSH access to all target nodes (server and workers)
2. SSH key pair for authentication
3. Terraform >= 1.0.0
4. Target nodes with:
   - A supported operating system (Ubuntu, Debian, CentOS, etc.)
   - Sufficient privileges to install system packages

## Configuration

### Setting Up Variables

1. Edit `terraform/infra/dev/terraform.tfvars` to configure your infrastructure:
   - Set `server_ip` to the IP address of your K3s server node
   - Set `worker_ips` to a list of IP addresses for your worker nodes
   - Set `ssh_user` to the SSH username for connecting to the nodes
   - Set `ssh_private_key` to the path of your SSH private key
   - Customize other parameters as needed

2. Alternatively, you can use environment variables by editing the `.env` file:
   - Uncomment and set the desired variables
   - Variables defined in `.env` will override those in `terraform.tfvars`

## Usage

### Deploying the Cluster

Navigate to the deployment directory and initialize Terraform:

```shell
cd terraform/infra/dev
terraform init
```

Review the execution plan:

```shell
terraform plan
```

Apply the configuration to deploy the K3s cluster:

```shell
terraform apply
```

### Accessing the Cluster

After deployment, the kubeconfig will be available at the path specified by `kubeconfig_path` (default: `~/.kube/config`). You can use this to interact with your cluster:

```shell
kubectl get nodes
kubectl get pods --all-namespaces
```

### Destroying the Cluster

To tear down the cluster:

```shell
terraform destroy
```

This will uninstall K3s from both server and worker nodes, and clean up all resources.

## Features

- **SSH Configuration**: Creates a secure SSH configuration for connecting to nodes
- **K3s Server Installation**: Installs K3s on the server node with customizable options
- **Kubeconfig Management**: Retrieves and configures the kubeconfig for local access
- **Worker Node Deployment**: Joins worker nodes to the cluster using the node token
- **Clean Uninstallation**: Properly cleans up all components on terraform destroy
- **Flexible Configuration**: Supports both variable files and environment variables

## Customization Options

- **Traefik Dashboard**: Enable with `enable_traefik_dashboard = true`
- **SSL Configuration**: Enable with `enable_ssl = true` and provide certificate paths
- **Custom K3s Version**: Specify with `k3s_version` variable
- **Additional Arguments**: Pass extra arguments to both server and agent installs

## Troubleshooting

If you encounter issues:

1. Check SSH connectivity to all nodes
2. Verify that the SSH user has sufficient permissions
3. Ensure all nodes meet the system requirements for K3s
4. Check the logs on each node at `/var/log/k3s.log` or `/var/log/k3s-agent.log`

## Security Considerations

- The SSH configuration disables strict host key checking for convenience but consider enabling it in production
- Secure your kubeconfig file as it contains authentication information
- Consider using an SSH agent or SSH certificates for improved security