Nomenclatura e Padronização de Infraestrutura¶

Status¶

Aprovado (Atualizado em 2026-01-08)

Contexto¶

A infraestrutura necessita de um padrão consistente para máquinas virtuais, hostnames, domínios e serviços para facilitar a automação, observabilidade e escalabilidade.

Decisão¶

Adotar o seguinte padrão único para todas as VMs e hostnames:

<env>-<scope>-<role>-<seq>

Componentes¶

Campo	Descrição	Exemplos
`env`	Ambiente (abreviado)	`prod`, `stg`, `ops`, `local`
`scope`	Produto ou domínio funcional	`pagesaude`, `credencia`, `shared`
`role`	Função principal da VM	`app`, `db`, `ai`, `monitor`
`seq`	Número sequencial (zero-padded)	`01`, `02`

Nomenclatura de Ambiente¶

A nomenclatura de ambiente deve ser sempre abreviada em todos os contextos:

Ambiente	Abreviação	Uso
Production	`prod`	Produção
Staging	`stg`	Homologação
Operations	`ops`	Operações (monitoramento central)
Local	`local`	Desenvolvimento local

Essa nomenclatura se aplica a: - deploy_environment no Ansible - Prefixo de hostnames (ex: stg-pagesaude-app-01) - Prefixo de domínios de serviço (ex: grafana-stg.pagesaude.com.br)

Regras¶

O nome da VM deve ser idêntico ao hostname do SO.
Todos os campos devem estar em inglês técnico.
Nunca renomear VMs sem atualizar inventário, monitoramento e automações.

Desenvolvimento Local/Testes¶

Para ambientes locais ou efêmeros, utilizar o TLD reservado .local (ex: grafana.local, traefik.local) para serviços internos.

Nota: O TLD .local é utilizado por conveniência em desenvolvimento. Se houver conflitos com mDNS/Bonjour em determinados ambientes, considere desativar o serviço ou usar /etc/hosts.

Alinhamento: VM vs Hostname vs Subdomínios¶

VM/Hostname: Identifica o ativo (ex: prod-pagesaude-app-01).
Subdomínio: Identifica o serviço (ex: api.pagesaude.com.br).
Regra: Nunca expor hostnames diretamente como endpoints públicos. DNS público deve apontar para serviços.

Padrão de Domínios de Serviço¶

Para serviços internos (ferramentas de operação), usar o formato:

<service>-<env>.pagesaude.com.br

Exemplo de Mapeamento¶

Serviço	Ambiente	Subdomínio
API	prod	`api.pagesaude.com.br`
Grafana	ops	`grafana-ops.pagesaude.com.br`
Traefik	stg	`traefik-stg.pagesaude.com.br`

Gerenciamento de Secrets¶

Os arquivos de secrets são gerenciados localmente em cada ambiente e não são versionados.

Configuração¶

Os compose files utilizam a variável SECRETS_PATH para localizar os arquivos de secrets:

secrets:
  postgres_password:
    file: ${SECRETS_PATH:-./secrets}/postgres_password

O valor de SECRETS_PATH é injetado pelo Ansible a partir da variável secrets_base_dir, que por padrão aponta para /opt/pagesaude/secrets em produção e ./secrets em desenvolvimento local.