Skip to main content

Convenção de Nomes — SSM Parameter Store

Este documento descreve o padrão de paths adotado no AWS SSM Parameter Store para separar segredos da plataforma e de pipelines.

Estrutura geral​

Todos os segredos gerenciados pela plataforma vivem sob o namespace /arca/:

/arca/{...}

Padrão dentro de /arca/​

/arca/{env}/{team}/{app}/{key}

Segredos acessíveis pelo cluster (External Secrets)​

Paths que seguem o padrão com ambiente explícito (prod, staging, etc.) são os únicos que o ClusterSecretStore tem permissão de leitura via IAM:

/arca/prod/kelbi/api/db-password
/arca/prod/kelbi/api/jwt-secret
/arca/prod/kelbi/game-server/secret-key
/arca/staging/kelbi/api/db-password

Segredos de pipeline (sem env no path)​

Paths sem segmento de ambiente são usados exclusivamente por pipelines e workflows. O ClusterSecretStore não tem acesso a esses paths:

/arca/github-deploy-apps/token
/arca/repos/kelbi-applications/token
Regra de ouro

Se o path não começa com /arca/{env}/, o cluster não pode — e não deve — lê-lo.

Por que essa separação funciona​

A policy IAM do ClusterSecretStore é restrita a paths com ambiente explícito:

{
  "Effect": "Allow",
  "Action": ["ssm:GetParameter", "ssm:GetParameters", "ssm:GetParametersByPath"],
  "Resource": [
    "arn:aws:ssm:us-east-1:*:parameter/arca/prod/*",
    "arn:aws:ssm:us-east-1:*:parameter/arca/staging/*"
  ]
}

Isso garante que tokens de pipeline com permissões adicionais (escrita em repositórios, criação de releases, etc.) nunca sejam expostos ao cluster, mesmo que um ExternalSecret seja criado por engano apontando para esse path.

Separação por time​

O segmento {team} permite isolar segredos entre times com políticas IAM independentes:

/arca/prod/kelbi/...       ← time Kelbi
/arca/prod/outro-time/...  ← time futuro, policy separada

Cada time pode ter um role IAM com acesso restrito ao próprio path.

Uso com External Secrets Operator​

Para expor segredos de um app no cluster, crie um ExternalSecret referenciando o path do app:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: kelbi-api-secrets
  namespace: apps
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: cluster-secret-store
    kind: ClusterSecretStore
  target:
    name: kelbi-api-secrets
  dataFrom:
    - find:
        path: /arca/prod/kelbi/api

Isso cria um Secret do Kubernetes com todas as chaves encontradas sob /arca/prod/kelbi/api/.

Para buscar uma chave específica:

  data:
    - secretKey: db-password
      remoteRef:
        key: /arca/prod/kelbi/api/db-password

Resumo visual​

/arca/
├── prod/                  ← ClusterSecretStore tem acesso
│   └── kelbi/
│       ├── api/
│       │   ├── db-password
│       │   └── jwt-secret
│       └── game-server/
│           └── secret-key
├── staging/               ← ClusterSecretStore tem acesso
│   └── kelbi/
│       └── api/
│           └── db-password
├── github-deploy-apps/    ← somente pipelines
│   └── token
└── repos/                 ← somente pipelines
    └── kelbi-applications/
        └── token