Ambientes

Um ambiente diz onde as coisas rodam: desenvolvimento, homologação, produção. Cada ambiente aponta pra um cluster, o cluster GoShip ou um seu, e todo projeto existe em todos os ambientes. Você não escolhe onde rodar a cada app: o ambiente em que você está já responde.

Ambientes são da organização, como as pessoas e a cobrança. Quem cria e muda ambientes é o dono ou um administrador (Organizações e projetos).

Os três ambientes de partida

Toda organização nasce com três ambientes, todos no cluster GoShip, nesta ordem:

O painel mostra esses nomes em inglês (Development, Staging, Production); os slugs são os mesmos.

Desenvolvimento é o ambiente padrão: vale quando nada escolhe outro (veja Na CLI). Isso vale também pras organizações que já existiam: os apps e bancos delas foram para o ambiente de desenvolvimento, e os nomes na plataforma e as URLs não mudaram. Dá pra tornar outro ambiente o padrão, mas o padrão em si não pode ser apagado.

O nome de exibição dos três pode ser trocado. O slug não: o nome dos apps na plataforma deriva dele (Nomes na plataforma). Pelo mesmo motivo, production, staging e development não podem ser o slug de um projeto.

Você pode criar outros ambientes, como qa ou demo. O slug de um ambiente:

• começa com letra minúscula e tem até 16 caracteres, só com letras minúsculas, números e hífens, sem terminar em hífen (^[a-z]([a-z0-9-]{0,14}[a-z0-9])?$);
• não pode ser new, settings nem all.

Ativar a homologação

A homologação aparece na lista, mas fica desativada até um administrador da organização ativá-la. Enquanto estiver desativada, não dá pra criar nada nela (apps, bancos, volumes), e o GoShip responde:

staging is disabled; an organization admin enables it in Infrastructure → Environments

Pra ativar, abra Environments (grupo Infrastructure da barra lateral) e clique em Enable, ou use a CLI:

goship environment enable staging

Pra desativar de novo, goship environment disable staging. O GoShip só desativa um ambiente que está vazio e que não é o padrão.

Qual cluster, qual banco

Cada ambiente tem duas escolhas, e as duas são da organização:

• Cluster: onde os apps, bancos e volumes do ambiente rodam. É o cluster GoShip, a infraestrutura compartilhada, ou um cluster seu: uma máquina que o GoShip instala na sua conta de nuvem ou por SSH, ou um Kubernetes que você já tem e conecta. Veja Clusters.
• Servidor de banco padrão (opcional): o servidor onde ficam os bancos novos do ambiente, um Cloud SQL no seu Google Cloud (Banco no seu Google Cloud). Um servidor é criado para um ambiente, na página Database servers, e vira o padrão dele quando fica pronto; o de produção é protegido contra exclusão. Sem um, os bancos novos vão pro PostgreSQL do GoShip. Com goship db create --server você escolhe outro servidor pra um banco só.

Um cluster pode servir vários ambientes e vários projetos. Desenvolvimento e homologação podem dividir uma máquina barata; ou os três ambientes podem ficar no cluster GoShip, sem cluster nenhum seu.

O ambiente também decide a cobrança. App no cluster GoShip paga o plano dele; app num cluster seu não paga plano por recurso, e quem é cobrado é o cluster, pela capacidade, exceto um Kubernetes conectado, que está em beta e não é cobrado (Clusters → Cobrança, Planos e cobrança).

Todo projeto existe em todo ambiente

Um projeto novo já existe em todos os ambientes da organização. Mas ele só usa um ambiente quando tem algo lá: o primeiro app, banco ou volume que você cria no ambiente prepara o espaço do projeto no cluster dele. Antes disso nada foi criado nem é cobrado.

No painel, Apps, Databases e Volumes mostram um ambiente de cada vez (No painel), e Environments, no grupo Infrastructure da barra lateral, lista os ambientes com o cluster de cada um e é onde você os cria, renomeia, ativa e desativa, aponta pra outro cluster, torna padrão e apaga.

Cada app, banco ou volume pertence a um ambiente do projeto. O app api em homologação e o app api em produção são dois apps que têm o mesmo nome, não um app com duas versões: cada um tem as suas variáveis, domínios, plano e ligações, e publicar em um não toca no outro.

As ligações ficam dentro do ambiente: um banco só se liga a apps do mesmo ambiente, e o mesmo vale pra volumes e pras ligações entre apps.

Nomes na plataforma

O nome completo de um app é <org>-<projeto>-<app> em produção e <org>-<projeto>-<ambiente>-<app> nos outros ambientes. O projeto default perde o <projeto>:

