Fiap Fase4 Infra Configuration

---
alwaysApply: true
---

🧩 Regras gerais deste repositório (Infra / Terraform / Kubernetes)

Este repositório é responsável por infraestrutura, não por lógica de negócio.

Tudo que for criado na cloud deve ser descrito em Terraform ou em manifestos Kubernetes – nada de "ajeitar no console" sem voltar para o código.

Manter o padrão de organização atual:

Infra AWS: diretório terraform/

Manifests Kubernetes: diretório k8s/ (subpastas app/ e infra/)

Sempre que copiar algo de outro projeto, adaptar nomes, variáveis e comentários para o contexto atual (não deixar fastfood perdido se o nome do projeto mudar).

=====================
1. REGRAS DE TERRAFORM
=====================

1.1. Versão e providers

Sempre usar bloco terraform com required_version >= 1.0.

Sempre usar o provider AWS da família ~> 5.0 (como já está em providers.tf).

O provider principal deve continuar assim:

```hcl
provider "aws" {
  region = var.aws_region
}
```

Não hardcodear a região diretamente no provider, sempre via var.aws_region.

1.2. Backend remoto (state)

O backend deve ser sempre S3, nunca local.

O arquivo backend.tf é o dono único da configuração do backend.

Não alterar o bucket de state sem motivo fortíssimo; se precisar trocar:

Ajustar bucket, key e region em backend.tf.

Garantir que o bucket exista antes de rodar terraform init.

Nunca commitar terraform.tfstate ou .terraform/ no repositório.

1.3. Organização de arquivos

Manter um arquivo por responsabilidade, como já está hoje:

providers.tf → versão do Terraform e provider AWS

backend.tf → configuração de backend S3

datasource.tf → data "aws_*" e helpers de descoberta

network.tf → VPC default e subnets do EKS

sg.tf → Security Group principal (cluster / exposição externa)

eks-cluster.tf → recurso aws_eks_cluster

eks-node.tf → recurso aws_eks_node_group

eks-access-policy.tf / access-entry.tf → acesso ao cluster (IAM/EKS)

ecr.tf → repositórios ECR

network-rds.tf → regra SG entre EKS e RDS

variables.tf → todas as variáveis de entrada

outputs.tf → todos os outputs públicos

Ao adicionar novos recursos, reutilizar esse padrão:

Se for algo de rede → network-*.tf

Se for algo de segurança → sg-*.tf

Se for algo de observabilidade → monitoring-*.tf

Não criar arquivos gigantes com tudo misturado.

1.4. Variáveis, nomes e tags

Todas as coisas "imutáveis por ambiente" devem ser parametrizadas:

project_name

env

aws_region

lab_role

policy_arn

principal_arn

Manter o padrão de nome de recursos:

```hcl
name = "${var.project_name}-api"
name = "eks-${var.project_name}"
node_group_name = "nodeg-${var.project_name}"
```

Sempre usar tags mínimas em todos os recursos suportados:

```hcl
tags = {
  Name        = "${var.project_name}-<alguma-coisa>"
  Environment = var.env
  Project     = var.project_name
}
```

Quando adicionar novos recursos (SQS, Dynamo, RDS, etc.), seguir esse mesmo padrão de tags e nomes.

1.5. Uso de AWS Academy (LabRole) e autenticação da infra

Não criar novas roles "admin" no Terraform.

Para o cluster EKS e Node Group:

role_arn do EKS deve usar var.lab_role.

node_role_arn do Node Group deve usar var.lab_role.

var.lab_role, var.policy_arn e var.principal_arn devem continuar configuráveis via variables.tf.

Manter e usar os recursos de acesso do EKS:

aws_eks_access_policy_association

aws_eks_access_entry

Esses recursos devem continuar apontando para:

cluster_name = aws_eks_cluster.cluster.name

policy_arn = var.policy_arn

principal_arn = var.principal_arn

Não hardcodear ARN da role do aluno dentro dos recursos; sempre usar var.principal_arn e var.lab_role.

1.6. VPC e Subnets

Sempre usar a VPC default da conta:

```hcl
data "aws_vpc" "default" { default = true }
```

Subnets do cluster devem ser descobertas via data "aws_subnets" filtrando pela VPC default e pelas AZs permitidas:

Excluir explicitamente us-east-1e (não suportada no Academy).

Não criar uma nova VPC neste projeto de infra – isso é restrito no ambiente AWS Academy e não é necessário para a entrega.

1.7. Security Groups e Regras

O security group principal (arquivo sg.tf) é responsável pela exposição pública (HTTP/HTTPS):

Expor apenas portas necessárias (80/443).

