diff --git a/docs/k3s_class_diagram.puml b/docs/k3s_class_diagram.puml new file mode 100644 index 0000000..065ba1c --- /dev/null +++ b/docs/k3s_class_diagram.puml @@ -0,0 +1,119 @@ +@startuml K3s Infrastructure Class Diagram +skinparam classAttributeIconSize 0 + +title K3s Kubernetes Cluster - Terraform Resource Relationships + +package "Terraform Infrastructure" { + class "Development Environment" as dev { + + server_ip: string + + worker_ips: list(string) + + ssh_user: string + + ssh_private_key: string + + replace_url: string + + domain: string + + ssl_cert_path: string + + ssl_key_path: string + + install_argocd: bool + + enable_traefik_dashboard: bool + + enable_ssh_tunnel: bool + } + + class "K3s Install Module" as k3s_module { + + server_ip: string + + worker_ips: list(string) + + ssh_user: string + + ssh_private_key: string + + replace_url: string + + apply() + + destroy() + } + + class "null_resource.setup_ssh_config" as ssh_config { + + triggers: map + - local-exec: create SSH config + } + + class "null_resource.install_k3s_server" as server_install { + + depends_on: [setup_ssh_config] + + triggers: map + - remote-exec: install K3s server + - remote-exec: uninstall on destroy + } + + class "null_resource.get_k3s_config" as get_config { + + depends_on: [install_k3s_server, setup_ssh_config] + - remote-exec: copy kubeconfig + - local-exec: download kubeconfig + - local-exec: update server URL + } + + class "null_resource.get_k3s_token" as get_token { + + depends_on: [install_k3s_server, setup_ssh_config] + - remote-exec: extract node token + - local-exec: download token + } + + class "null_resource.copy_token_to_workers" as copy_token { + + depends_on: [get_k3s_token] + + count: length(worker_ips) + - file: upload token to worker + } + + class "null_resource.install_k3s_worker" as worker_install { + + depends_on: [copy_token_to_workers] + + count: length(worker_ips) + + triggers: map + - remote-exec: install K3s agent + - remote-exec: uninstall on destroy + } + + class "Output" as output { + + kubeconfig_path: string + } +} + +package "External Resources" { + class "Server Node" as server { + + hostname: string + + K3s server + + Control plane components + + Node token + + Kubeconfig + } + + class "Worker Node" as worker { + + hostname: string + + K3s agent + + Container runtime + } +} + +dev --> k3s_module : uses +k3s_module --> ssh_config : creates +k3s_module --> server_install : creates +k3s_module --> get_config : creates +k3s_module --> get_token : creates +k3s_module --> copy_token : creates +k3s_module --> worker_install : creates +k3s_module --> output : provides + +ssh_config ..> server : configures access +ssh_config ..> worker : configures access +server_install ..> server : provisions +get_config ..> server : extracts config +get_token ..> server : extracts token +copy_token ..> worker : transfers token +worker_install ..> worker : provisions + +note bottom of k3s_module + The K3s Install Module orchestrates the provisioning of a K3s Kubernetes cluster + by creating and managing the necessary resources in sequence: + 1. Set up SSH configuration + 2. Install K3s on server node + 3. Retrieve kubeconfig and node token + 4. Copy token to worker nodes + 5. Install K3s agents on worker nodes +end note + +footer K3s Infrastructure Class Diagram - Version 1.0 +@enduml diff --git a/docs/k3s_component_diagram.puml b/docs/k3s_component_diagram.puml new file mode 100644 index 0000000..1c90c34 --- /dev/null +++ b/docs/k3s_component_diagram.puml @@ -0,0 +1,56 @@ +@startuml K3s Infrastructure Component Diagram +!include + +title K3s Kubernetes Cluster Infrastructure - Component Diagram + +AddElementTag("module", $bgColor="#85BBF0", $fontColor="black", $borderColor="#78A8D8") +AddElementTag("resource", $bgColor="#85E0A3", $fontColor="black", $borderColor="#78D096") +AddElementTag("data", $bgColor="#F5DA81", $fontColor="black", $borderColor="#E8CD74") +AddElementTag("provider", $bgColor="#F08585", $fontColor="black", $borderColor="#D87878") + +Person(client, "DevOps Engineer", "Infrastructure Administrator") + +System_Boundary(terraform, "Terraform Infrastructure") { + Component(providers, "Terraform Providers", "null, local", "Required providers for infrastructure management", $tags="provider") + + Component_Ext(dev_env, "Development Environment", "terraform/infra/dev", "Main entry point for infrastructure deployment", $tags="module") + + Component(k3s_module, "K3s Install Module", "terraform/modules/k3s-install", "Module for K3s Kubernetes cluster deployment", $tags="module") + + Component(null_resources, "Null Resources", "terraform", "Various operations performed by null_resource blocks", $tags="resource") + + Component(variables, "Variables Configuration", "terraform/infra/dev/terraform.tfvars", "Infrastructure configuration parameters", $tags="data") + + Component(env_file, "Environment File", ".env", "Environment-specific variables", $tags="data") +} + +System_Boundary(infrastructure, "K3s Kubernetes Cluster") { + Component(server_node, "K3s Server Node", "Kubernetes Control Plane", "Main server managing the Kubernetes cluster", $tags="resource") + + Component(worker1, "Worker Node 1", "Kubernetes Worker", "Node running containerized workloads", $tags="resource") + Component(worker2, "Worker Node 2", "Kubernetes Worker", "Node running containerized workloads", $tags="resource") + + Component(kubeconfig, "Kubeconfig", "YAML Configuration", "Authentication and connection details", $tags="data") + + Component(node_token, "Node Token", "Authentication Token", "Used by workers to join the cluster", $tags="data") +} + +Rel(client, dev_env, "Runs terraform apply/destroy") +Rel(dev_env, variables, "Reads configuration from") +Rel(dev_env, env_file, "Reads environment data") +Rel_Right(dev_env, k3s_module, "Uses") +Rel(k3s_module, null_resources, "Creates and manages") +Rel(k3s_module, providers, "Uses") + +Rel(null_resources, server_node, "Provisions and configures") +Rel_Right(server_node, node_token, "Generates") +Rel_Right(server_node, kubeconfig, "Generates") +Rel(null_resources, node_token, "Retrieves") +Rel(null_resources, worker1, "Provisions and configures") +Rel(null_resources, worker2, "Provisions and configures") +Rel_Up(worker1, node_token, "Uses for authentication") +Rel_Up(worker2, node_token, "Uses for authentication") +Rel(client, kubeconfig, "Uses to access cluster") + +footer K3s Infrastructure Components - Version 1.0 +@enduml diff --git a/docs/k3s_deployment_diagram.puml b/docs/k3s_deployment_diagram.puml new file mode 100644 index 0000000..a1033a6 --- /dev/null +++ b/docs/k3s_deployment_diagram.puml @@ -0,0 +1,78 @@ +@startuml K3s Infrastructure Deployment Diagram +!include + +skinparam linetype ortho +skinparam rectangle { + BackgroundColor<> #C0FFFF + BackgroundColor<> #F0FFC0 + BackgroundColor<> #FFE0C0 + BackgroundColor<> #C0C0FF +} + +title K3s Kubernetes Cluster - Deployment Architecture + +rectangle "Infrastructure Administrator's Machine" as client { + rectangle "Terraform CLI" as terraform <> { + rectangle "terraform.tfvars" as tfvars + rectangle "main.tf" as main + rectangle "variables.tf" as vars + rectangle ".env file" as env + } + rectangle "SSH Keys" as ssh_keys + rectangle "Local Kubeconfig" as local_kubeconfig <> +} + +rectangle "Kubernetes Cluster" { + rectangle "Server Node\n(reg.benadis.org)" as server <> { + rectangle "<$node>\nK3s Server" as k3s_server + rectangle "Control Plane Components" as control_plane + rectangle "/etc/rancher/k3s/k3s.yaml" as kubeconfig <> + rectangle "Node Token" as token <> + } + + rectangle "Worker Node 1\n(worker1.benadis.org)" as worker1 <> { + rectangle "<$pod>\nK3s Agent" as k3s_agent1 + rectangle "Container Runtime" as container1 + } + + rectangle "Worker Node 2\n(worker2.benadis.org)" as worker2 <> { + rectangle "<$pod>\nK3s Agent" as k3s_agent2 + rectangle "Container Runtime" as container2 + } +} + +' Client connections +client -- server : SSH +client -- worker1 : SSH +client -- worker2 : SSH + +' Internal cluster connections +server -- worker1 : HTTPS (6443) +server -- worker2 : HTTPS (6443) + +' Configuration flows +terraform ..> server : provisions +terraform ...> worker1 : provisions +terraform ...> worker2 : provisions + +ssh_keys ....> server : authenticates +ssh_keys ....> worker1 : authenticates +ssh_keys ....> worker2 : authenticates + +kubeconfig -[dashed]-> local_kubeconfig : copied & modified +token -[dashed]-> worker1 : used for joining +token -[dashed]-> worker2 : used for joining + +note as N1 + The K3s deployment uses Terraform to provision a lightweight + Kubernetes cluster consisting of one server node and two worker nodes. + + Key features: + - Uses SSH for secure provisioning + - Retrieves kubeconfig file for cluster access + - Transfers node token to worker nodes for authentication + - Creates a secure and robust Kubernetes environment +end note + +footer K3s Infrastructure Deployment Architecture - Version 1.0 +@enduml diff --git a/docs/k3s_infrastructure_activity_diagram.puml b/docs/k3s_infrastructure_activity_diagram.puml new file mode 100644 index 0000000..e3c74fc --- /dev/null +++ b/docs/k3s_infrastructure_activity_diagram.puml @@ -0,0 +1,84 @@ +@startuml K3s Infrastructure Deployment Workflow +skinparam ConditionEndStyle hline + +title K3s Kubernetes Cluster Deployment Workflow + +|#AntiqueWhite|Client| +|#LightBlue|Terraform| +|#PaleGreen|Server Node| +|#LightSalmon|Worker Nodes| + +|Client| +start +:Prepare SSH Authentication; +note right: SSH key pair must be available at the specified path + +|Terraform| +:Read Input Variables (Dev Environment); +note right: server_ip, worker_ips, ssh_user, ssh_private_key, and other parameters + +:Setup SSH Config; +note right: Creates temporary SSH config for secure connections + +|Server Node| +:Install K3s Server; +note right + Uses curl to download and run K3s installer + Configures node as a Kubernetes server +end note + +:Store Kubeconfig; +:Generate Node Token; +note right: Required for worker nodes to join the cluster + +|Terraform| +:Retrieve K3s Kubeconfig; +note right + Gets k3s.yaml configuration + Makes it accessible locally + Updates server URL in config +end note + +:Retrieve Node Token; +note right: Securely transfer the token to local environment + +|Worker Nodes| +fork + :Worker Node 1; + note right: For each worker node in parallel +fork again + :Worker Node 2; +end fork + +|Terraform| +:Copy Node Token to Workers; +note right: Securely transfer the join token to each worker + +|Worker Nodes| +fork + :Install K3s Agent (Worker 1); + note right + Installs K3s in agent mode + Connects to server using token + Registers as a worker node + end note +fork again + :Install K3s Agent (Worker 2); +end fork + +|Terraform| +:Cluster is Ready; +note right + All nodes are provisioned + Kubeconfig is available locally + Cluster can be accessed via kubectl +end note + +|Client| +:Access Kubernetes Cluster; +note right: Using generated kubeconfig at ~/.kube/config or as specified + +stop + +footer Infrastructure Deployment Process - Version 1.0 +@enduml diff --git a/docs/k3s_sequence_diagram.puml b/docs/k3s_sequence_diagram.puml new file mode 100644 index 0000000..5bf5382 --- /dev/null +++ b/docs/k3s_sequence_diagram.puml @@ -0,0 +1,97 @@ +@startuml K3s Infrastructure Sequence Diagram +skinparam sequenceMessageAlign center +skinparam responseMessageBelowArrow true + +title K3s Kubernetes Cluster Deployment - Sequence Diagram + +actor "DevOps Engineer" as client +participant "Terraform CLI" as terraform +participant "K3s Install Module" as module +participant "SSH Connection" as ssh +participant "Server Node" as server +participant "Worker Node 1" as worker1 +participant "Worker Node 2" as worker2 + +== Infrastructure Initialization == +client -> terraform: terraform init +terraform -> client: Providers initialized + +== Deployment Planning == +client -> terraform: terraform plan +terraform -> module: Parse variables +module -> terraform: Show planned resources +terraform -> client: Display execution plan + +== Infrastructure Deployment == +client -> terraform: terraform apply +terraform -> module: Execute installation + +== SSH Configuration == +module -> module: Create temporary SSH config +note right: Creates secure SSH configuration for all nodes + +== Server Provisioning == +module -> ssh: Establish connection to server +ssh -> server: Connect +module -> server: Install K3s server component +note right + Uses curl to download K3s installer + Configures K3s as server node +end note +server --> module: Installation complete + +== Kubeconfig Retrieval == +module -> server: Request kubeconfig +server -> server: Copy k3s.yaml to /tmp +server --> module: Kubeconfig available +module -> module: Download kubeconfig +module -> module: Update server URL in config +note right: Replaces 127.0.0.1 with actual server address + +== Node Token Handling == +module -> server: Request node token +server -> server: Extract node token +server --> module: Node token available +module -> module: Download node token + +== Worker Node Provisioning == +group Worker Node Installation [Parallel execution] + module -> ssh: Connect to Worker Node 1 + ssh -> worker1: Connect + module -> worker1: Transfer node token + module -> worker1: Install K3s agent + note right + Installs K3s in agent mode + Uses token to join the cluster + end note + worker1 --> module: Installation complete + + module -> ssh: Connect to Worker Node 2 + ssh -> worker2: Connect + module -> worker2: Transfer node token + module -> worker2: Install K3s agent + worker2 --> module: Installation complete +end + +== Completion == +module --> terraform: All resources provisioned +terraform --> client: Infrastructure deployment complete + +== Cluster Usage == +client -> server: Access Kubernetes via kubeconfig +note right: Uses kubectl with the generated configuration + +== Destruction (Optional) == +client -> terraform: terraform destroy +terraform -> module: Initiate cleanup +module -> worker1: Run agent uninstall script +worker1 --> module: Agent uninstalled +module -> worker2: Run agent uninstall script +worker2 --> module: Agent uninstalled +module -> server: Run server uninstall script +server --> module: Server uninstalled +module --> terraform: All resources cleaned up +terraform --> client: Infrastructure destroyed + +footer K3s Infrastructure Sequence Diagram - Version 1.0 +@enduml diff --git a/docs/prompt.md b/docs/prompt.md new file mode 100644 index 0000000..1fa3d6e --- /dev/null +++ b/docs/prompt.md @@ -0,0 +1,69 @@ +# K3s Kubernetes Infrastructure Generation Prompt + +This document contains the prompt that can be used to regenerate the entire K3s Kubernetes infrastructure project based on the PlantUML diagrams provided in this directory. + +## Prompt for Project Generation + +``` +Please generate a complete Terraform project for deploying a K3s Kubernetes cluster based on the following PlantUML diagrams: + +1. The activity diagram (k3s_infrastructure_activity_diagram.puml) shows the workflow and sequence of operations for setting up the K3s infrastructure. +2. The component diagram (k3s_component_diagram.puml) illustrates the main components and their relationships. +3. The sequence diagram (k3s_sequence_diagram.puml) details the interaction between different components during deployment. +4. The deployment diagram (k3s_deployment_diagram.puml) shows the physical architecture of the Kubernetes cluster. +5. The class diagram (k3s_class_diagram.puml) depicts the relationships between Terraform resources. + +Based on these diagrams, create a complete Terraform project with the following 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 - empty template) + +The project should implement the following functionality: +1. Setup SSH configuration for secure connections to server and worker nodes +2. Install K3s server on the main node +3. Retrieve kubeconfig and node token from the server +4. Copy the node token to worker nodes +5. Install K3s agents on worker nodes +6. Provide proper cleanup/uninstallation on terraform destroy +7. Handle any potential errors gracefully + +Use only null and local providers for this infrastructure. All operations should be performed using SSH connections and local-exec/remote-exec provisioners. + +Please implement each file with complete, working code that follows Terraform best practices. +``` + +## Modifying the Infrastructure + +To modify the infrastructure, you can: + +1. Edit the PlantUML diagrams to reflect your desired changes +2. Provide a prompt like the following: + +``` +Based on the modified PlantUML diagram [diagram_name.puml], please update the corresponding Terraform files to implement these changes: + +[List specific changes here] + +Ensure that the changes maintain the overall integrity of the infrastructure and follow Terraform best practices. +``` + +## Additional Considerations + +- The diagrams contain detailed comments and notes that explain the functionality and purpose of each component +- The activity diagram shows the exact flow of operations needed for proper deployment +- The class diagram maps directly to Terraform resources and their relationships +- The sequence diagram provides timing information critical for understanding dependencies + +By following these diagrams, you can generate a fully functional Terraform project for deploying a K3s Kubernetes cluster on any compatible infrastructure.