apk-deploy-02/terraform/README.md

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:

cd terraform/infra/dev
terraform init

Review the execution plan:

terraform plan

Apply the configuration to deploy the K3s cluster:

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:

kubectl get nodes
kubectl get pods --all-namespaces

Destroying the Cluster

To tear down the cluster:

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