Egress liberado (0.0.0.0/0) é aceitável para MVP, mas não abrir ingress desnecessário.

Para comunicação EKS → RDS:

Usar network-rds.tf para criar regras via aws_security_group_rule.

Nunca abrir RDS para 0.0.0.0/0.

Sempre restringir a SG rule usando eks_node_sg_id + rds_sg_id (variáveis).

A porta deve ser compatível com o banco:

MySQL: 3306

PostgreSQL: 5432

Não misturar regras de SG da aplicação com regras de SG do banco no mesmo bloco sem necessidade.

1.8. Cluster EKS e Node Group (padrão)

O recurso de cluster deve seguir a linha atual:

```hcl
resource "aws_eks_cluster" "cluster" {
  name = "eks-${var.project_name}"

  access_config {
    authentication_mode = "API"
  }

  role_arn = var.lab_role
  version  = var.eks_version

  vpc_config {
    subnet_ids         = data.aws_subnets.eks_supported.ids
    security_group_ids = [aws_security_group.sg.id]
  }
}
```

O Node Group deve:

Usar node_role_arn = var.lab_role

Utilizar scaling_config com min=2, desired=2, max=3 (ou parametrizar isso se necessário).

Usar update_config { max_unavailable = 1 }.

Pegar instance_types de var.instance_types.

1.9. ECR – Repositórios de imagens

Manter o padrão de ECR com var.manage_ecr (feature flag):

Quando manage_ecr = true → cria os repositórios.

Quando manage_ecr = false → não cria nada e devolve mensagens amigáveis nos outputs.

Todos os ECR precisam:

image_tag_mutability = "MUTABLE" (a não ser que você tenha motivo para IMMUTABLE).

image_scanning_configuration { scan_on_push = true }.

force_delete = true para facilitar limpeza no ambiente de laboratório.

Lifecycle policy para expirar imagens antigas/untagged (já existe, manter o padrão).

Sempre nomear ECR com ${var.project_name}-<sufixo> e tags padrão.

1.10. Data sources e outputs

Nunca hardcodear IDs de recursos que possam ser descobertos com data "aws_*".

datasource.tf deve centralizar:

data "aws_caller_identity" "current"

data "aws_eks_cluster" / data "aws_eks_cluster_auth" para pegar endpoint e CA.

outputs.tf deve:

Expor somente o que for útil para:

Configurar o kubeconfig do EKS

Pipelines de deploy dos serviços

Conectar RDS/EKS

Exemplo obrigatório:

eks_name

eks_endpoint

eks_ca

URLs dos ECR (quando manage_ecr = true)

1.11. Boas práticas gerais de código Terraform

Sempre rodar:

terraform fmt antes de commitar.

terraform validate antes de aplicar.

**OBRIGATÓRIO:** Antes de commitar qualquer mudança em arquivos Terraform:

1. Executar `terraform init` (se novos módulos foram adicionados)
2. Executar `terraform fmt -recursive` para formatar todos os arquivos
3. Executar `terraform validate` e garantir que retorna "Success! The configuration is valid."
4. Corrigir todos os erros de validação antes de commitar

Nenhum código Terraform deve ser commitado com erros de validação.

Não usar variáveis locais para coisas sensíveis (senhas, tokens).

Senhas, tokens, connection strings:

Nunca em texto puro em .tf.

Devem ir para:

AWS Secrets Manager (ideal)

Ou, no mínimo, como variáveis de ambiente nos pipelines, injetadas em Kubernetes Secret.

Não commitar arquivos:

*.tfstate

*.tfstate.backup

.terraform/

Arquivos .tfplan (como plan.tfplan).

=====================
2. REGRAS DE KUBERNETES (manifests em /k8s)
=====================

2.1. Organização

Manifests de aplicação ficam em k8s/app/<serviço>/.

Exemplo atual: k8s/app/api/ contém:

api-deployment.yaml

api-service.yaml

api-hpa.yaml

Manifests de infraestrutura/shared ficam em k8s/infra/:

namespace.yaml

infra/configmap/

infra/metrics/ (metrics-server, etc.)

2.2. Namespaces

Nunca usar o namespace default para aplicações desse projeto.

Sempre usar um Namespace explícito (arquivo namespace.yaml) com placeholder <NAMESPACE>.

Para cada ambiente ou contexto (orderhub, paystream, kitchenflow), usar um namespace claro:

orderhub

paystream

kitchenflow

Antes de criar novos manifests, verificar se:

metadata.namespace está definido corretamente.

O namespace está sendo criado por manifesto infra (namespace.yaml).

2.3. Deployments

Sempre usar kind: Deployment para as APIs.

