120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
# 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
|