Conceitos

Topology

A topologia é o mapa do ambiente. Ela é a fonte de verdade para provisionamento, instalação e recriação.

Cluster

Um cluster agrupa nodes do mesmo provider. Hoje o provider suportado é Proxmox.

Node

Um node é a máquina física ou virtual de base que hospeda as VMs.

Virtual Machine

Uma virtual machine (VM) é descrita na topologia. Ela é criada a partir de um Size (CPU, RAM e disco) e de uma Image (o SO base). VMs carregam tags livres para organização.

Image

Uma Image é o template base de VM, como Ubuntu 22.04/24.04 ou Debian 12/13.

Size

Um size descreve recursos de computação: CPU, memória e disco.

Station

Uma station é a unidade onde services são registrados e orquestrados. Pense nela como a topologia operacional do seu homelab: um grupo de serviços que fazem sentido juntos.

Service

Um service é uma capacidade registrada dentro de uma station a partir de um blueprint. Ele guarda nome, blueprint, vault, inputs, VMs alvo ou host, status e histórico de instalação.

Blueprint

Um blueprint é uma receita YAML declarativa para instalar e operar uma capacidade. Blueprints podem ser standalone, com VMs próprias, ou hosted sobre outro service, como ArgoCD sobre k3s.server. O conceito de role interno de um blueprint (ex: server, worker) descreve apenas alvos de instalação dentro daquele blueprint.

Provider

Um provider é a plataforma onde a infraestrutura roda. Hoje o provider suportado é Proxmox.

Vault

O vault é o cofre local cifrado para senhas, chaves SSH, tokens, credenciais de provider e secrets usados pelos services durante a instalação.

Provisionamento

Provisionamento é como o DevStation cria e atualiza VMs. Ele usa um runtime OpenTofu embutido, com arquivos .tf e .tfvars como formato. A ferramenta gerencia essa camada de forma transparente; você não precisa interagir com o OpenTofu diretamente.

MCP

O servidor MCP expõe o DevStation para agentes LLM. Ele vem no mesmo binário único e permite que ferramentas externas leiam a topologia, disparem instalações e consultem o vault.