• Produção não leva o ambiente no nome. Os apps que já existiam mantêm o nome que tinham na plataforma, mesmo tendo passado para o ambiente de desenvolvimento. Por isso, criar em produção um app com o mesmo nome de um app do projeto que passou para desenvolvimento é recusado: a recusa diz em que ambiente ele está e pede --environment development.
• O nome do app precisa ser único dentro do projeto e do ambiente. O mesmo api pode existir em homologação e em produção.
• O nome completo tem no máximo 40 caracteres. Fora de produção o slug do ambiente entra na conta, então slugs curtos deixam mais espaço pro app.
• Bancos e volumes seguem o mesmo esquema, e o nome de cada um também é único dentro do projeto e do ambiente.

Criar, renomear, trocar de cluster e apagar

Criar. Um ambiente novo aponta pro cluster GoShip e pro PostgreSQL do GoShip, a menos que você diga outro:

goship environment create qa
goship environment create qa --name "QA" --cluster acme-sp --db-server pg-prod

--cluster e --db-server aceitam nome ou id (goship clusters e goship db server list mostram os seus). O ambiente passa a existir em todos os projetos, vazio.

Renomear. O nome de exibição muda quando você quiser, na página Environments ou pela API. O slug muda só nos ambientes que você criou; os apps que já existem mantêm o nome que têm na plataforma.

Trocar o cluster. Na página Environments ou pela API, o ambiente passa a apontar pra outro cluster. O cluster novo vale pros projetos que passarem a usar o ambiente depois. Os projetos que ainda não têm nada no ambiente passam pra ele. Os que já têm app, banco ou volume lá ficam onde estão, porque a plataforma não move recursos entre clusters. Esses são os mantidos: a resposta da mudança lista cada um, com o projeto e o cluster em que ficou, e eles seguem fixados até os recursos serem recriados no destino.

Isso vale pra qualquer app, banco ou volume: não existe mover um recurso entre ambientes nem entre clusters. Pra mudar, crie de novo onde quer.

O servidor de banco padrão muda a qualquer hora e vale só pros bancos criados depois.

Apagar. O GoShip recusa apagar um ambiente enquanto algum projeto tiver app, banco ou volume nele, e diz quais projetos ainda seguram algo. Os projetos que só têm o ambiente vazio não impedem. O ambiente padrão não se apaga: escolha outro padrão antes.

goship environment rm qa

Fixar um projeto em outro cluster

O cluster que vale pra um projeto num ambiente é o do próprio projeto naquele ambiente. O cluster do ambiente é só o padrão de quando o projeto começa a usá-lo.

Um administrador da organização pode fixar (pin) um projeto, num ambiente, a outro cluster da organização, enquanto o projeto não tem nada ali. Serve pra uma organização com dois produtos manter a produção de um numa máquina própria e a do outro no cluster GoShip, sem mudar o ambiente inteiro. A lista de ambientes do projeto mostra, em cada um, o cluster que ele usa e se está fixado. Com recursos no ambiente, o GoShip recusa e diz quantos há. Fixa-se nas configurações do projeto (Project settings) ou pela API.

Como fazer cada coisa

Renomear, trocar o cluster, mudar o padrão e fixar não têm comando na CLI: use o painel ou a API. Os detalhes das rotas estão na Referência da API.

No painel

A barra lateral tem um seletor de ambiente, que mostra o ambiente atual. As páginas Apps, Databases e Volumes listam os recursos desse ambiente, e o endereço delas leva /envs/<ambiente>/.

Na CLI

goship environments                         # os ambientes, o cluster de cada um e se estão ativados
goship environment use production           # os próximos comandos deste projeto usam produção
goship deploy --environment staging         # só neste comando

O ambiente vale pro comando inteiro: goship apps, goship db create, goship logs e os demais agem dentro dele. O CLI decide o ambiente nesta ordem, parando no primeiro que encontrar:

1. a flag --environment;
2. a chave environment: do goship.yaml;
3. a variável de ambiente GOSHIP_ENVIRONMENT;
4. o ambiente guardado por goship environment use, uma escolha por organização e projeto;
5. o ambiente padrão da organização, que é desenvolvimento até você trocar.

Diferente de organização e projeto, não escolher nenhum não é erro: o padrão vale. A exceção é quando o CLI não consegue ler o padrão da organização (a API fora do ar, por exemplo) e nada escolheu um ambiente: os comandos que mudam algo recusam e pedem --environment, e os de listagem usam development, com uma nota.

# goship.yaml
app: api
org: acme
project: loja
environment: staging

O environment: do goship.yaml só vale quando o org: e o project: do mesmo arquivo estão vazios ou são a organização e o projeto em uso.

goship env continua sendo as variáveis de ambiente de um app (goship env set). Os ambientes de que esta página fala são goship environment e goship environments.

Os comandos de ambiente e de cluster estão disponíveis a partir da versão 0.14.0 da CLI; goship environment enable e disable e a coluna ENABLED de goship environments, a partir da 0.16.0.