XoR/apk-deploy-02
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Исправления в документации.

Browse Source
This commit is contained in:
Бекетов Дмитрий Сергеевич
2025-03-28 13:39:16 +03:00
parent 65c06723a9
commit 7bf400ac19
4 changed files with 302 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
docs/diagram-promt.md Normal file
View File

@@ -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 <<Type>> {
rectangle "Subcomponent" as subAlias
}
```
### Key Formatting Rules
1. **Component Containers**: Group related components inside rectangles
2. **Stereotypes**: Use `<<Server>>`, `<<Worker>>`, `<<Config>>` 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.

138
docs/k3s_infrastructure_activity_diagram.puml
View File

@@ -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

42
docs/prompt.md
View File

@@ -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 (<<Server>>, <<Worker>>, <<Config>>) 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:

40
terraform/infra/dev/terraform.tfvars
View File

@@ -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