Instalar com Helm

Um chart só instala os dois componentes: o control plane (API, UI e server) e o agent, que cria os Jobs dos runs. Os comandos abaixo usam deploy/helm/firstlume, o caminho do chart no repositório do Firstlume.

A imagem do container ainda não é pública. Para pedir acesso, escreva para hello@firstlume.io.

Tudo num cluster só

Com banco gerenciado:

helm install firstlume deploy/helm/firstlume -n firstlume --create-namespace \
  --set controlPlane.database.url='postgres://user:pass@host:5432/firstlume?sslmode=require'

A URL também pode vir de um Secret existente, com controlPlane.database.existingSecret.

Para testar sem banco externo, use --set postgresql.enabled=true. É uma instância única e sem backup, só para teste.

Acessar o server

Ligue o ingress e defina o endereço público:

helm upgrade firstlume deploy/helm/firstlume -n firstlume --reuse-values \
  --set controlPlane.ingress.enabled=true \
  --set controlPlane.ingress.host=firstlume.example.com \
  --set controlPlane.publicURL=https://firstlume.example.com

O padrão de controlPlane.publicURL é o host do ingress. O retorno do login e os JWTs que o Vault confere usam esse endereço.

O token admin fica no Secret da release:

kubectl -n firstlume get secret firstlume-control-plane \
  -o jsonpath='{.data.admin-token}' | base64 -d

Abra https://firstlume.example.com e entre com ele, ou siga para Seu primeiro run.

A imagem

A imagem é ghcr.io/bsteigleder/firstlume, para amd64 e arm64. As tags são main, sha-<commit> e, nas tags vX.Y.Z, X.Y.Z.

Crie um Secret de pull e passe para o chart:

--set imagePullSecrets[0].name=<secret>

O server, o agent e os Jobs dos runs (pela ServiceAccount do executor) passam a usá-lo. Num cluster com registry interno, prefira um proxy-cache dele apontando para o GHCR, com a credencial num lugar só.

Um agent adicional em outro cluster

Um agent pertence a uma organização e só recebe runs dela. Crie o token com POST /api/v1/orgs/{org}/agents:

curl -s -H "Authorization: Bearer $FIRSTLUME_ADMIN_TOKEN" \
  https://firstlume.example.com/api/v1/orgs/default/agents -d '{"name": "cluster-b"}'

Depois instale só o agent no outro cluster:

helm install firstlume-agent deploy/helm/firstlume -n firstlume --create-namespace \
  --set controlPlane.enabled=false \
  --set agent.name=cluster-b \
  --set agent.apiUrl=https://firstlume.example.com \
  --set agent.token=fla_...

O agent só faz requisições de saída, então a API nunca precisa alcançá-lo.

Onde os runs rodam

Os Jobs dos runs aceitam agent.executor.nodeSelector, tolerations e affinity (inclusive anti-afinidade), com os mesmos campos de um pod. Use quando só alguns nodes alcançam as máquinas que o código configura.

Para código que fala com a API do próprio cluster (providers kubernetes e helm sem kubeconfig), ligue agent.executor.automountServiceAccountToken e dê permissões à ServiceAccount do executor com agent.executor.serviceAccount.clusterRoles. Elas valem para todos os runs daquele agent. Para permissões diferentes, use outro agent.

As credenciais de nuvem vêm da identidade do pod (IRSA, Workload Identity), por anotações em agent.executor.serviceAccount.annotations.

Sem isso, só o token admin funciona. O Gitea é o primeiro provedor. Outros provedores OIDC usam as mesmas configurações.

Cadastre um app OAuth confidencial no provedor, com <publicURL>/auth/callback como endereço de retorno, e deixe o client secret num Secret existente. Todos os valores ficam em controlPlane.:

Valor	Padrão
`publicURL`	o host do ingress	obrigatório com OIDC: sem ele e sem host de ingress, o server não sobe
`auth.oidc.enabled`	`false`
`auth.oidc.providerName`	`Gitea`	o texto do botão de login
`auth.oidc.issuer`		por exemplo `https://gitea.example.com`
`auth.oidc.clientId`
`auth.oidc.existingSecret`, `auth.oidc.clientSecretKey`	key `client-secret`	o client secret nunca vai nos values
`auth.oidc.scopes`	`openid profile email groups`
`auth.oidc.groupsClaim`	`groups`
`auth.oidc.allowedGroups`	vazio	quando preenchido, só membros desses grupos entram
`auth.oidc.adminGroups`	vazio	os membros são administradores da instalação
`auth.adminTokenLogin`	`true`	mostra "Usar token admin" na tela de login

O Gitea manda as organizações (acme) e os times (acme:infra) como grupos, e as duas listas aceitam os dois formatos. Se o provedor estiver fora do ar quando o server sobe, ele sobe mesmo assim, com o token admin funcionando, e continua tentando.

Fazer login não dá acesso a nenhuma organização. Veja Organizações, pastas e stacks.

Faça backup da chave secreta

Faça backup da chave secret-key do Secret <release>-control-plane. Sem ela não dá para recuperar os dados criptografados: variáveis sensíveis, tokens git, planos e versões de state. O Secret é preservado no helm uninstall.

Todas as opções

O values.yaml do chart lista todas as opções, com comentários. O storage de state tem página própria: Onde o state fica.