Organizações, pastas e stacks

O Firstlume organiza a infraestrutura numa árvore: organização → pastas → stacks. A árvore é sua, e não precisa espelhar a estrutura dos repositórios. Configurações definidas no alto da árvore são herdadas abaixo, e qualquer nível pode sobrescrevê-las.

Organizações

Uma instalação tem várias organizações. Cada uma tem um nome de exibição e um slug, o identificador na URL (minúsculas, números e hífen, de 2 a 40 caracteres). Todo dado (pastas, stacks, runs, agents, variáveis, conexões) pertence a exatamente uma organização, e nada cruza entre elas.

Pastas

Uma pasta é um nó livre da árvore. Pastas são opcionais: uma organização pode ter todos os stacks na raiz.

O nome tem de 1 a 100 caracteres, não pode conter / e é único entre irmãos, ignorando maiúsculas e minúsculas.
As pastas podem ter até 10 níveis.
Uma pasta pode ser renomeada. Só pode ser excluída se estiver vazia.
Mover pastas ainda não é possível.

Stacks

Um stack é uma infraestrutura gerenciada. Ele fica numa pasta ou na raiz da organização, e aponta para:

um repositório
uma branch: por padrão, a branch principal do repositório
um caminho: a pasta do repositório que contém .firstlume/config.yaml, como environments/prod, ou . na raiz

environments/
├── prod/
│   ├── .firstlume/config.yaml   → stack com caminho environments/prod
│   └── main.tf
└── edge/
    ├── .firstlume/config.yaml   → stack com caminho environments/edge
    └── main.tf

Vários stacks podem vir do mesmo repositório e da mesma branch, com caminhos diferentes. Cada um tem state, lock, runs, variáveis e configurações próprios. Não podem existir dois stacks numa organização com o mesmo repositório, branch e caminho: eles gerenciariam a mesma infraestrutura com states diferentes.

Excluir um stack não destrói infraestrutura. Um stack com run ativo, ou com recursos no state, não pode ser excluído.

Mover um stack

Um stack pode mudar de pasta ou ir para a raiz: arraste-o na árvore ou use "Move…" na página dele. Antes, a UI mostra o que muda no que ele herda. A mudança é recusada com run na fila, planejando, aguardando aprovação ou aplicando, e quando o destino já tem um stack com o mesmo nome. Runs, state e versões ficam com o stack.

Herança

Para cada configuração, vale o valor do primeiro nível que a define, subindo a partir do stack:

stack → pasta onde está → pasta pai → ... → pasta de nível 1 → organização

Configuração	Campo na API	Quando nenhum nível define
Exigir aprovação antes do apply	`require_approval`	exigida
Intervalo de drift detection	`drift_interval_minutes`	desligado
Confirmar cada exclusão ou recriação	`confirm_destructive`	desligado
Papel do Vault	`vault_role`	nenhum
Variáveis Terraform, de ambiente e de arquivo	`variables`	nenhuma
Credenciais de registry, somadas por host	`registries`	nenhuma

A identidade de uma variável é a categoria mais o nome: region como variável Terraform e region como variável de ambiente são coisas diferentes. Segredos são variáveis com sensitive: true e seguem a mesma regra. O valor nunca é devolvido pela API, em nenhum nível.

Dá para sobrescrever uma variável herdada, mas não apagá-la num nível de baixo.

Exemplo

Organização Acme           TF_VAR_region=us-east-1, segredo DB_PASSWORD=a, aprovação=sim
└── Infra                  (nada)
    ├── prod               segredo DB_PASSWORD=b, drift=a cada 6h
    │   └── stack cluster  (nada)
    │                      → region=us-east-1 (Acme), DB_PASSWORD=b (prod),
    │                        aprovação=sim (Acme), drift=6h (prod)
    └── dev                aprovação=não
        └── stack dev01    TF_VAR_region=sa-east-1
                           → region=sa-east-1 (stack), DB_PASSWORD=a (Acme),
                             aprovação=não (dev), drift=off (padrão)

Em qualquer nível, a UI mostra o que está definido ali, o que vem herdado e de onde, e o que aquele nível sobrescreve.

Quando os valores são lidos

O plan usa as variáveis efetivas na hora em que começa.
O apply usa as mesmas variáveis do plan, de um snapshot guardado criptografado no run, mesmo que alguém mude uma pasta entre os dois.
A regra de aprovação é lida quando o plan termina.

Configurações na API

GET|PUT /api/v1/orgs/{org}/settings
GET|PUT /api/v1/orgs/{org}/folders/{id}/settings
GET|PUT /api/v1/orgs/{org}/stacks/{id}/settings

Um PUT substitui o que o nível define. Mande as configurações e as variáveis do nível a cada vez. Uma configuração que ficar de fora volta a herdar. Uma variável sensível enviada com valor vazio mantém o valor guardado. A única exceção é registries: sem o campo, as credenciais do nível ficam como estão.

Conexão Git

Uma organização pode se conectar a uma conta do Git. O Gitea é o primeiro provedor. No Gitea, a conta é uma organização ou um usuário, e a credencial é um token de serviço de uma conta de bot, com leitura dos repositórios. O token é separado do login de qualquer pessoa, então nada para quando alguém sai. Ele fica criptografado e nunca é devolvido pela API.

Com a conexão, o Firstlume lista os repositórios da conta e encontra as pastas .firstlume de uma branch sem clonar. Ele marca cada uma como válida ou inválida e mostra se já existe um stack usando. O assistente "Novo stack" usa isso.

Sem conexão, um stack pode usar qualquer repositório Git pela URL de clone, com um token opcional.

Membros e acesso

Todo usuário logado com acesso a uma organização é administrador dela. Papéis mais finos estão planejados.

Quem vê o quê

Quem	Organizações que vê	Cria organização
Token admin	todas	sim
Administrador da instalação, membro de um grupo de `auth.oidc.adminGroups`	todas	sim
Outro usuário logado	só aquelas em que é membro	não

Uma organização em que a pessoa não é membro responde 404 em todas as rotas, inclusive stacks, runs e state, para não revelar que ela existe. Quem não tem nenhuma organização vê uma tela com o próprio login, pronto para mandar a um administrador, sem opção de criar uma.

auth.oidc.allowedGroups decide só quem entra. A lista não dá acesso a nenhuma organização: isso é convite, ou ser administrador da instalação.

Convites

Membros e administradores da instalação convidam pelo login do Gitea:

curl -s -H "$H" $O/members -d '{"login": "maria"}'

Quem já entrou alguma vez vira membro na hora.
Quem nunca entrou fica com um convite pendente, que vale no primeiro login. O login é comparado sem diferenciar maiúsculas.
Convites pendentes aparecem na lista de membros, podem ser cancelados e expiram em 30 dias. O Firstlume não confere se o login existe, então um erro de digitação aparece como um convite que nunca é aceito.
Remover um membro vale na hora, mesmo com sessão aberta, e não cancela os runs que a pessoa já iniciou.

Runs, aprovações e alterações de configuração registram quem fez: o login da pessoa ou admin-token.