diff --git a/docs/diagram-promt.md b/docs/diagram-promt.md new file mode 100644 index 0000000..1ce0d83 --- /dev/null +++ b/docs/diagram-promt.md @@ -0,0 +1,144 @@ +# K3s Infrastructure Diagram Formatting Guidelines + +This document provides specific formatting guidelines for creating consistent, readable, and machine-parsable PlantUML diagrams for the K3s Kubernetes infrastructure project. + +## Activity Diagram Formatting + +Activity diagrams should use the following formatting style with header separators (====) and detail separators (----): + +``` +:Activity Name +==== +parameter1=value1 +parameter2=value2 +parameter3=value3 +---- +Additional context or explanation; +``` + +### Key Formatting Rules + +1. **Activity Names**: Clear, concise action descriptions +2. **Parameter Section**: Place after the header separator (====) + - Use `parameter=value` format on separate lines + - Parameters should be specific to the action (e.g., paths, commands, modes) +3. **Context Section**: Place after the detail separator (----) + - Provide a brief explanation of the action's purpose + - End with a semicolon +4. **Variable Escaping**: Enclose Terraform variables or special characters in single quotes + - Example: `local_path='${kubeconfig_path}'` instead of `local_path=${kubeconfig_path}` + - This prevents parsing errors in PlantUML + +### Example + +``` +:Install K3s Server +==== +action=curl -sfL https://get.k3s.io +mode=server +k3s_version='${var.k3s_version}' +---- +Configures node as a Kubernetes server; +``` + +## Component Diagram Formatting + +Component diagrams should use a consistent C4 model approach: + +``` +Component(id, "Name", "Technology", "Description", $tags="tag") +``` + +### Key Formatting Rules + +1. **Component Definitions**: Use C4 model component syntax +2. **Tags**: Use consistent tags for visual grouping (module, resource, data, provider) +3. **Relationships**: Clearly indicate direction and purpose of relationships +4. **Systems**: Group related components inside System_Boundary blocks +5. **Special Characters**: Escape variables or special characters with single quotes + - Example: `"Version: '${var.version}'"` instead of `"Version: ${var.version}"` + +### Example + +``` +Component(k3s_module, "K3s Install Module", "terraform/modules/k3s-install", "Module for K3s Kubernetes cluster deployment", $tags="module") +``` + +## Sequence Diagram Formatting + +Sequence diagrams should use clear participant definitions and message formatting: + +``` +participant "Participant Name" as alias +``` + +For messages, follow this format: + +``` +sender -> receiver: Action +==== +parameter1=value1 +parameter2=value2 +---- +Additional context; +``` + +### Key Formatting Rules + +1. **Participant Definitions**: Clear names with meaningful aliases +2. **Message Formatting**: Include header and detail separators for complex actions +3. **Grouping**: Use `group` for parallel or related actions +4. **Phases**: Separate workflow into logical phases using `==Phase Name==` +5. **Special Characters**: Escape variables with single quotes in message text + - Example: `Setup server at address: '${server_ip}'` + +## Deployment Diagram Formatting + +Deployment diagrams should use: + +``` +rectangle "Component Name\n(hostname)" as alias <> { + rectangle "Subcomponent" as subAlias +} +``` + +### Key Formatting Rules + +1. **Component Containers**: Group related components inside rectangles +2. **Stereotypes**: Use `<>`, `<>`, `<>` consistently +3. **Connections**: Use solid lines for network connections, dashed for data flows +4. **Notes**: Use notes to explain complex relationships or configurations +5. **Special Characters**: Escape variables with single quotes in component names + - Example: `"Server '${var.name}'"` instead of `"Server ${var.name}"` + +## Class Diagram Formatting + +Class diagrams representing Terraform resources should use: + +``` +class "Resource Name" as alias { + + property: type + - private_property: type + + method() +} +``` + +### Key Formatting Rules + +1. **Resource Representation**: Each Terraform resource is a class +2. **Properties**: Include all significant properties with their types +3. **Relationships**: Show dependencies using standard UML notation +4. **Packages**: Group related resources into logical packages +5. **Special Characters**: Escape variables with single quotes in properties + - Example: `+ url: '${var.domain}'` instead of `+ url: ${var.domain}` + +## General Formatting Guidelines + +1. **Naming Consistency**: Use consistent naming across all diagrams +2. **Color Schemes**: Maintain consistent color themes across diagrams +3. **Comments**: Include descriptive comments/notes for complex elements +4. **Escaping Special Characters**: Always enclose Terraform variable references (`${...}`) in single quotes +5. **Footer**: Include version information in the footer +6. **Title**: Use clear, descriptive titles + +These formatting guidelines ensure that all infrastructure diagrams are consistent, readable, and correctly processed by both PlantUML and Terraform code generators. \ No newline at end of file diff --git a/docs/k3s_infrastructure_activity_diagram.puml b/docs/k3s_infrastructure_activity_diagram.puml index e3c74fc..dd5abb5 100644 --- a/docs/k3s_infrastructure_activity_diagram.puml +++ b/docs/k3s_infrastructure_activity_diagram.puml @@ -10,73 +10,127 @@ title K3s Kubernetes Cluster Deployment Workflow |Client| start -:Prepare SSH Authentication; -note right: SSH key pair must be available at the specified path +:Prepare SSH Authentication +==== +---- +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 +:Read Input Variables (Dev Environment) +==== +server_ip=string +worker_ips=list(string) +ssh_user=string +ssh_private_key=string +---- +and optional parameters; -:Setup SSH Config; -note right: Creates temporary SSH config for secure connections +:Setup SSH Config +==== +---- +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 +:Install K3s Server +==== +action=curl -sfL https://get.k3s.io +mode=server +k3s_version=latest +---- +Configures node as a Kubernetes server; -:Store Kubeconfig; -:Generate Node Token; -note right: Required for worker nodes to join the cluster +:Store Kubeconfig +==== +source=/etc/rancher/k3s/k3s.yaml +target=/tmp/k3s-terraform/k3s.yaml +permissions=644; + +:Generate Node Token +==== +source=/var/lib/rancher/k3s/server/node-token +target=/tmp/k3s-terraform/node-token +permissions=644 +---- +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 K3s Kubeconfig +==== +remote_path=/tmp/k3s-terraform/k3s.yaml +local_path='${kubeconfig_path}' +method=scp +---- +Makes it accessible locally and updates server URL in config; -:Retrieve Node Token; -note right: Securely transfer the token to local environment +:Retrieve Node Token +==== +remote_path=/tmp/k3s-terraform/node-token +local_path='${node_token_path}' +method=scp +---- +Securely transfer the token to local environment; |Worker Nodes| fork - :Worker Node 1; - note right: For each worker node in parallel + :Worker Node 1 + ==== + hostname=${worker_ips[0]} + ---- + For each worker node in parallel; fork again - :Worker Node 2; + :Worker Node 2 + ==== + hostname=${worker_ips[1]} + ---- + For each worker node in parallel; end fork |Terraform| -:Copy Node Token to Workers; -note right: Securely transfer the join token to each worker +:Copy Node Token to Workers +==== +source='${node_token_path}' +destination=/tmp/k3s-terraform/node-token +method=scp +---- +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 + :Install K3s Agent (Worker 1) + ==== + action=curl -sfL https://get.k3s.io + mode=agent + server_url=https://${server_ip}:6443 + token=node-token + ---- + Connects to server using token and registers as a worker node; fork again - :Install K3s Agent (Worker 2); + :Install K3s Agent (Worker 2) + ==== + action=curl -sfL https://get.k3s.io + mode=agent + server_url=https://${server_ip}:6443 + token=node-token + ---- + Connects to server using token and registers as a worker node; end fork |Terraform| -:Cluster is Ready; -note right - All nodes are provisioned - Kubeconfig is available locally - Cluster can be accessed via kubectl -end note +:Cluster is Ready +==== +kubeconfig=available +nodes=registered +state=running +---- +All nodes are provisioned and cluster can be accessed via kubectl; |Client| -:Access Kubernetes Cluster; -note right: Using generated kubeconfig at ~/.kube/config or as specified +:Access Kubernetes Cluster +==== +kubeconfig='${kubeconfig_path}' +commands=kubectl +---- +Using generated kubeconfig at specified location; stop diff --git a/docs/prompt.md b/docs/prompt.md index 37dcbe7..85adebd 100644 --- a/docs/prompt.md +++ b/docs/prompt.md @@ -51,6 +51,48 @@ IMPORTANT CONSIDERATIONS: 5. Implement validation for input variables where appropriate. ``` +## Diagram Formatting Guidelines + +When interpreting the PlantUML diagrams, note that they follow specific formatting conventions to clearly represent infrastructure components and their relationships. + +### Activity Diagram Formatting + +Activity diagrams use a structured format with header separators (====) and detail separators (----): + +``` +:Activity Name +==== +parameter1=value1 +parameter2=value2 +parameter3=value3 +---- +Additional context or explanation; +``` + +The parameters section contains key configuration values, and variables are properly escaped with single quotes when they contain special characters (like Terraform variables): + +Example: `local_path='${kubeconfig_path}'` instead of `local_path=${kubeconfig_path}` + +### Component Diagram Formatting + +Component diagrams use the C4 model approach with consistent tagging: + +``` +Component(id, "Name", "Technology", "Description", $tags="tag") +``` + +### Sequence Diagram Formatting + +Sequence diagrams show detailed interactions with parameters and context similar to activity diagrams, using the same header/detail separator pattern. + +### Deployment Diagram Formatting + +Deployment diagrams use consistent stereotypes (<>, <>, <>) and clear connection representations. + +### Class Diagram Formatting + +Class diagrams represent Terraform resources as UML classes with proper property types and relationships. + ## Modifying the Infrastructure To modify the infrastructure, you can: diff --git a/terraform/infra/dev/terraform.tfvars b/terraform/infra/dev/terraform.tfvars index 2932410..35bdc9a 100644 --- a/terraform/infra/dev/terraform.tfvars +++ b/terraform/infra/dev/terraform.tfvars @@ -1,28 +1,28 @@ # K3s Server Configuration -server_ip = "192.168.1.100" # Replace with your server IP -worker_ips = [ # Replace with your worker IPs - "192.168.1.101", - "192.168.1.102" +server_ip = "reg.benadis.org" # Replace with your server IP +worker_ips = [ # Replace with your worker IPs + "worker1.benadis.org", + "worker2.benadis.org" ] -ssh_user = "ubuntu" # Replace with your SSH username -ssh_private_key = "~/.ssh/id_rsa" # Path to your private SSH key -replace_url = "" # Optional: URL to replace in kubeconfig, leave empty to use server_ip +ssh_user = "root" # Replace with your SSH username +ssh_private_key = "~/.ssh/id_rsa" # Path to your private SSH key +replace_url = "reg.benadis.org" # Optional: URL to replace in kubeconfig, leave empty to use server_ip # Cluster Configuration -domain = "reg.benadis.org" # Your domain name -k3s_version = "v1.27.3+k3s1" # K3s version to install -k3s_channel = "stable" # K3s release channel -kubeconfig_path = "~/.kube/config" # Where to save kubeconfig -node_token_path = "/tmp/node-token" # Where to save node token +domain = "reg.benadis.org" # Your domain name +k3s_version = "latest" # K3s version to install +k3s_channel = "stable" # K3s release channel +kubeconfig_path = "./k3s.yaml" # Where to save kubeconfig +node_token_path = "./tmp/node-token" # Where to save node token # Optional Features -enable_traefik_dashboard = false # Enable Traefik dashboard -enable_ssl = false # Enable SSL -ssl_cert_path = "" # Path to SSL certificate -ssl_key_path = "" # Path to SSL key -install_argocd = false # Install ArgoCD -enable_ssh_tunnel = false # Enable SSH tunneling +enable_traefik_dashboard = false # Enable Traefik dashboard +enable_ssl = false # Enable SSL +ssl_cert_path = "~/.tls/wildcard.benadis.org.crt" # Path to SSL certificate +ssl_key_path = "~/.tls/wildcard.benadis.org.key" # Path to SSL key +install_argocd = false # Install ArgoCD +enable_ssh_tunnel = false # Enable SSH tunneling # Advanced Configuration -k3s_extra_server_args = "" # Extra args for K3s server -k3s_extra_agent_args = "" # Extra args for K3s agent +k3s_extra_server_args = "" # Extra args for K3s server +k3s_extra_agent_args = "" # Extra args for K3s agent