carnufex/gitops-app-onboarding

Integração de aplicações GitOps

O método é genérico; os fatos do cluster (caminhos, listas de permissões, registry, classes de armazenamento, gateways, aplicações de referência, onde os alertas residem) estão em .claude/profiles/gitops.md no repositório GitOps. Leia o perfil primeiro. Se estiver faltando, crie-o a partir de templates/profile.md lendo o repositório (o ApplicationSet, o AppProject, o armazenamento de segredos, uma ou duas aplicações existentes, a pasta de monitoramento) e informe ao usuário em uma linha que você o escreveu. Nunca adivinhe um caminho.

Como uma aplicação se torna ativa

• Um ApplicationSet com um gerador de diretórios transforma cada pasta sob o diretório de aplicações do perfil em seu próprio aplicativo e namespace do ArgoCD. Uma pasta é implantada assim que tiver um kustomization.yaml válido.
• Nada chega ao cluster até que seja enviado para o branch que o ArgoCD monitora. Uma alteração aplicada apenas com kubectl é revertida na próxima sincronização.
• Componentes da plataforma (CNI, armazenamento, controladores) não vão para o diretório de aplicações; o perfil diz onde eles ficam.

Um novo namespace deve estar em todas as listas de permissões, no mesmo commit

A seção Listas de permissões do perfil lista todos os arquivos que mencionam namespaces (tipicamente: os destinations do AppProject, as conditions do ClusterSecretStore, e o pool de IPs do LoadBalancer e os seletores de anúncio L2/BGP se a aplicação precisar de um IP de LB). Se faltar um, a aplicação falha ao sincronizar, seus ExternalSecrets ficam com SecretSyncError, ou seu IP de LB nunca é anunciado. Adicione o namespace a todos os arquivos aplicáveis no commit que adiciona a pasta.

Ordem de integração (menor formato seguro primeiro)

1. ns.yaml: o namespace com os rótulos de segurança de pod do perfil.
2. kustomization.yaml: recursos em ordem de dependência (namespace e configuração, depois cargas de trabalho, depois rotas).
3. Segredos: crie as entradas no backend de segredos primeiro (perfil: Segredos), depois um ExternalSecret para cada segredo. Nunca faça commit de valores de segredos; segredos de inicialização e de acesso de emergência ficam fora do Git.
4. Manifestos de tempo de execução (Deployment, Service, PVCs, ConfigMap), somente após os nomes das imagens e os nomes dos segredos serem confirmados. Sondagens de prontidão e vivacidade em um endpoint de saúde real, solicitações de recursos e o contexto de segurança exigido pelo nível de segurança de pod do namespace.
5. O sinal das 3 da manhã (abaixo), na mesma alteração da carga de trabalho.
6. A rota, por último, assim que a imagem for executada, os segredos forem resolvidos e as sondagens passarem (veja Exposição).
7. Um README.md na pasta da aplicação: o que é, suas dependências de tempo de execução, seus nomes de segredos, seu armazenamento, como é acessada.

Convenções (o perfil tem os valores)

• Imagens: fixe tag@sha256:<digest> a menos que o perfil diga que a aplicação segue uma tag móvel; imagens próprias vêm do registry do perfil com tags imutáveis. Imagens privadas precisam do padrão de pull-secret do perfil.
• Segredos: recursos ExternalSecret contra o ClusterSecretStore do perfil, nunca dados Secret inline.
• Armazenamento: as classes de armazenamento do perfil e para que cada uma serve (pequenos volumes de bloco replicados vs. dados em massa em NFS). Limites de capacidade no perfil são limites rígidos.
• Roteamento: gateways público e interno e seus padrões de host; TCP/UDP bruto através de um serviço LoadBalancer.
• Copie a forma das Aplicações de referência do perfil em vez de inventar uma nova.

O sinal das 3 da manhã

Pergunte antes de enviar: se esta aplicação quebrar às 3 da manhã, como alguém saberia, e o que olhariam primeiro?

• A aplicação deve ser coberta por um alerta que atinja uma pessoa: adicione seu namespace e carga de trabalho às regras de alerta de Monitoramento do perfil (réplicas indisponíveis, loops de crash, pods ou PVCs pendentes), ou adicione uma regra específica da aplicação se ela tiver um modo de falha que essas não conseguem ver (uma fila que para de drenar, um job que para de executar, um certificado ou token expirando).
• Os logs da aplicação devem dizer o que falhou com os IDs que localizam o problema; se a imagem é nossa e eles não fazem isso, isso é uma tarefa.
• Escreva o sinal na mensagem do commit: 3 am: <nome do alerta> via <receptor>.

Exposição

Não adicione uma rota pública até que a aplicação esteja em execução, seus segredos sejam resolvidos e suas verificações de saúde passem. Ferramentas apenas internas se conectam apenas ao gateway interno e não recebem rota pública. Quando você expor publicamente, siga as Skills relacionadas do perfil para o caminho de entrada público (DNS, túnel, certificados).

Após a integração (verifique, não assuma)

1. Envie; observe o novo aplicativo aparecer e convergir (kubectl get applications.argoproj.io -n argocd, ou os comandos Verificar do perfil). Solicite uma atualização para pular o atraso de polling se o perfil mostrar como.
2. Verifique: aplicativo Synced e Healthy, cada ExternalSecret SecretSynced, pods prontos, a rota responde e a regra de alerta está carregada (ela aparece na lista de regras da pilha de monitoramento).
3. Se não convergir, percorra a cadeia de cima para baixo: listas de permissões → segredos → erros de sincronização do ArgoCD → pods → roteamento. As listas de permissões são o culpado usual. As Skills relacionadas do perfil nomeiam a skill de diagnóstico do cluster.