144 lines
4.7 KiB
Markdown
144 lines
4.7 KiB
Markdown
# 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. |