Padrões obrigatórios:

strategy: RollingUpdate com maxUnavailable: 0 e maxSurge: 1 (ou valores similares de rollout seguro).

spec.selector.matchLabels deve bater com spec.template.metadata.labels.

Imagem deve vir de ECR, nunca de Docker Hub público para a aplicação principal.

Container principal:

Ter ports.containerPort nomeado (name: http) quando for HTTP.

Ter resources.requests e resources.limits definidos (CPU e memória).

Variáveis de ambiente sensíveis via envFrom.secretRef.

Configuração não sensível via envFrom.configMapRef.

2.4. Services

Cada aplicação exposta externamente deve ter um Service separado.

Para comunicação pública:

Usar type: LoadBalancer.

Manter annotations para NLB / internet-facing, como no exemplo atual:

service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing

service.beta.kubernetes.io/aws-load-balancer-type: nlb

spec.selector deve casar com os labels do Deployment.

externalTrafficPolicy: Cluster é aceitável para o seu caso; não mudar para Local sem necessidade.

2.5. HPA (Horizontal Pod Autoscaler)

Sempre usar autoscaling/v2 com métricas de CPU (e opcionalmente memória).

Boas práticas:

minReplicas ≥ 2 para alta disponibilidade.

maxReplicas compatível com a capacidade do Node Group (não maior que o que a infra aguenta).

averageUtilization de CPU em 60–70% (como você já tem).

2.6. ConfigMaps vs Secrets

ConfigMap:

Somente valores não sensíveis (URLs, audience, issuer, tempos de expiração, nomes de serviço).

Secret:

Tokens, client secrets do Cognito, connection strings completas, senhas de banco, chaves JWT, etc.

Nunca commitar valores reais de secrets.

Usar placeholders (<TO_BE_FILLED_BY_PIPELINE>) ou variáveis de ambiente nos pipelines.

Nome dos objetos:

ConfigMap padrão: fastfood-config (ou equivalente por serviço).

Secret padrão: fastfood-secrets (ou equivalente por serviço).

=====================
3. REGRAS DE AUTENTICAÇÃO (Infra + Kubernetes)
=====================

3.1. Autenticação na AWS (Terraform / Pipelines)

Pipelines (GitHub Actions) não fazem parte deste rule, mas estes princípios valem:

Não colocar credenciais fixas em .tf.

Qualquer credencial que o Terraform precise deve vir de:

aws-actions/configure-aws-credentials no pipeline, usando a LabRole da Academy.

Se for necessário assumir role:

Usar role-to-assume: var.lab_role ou valores equivalentes configurados no pipeline, não no código.

3.2. Acesso ao cluster EKS

Nunca versionar kubeconfig no repositório.

Acesso ao cluster deve ser obtido via CLI/pipeline:

```bash
aws eks update-kubeconfig --name <eks_name> --region <aws_region> --role-arn <lab_role>
```

aws_eks_access_entry + aws_eks_access_policy_association são a fonte da verdade de quem pode administrar o cluster.

Não adicionar usuários/roles diretamente no aws-auth ConfigMap manualmente; preferir o modelo novo de access entries.

3.3. Tokens de aplicação (JWT / Cognito / etc.)

O Terraform não deve gerenciar tokens JWT nem segredos de Cognito diretamente.

Apenas:

Criar/permitir infra necessária (RDS, EKS, Lambdas, etc.).

Permitir que os serviços de aplicação usem ConfigMap/Secrets para autenticação.

Nos manifests Kubernetes:

Qualquer configuração de JWT (issuer, audience, expiration) deve estar em ConfigMap.

Qualquer segredo (chave privada, client secret de IdP, etc.) deve estar em Secret.

=====================
4. DEFINIÇÃO DE "FEITO" PARA MUDANÇAS DE INFRA
=====================

Ao alterar ou adicionar Terraform ou manifests Kubernetes, considere "OK" somente se:

terraform fmt -recursive foi executado e formatou todos os arquivos.

terraform init foi executado (se novos módulos foram adicionados).

terraform validate foi executado e retornou "Success! The configuration is valid." sem erros.

Todos os erros de validação foram corrigidos antes de commitar.

Não há TODO pendente em blocos críticos.

Os novos recursos:

Estão com nomes e tags seguindo o padrão.

Respeitam a VPC default.

Têm segurança mínima (nada exposto desnecessariamente).

Manifests Kubernetes:

Referenciam o namespace correto.

Têm Deployment + Service + HPA quando aplicável.

Separaram ConfigMap e Secret corretamente.

Nenhuma credencial foi exposta em .tf ou .yaml.