Pular para o conteúdo principal

Configuração no repositório (coda.yaml)

O arquivo coda.yaml, na raiz do repositório vinculado a uma aplicação, descreve o ambiente inteiro: serviços, kinds, saúde, escala, variáveis, conexões entre serviços e volumes. A cada push na branch vinculada, o Coda Cloud lê o arquivo do commit e transforma o conteúdo num rascunho do grafo do ambiente.

  • Se o ambiente não é protegido, o rascunho é aplicado na hora (revisão com origem FILE).
  • Se o ambiente é protegido, a revisão fica aguardando aprovação, como qualquer outra mudança.
  • Mudanças destrutivas, como remover um volume com dados, nunca são aplicadas pelo push. Elas ficam no rascunho até um Admin confirmar no canvas.

O ambiente passa a aparecer no portal como gerenciado por arquivo. Edições manuais no canvas continuam possíveis, mas o arquivo vence no próximo push: o rascunho manual é descartado antes de o arquivo ser aplicado.

Exemplo​

# yaml-language-server: $schema=https://docs.<domínio>/schemas/coda.schema.json
version: 1
services:
  api:
    image: registry.<domínio>/acme/api@sha256:3f1c... # opcional se o serviço já existe (build pelo repositório)
    type: web
    port: 8080
    public: true
    health:
      path: /health
    scale:
      instances: 2
      cpuMillis: 250
      memoryMiB: 256
    variables:
      LOG_LEVEL: info
      WORKER_URL: ${{ worker.URL }}
      DATABASE_PASSWORD: ${{ secret.DATABASE_PASSWORD }}
    connects:
      - to: worker
        ports: [9090]
  worker:
    image: registry.<domínio>/acme/worker@sha256:9a7b...
    type: worker
    mounts:
      - volume: data
        path: /data
  data:
    kind: volume
    sizeGiB: 10

environments:
  production:
    services:
      api:
        scale:
          instances: 4

Campos​

CampoDescrição
versionObrigatório. Só a versão 1 é aceita.
services.<nome>Um nó do grafo. O nome segue DNS-1123 (minúsculas, dígitos e -, de 2 a 40 caracteres) e não muda depois de aplicado.
kindapplication (padrão), volume ou os kinds de dados do seu plano.
imageImagem por digest. Pode ser omitida se o serviço já existe e é construído a partir do repositório.
type, port, publicTipo (web ou worker), porta e exposição pública na borda.
healthpath (HTTP), ou command e timeoutSeconds (worker).
scaleinstances, cpuMillis, memoryMiB ou size (tamanho predefinido).
command, argsComando e argumentos do contêiner.
variablesValores públicos, referências ${{ serviço.SAÍDA }} ou ${{ secret.NOME }}. Declarar o bloco faz o arquivo gerenciar todas as variáveis do serviço. Sem o bloco, as variáveis atuais ficam como estão.
connectsArestas de rede: um nome de serviço ou { to, ports }. Sem ports, vale a porta do destino.
mountsVolumes montados: { volume, path, readOnly }.
buildSó documentação: o build vem do repositório vinculado à aplicação.
configConfiguração de um kind que não é application (os campos do schema do kind também podem vir direto no serviço, como sizeGiB).
previewsAceito, mas ainda ignorado (ambientes de preview chegam numa fase futura).
environments.<slug>Overrides por ambiente: cada serviço é mesclado sobre o bloco base.

Serviços que existem no ambiente e não estão no arquivo são removidos, porque o arquivo descreve o ambiente inteiro.

Segredos​

Segredos nunca entram no arquivo. Uma variável com nome de credencial (*_PASSWORD, *_TOKEN, *_SECRET, *_API_KEY...) ou com valor de chave conhecido (ghp_, AKIA, sk_live_, chave privada PEM) é recusada com coda.secret_literal e a linha:

coda.yaml: linha 18: "DATABASE_PASSWORD" parece um segredo: guarde-o como segredo e escreva 'DATABASE_PASSWORD: ${{ secret.DATABASE_PASSWORD }}' (coda.secret_literal)

Crie o segredo pelo portal ou por coda secrets set e referencie com o mesmo nome: NOME: ${{ secret.NOME }}. Um segredo que o serviço não tem é apontado com coda.unknown_secret. Num serviço novo, isso é só um aviso, porque o segredo só pode ser criado depois da primeira aplicação.

Schema e editor​

O schema JSON fica em https://docs.<domínio>/schemas/coda.schema.json. No VS Code, com a extensão YAML, a primeira linha # yaml-language-server: $schema=... liga o autocomplete e a validação no editor.

CLI​

coda coda validate              # validação local (sem API): formato, segredos literais e arestas
coda coda diff                  # o que o arquivo mudaria no rascunho do ambiente (--org/--project/--env ou coda link)
coda coda export --file coda.yaml   # exporta o ambiente atual; aplicado de novo, não muda nada

API​

RotaDescrição
GET /api/v1/orgs/{org}/projects/{p}/environments/{e}/graph/export?format=codaExporta o ambiente como coda.yaml (application/yaml). Viewer ou acima.
POST /api/v1/orgs/{org}/projects/{p}/environments/{e}/graph/coda/diffCorpo { "content": "<yaml>" }. Devolve valid, errors e warnings (com code, line e path), changes (op, target, name) e managedByFile. Não grava nada.
GET .../graphO campo managedByFile traz o repositório que gerencia o ambiente.

Erros​

CódigoQuando
coda.invalidYAML inválido, chave desconhecida, campo fora do schema do kind ou referência a segredo mal escrita.
coda.secret_literalValor de segredo literal no arquivo.
coda.unknown_secret${{ secret.NOME }} que o serviço não tem.
coda.unknown_serviceconnects, mounts ou override que cita um serviço que não está no arquivo.
coda.unsupported_versionversion diferente de 1.