Como gerenciar aplicativos com o Application Delivery

Padrão

Nesta página, você verá como configurar uma implantação de NGINX com o Application Delivery. A implantação é executada em dois ambientes: staging e prod. O ambiente prod usa a configuração regular, enquanto o staging usa uma ligeiramente modificada.

Requisitos

Para concluir este tutorial, você precisará do seguinte:

Git 2.19.2 ou superior instalado localmente.
Uma conta do GitHub ou do GitLab com permissões para criar um repositório privado. O Application Delivery só é compatível com os repositórios GitHub e GitLab.
Um cluster executando o GKE versão 1.15 ou posterior.
Um usuário com privilégios clusterAdmin.
Kustomize instalado localmente. Siga o guia de instalação.
Se você quiser validar seus arquivos de configuração do Kubernetes no repositório de implantação, instale o Docker.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

Ativar a API Google Kubernetes Engine.

Ativar a API Google Kubernetes Engine

Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud.
Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como: One of [--zone, --region] must be supplied: Please specify location.

Adicione chaves SSH às suas contas do GitHub ou do GitLab.
Teste suas chaves com ssh:

GitHub
sh ssh -T git@github.com

GitLab
sh ssh -T git@gitlab.com

É possível que você seja solicitado a confirmar os detalhes da conexão ou a senha longa de sua chave. Se a conexão for bem-sucedida, uma mensagem será impressa no terminal.

Como configurar o Application Delivery

Para usar o Application Delivery, faça o seguinte:

Crie um novo cluster com o Application Delivery ativado ou ative-o em um cluster do GKE com a versão 1.15 ou mais recente.
Instale a appctl, a ferramenta de linha de comando do Application Delivery.

Criar um novo cluster com o Application Delivery

É possível criar um cluster com o Application Delivery ativado usando a CLI gcloud ou o console do Google Cloud.

gcloud

Crie um cluster:

gcloud beta container clusters create CLUSTER_NAME \
      --cluster-version CLUSTER_VERSION\
      --addons ApplicationManager

Substitua:

CLUSTER_NAME: o nome do novo cluster;
CLUSTER_VERSION: a versão do novo cluster. Precisa ser o GKE 1.15 ou posterior.

Console

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Clique em Criar.
Na seção Padrão, clique em Configurar.
Especifique o Nome do cluster.
Escolha uma Versão do plano de controle de 1.15.x ou posterior.
Configure o cluster como quiser.
No painel de navegação, em Cluster, clique em Recursos.
Marque a caixa de seleção Ativar o Gerenciador de aplicativos.
Clique em Criar.

Como ativar o Application Delivery em um cluster vigente

Ative o Application Delivery em um cluster atual usando a CLI gcloud ou o console do Google Cloud.

gcloud

Para ativar o Application Delivery em um cluster atual, execute o seguinte comando:

gcloud beta container clusters update CLUSTER_NAME \
      --update-addons ApplicationManager=ENABLED

Substitua CLUSTER_NAME pelo nome do cluster.

Console

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster que você quer modificar.
Em Recursos, ao lado do campo Gerenciador de aplicativos, clique em Editar gerenciador de aplicativos.
Marque a caixa de seleção Ativar o Gerenciador de aplicativos.
Clique em Salvar alterações.

Como confirmar a instalação

Para verificar o status da instalação do Application Delivery, faça o seguinte:

Verifique o status da implantação:

kubectl get deployment application-controller-manager -n application-system

A resposta será semelhante a:

NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
application-controller-manager   2/2     2            2           1h

É preciso haver dois pods disponíveis nessa implantação do application-controller-manager.

Verifique o status do StatefulSet:

kubectl get statefulset kalm-controller-manager -n kalm-system

A resposta será semelhante a:

NAME                      READY   AGE
kalm-controller-manager   1/1     1h

É necessário haver um pod pronto neste StatefulSet kalm-controller-manager.

Instalar appctl

Para instalar a ferramenta de linha de comando do Application Delivery, appctl, use a CLI gcloud para instalar pkg.

gcloud components install pkg

Depois de ativar o Application Delivery em um cluster e instalar o pkg, você está pronto para implantar seu primeiro aplicativo.

Como implantar um aplicativo

Para implantar um aplicativo, faça o seguinte:

Crie novos repositórios Git ou inicialize repositórios existentes.
Crie uma configuração base.
Crie um ou mais ambientes para sua implantação.
Opcionalmente, aplique sobreposições de configuração aos seus ambientes no repositório do seu aplicativo.
Crie um candidato de versão no formato de uma solicitação de envio ou mesclagem.
Implante sua versão.

Como criar novos repositórios

Crie repositórios para o Application Delivery no GitHub ou no GitLab com appctl.

Altere para o diretório em que você gostaria de criar o diretório do seu aplicativo.
Crie seus repositórios do Application Delivery com appctl.
GitHub
Execute este comando:
```
appctl init APP_NAME \
    --app-config-repo=github.com/USERNAME/APP_NAME
```
Substitua:
- APP_NAME: o nome do seu aplicativo.
- USERNAME: seu nome de usuário do GitHub.
Por exemplo, se seu nome de usuário do GitHub for octocat e você quiser criar um aplicativo chamado myapp, execute o comando a seguir:
```
appctl init myapp \
    --app-config-repo=github.com/octocat/myapp
```
GitLab
Execute este comando:
```
appctl init APP_NAME \
    --app-config-repo=gitlab.com/USERNAME/APP_NAME
```
Substitua:
- APP_NAME: o nome do seu aplicativo.
- USERNAME: seu nome de usuário do GitLab.
Por exemplo, se seu nome de usuário do GitLab for alice e você quiser criar um aplicativo chamado myapp, execute o comando a seguir:
```
appctl init myapp \
    --app-config-repo=gitlab.com/alice/myapp
```
appctl solicita que você confirme seus novos repositórios privados.

Observação: o Git solicita outras informações de login.

appctl cria dois repositórios Git particulares e remotos:

O repositório do aplicativo github.com/USERNAME/APP_NAME. Esse repositório é clonado no diretório atual.
O repositório de implantação github.com/USERNAME/APP_NAME-deployment. O repositório de implantação local é armazenado em ./APP_NAME/.deployment.

Para mais informações sobre o conteúdo e a estrutura desses repositórios, consulte o guia do Application Delivery.

Inicializar repositórios existentes

Se você tiver repositórios, será possível inicializá-los para o Application Delivery no GitHub ou no GitLab com appctl.

Altere para o diretório em que você quer criar o diretório do aplicativo.
Execute o comando appctl init, que criará um diretório chamado APP_NAME e clonará seu repositório nele.

O comando appctl init inicializa uma camada base do Kustomize nos arquivos de configuração armazenados no diretório ./config do repositório. Especifique um caminho de configuração diferente com a sinalização --config-path.

Por padrão, appctl init usa github.com/USERNAME/APP_NAME-deployment como o URL do repositório de implantação. Use a sinalização --deployment-repo para especificar um URL diferente. Se o repositório de implantação não existir, o comando appctl criará um.

Observação: se já houver um diretório APP_NAME no caminho local, appctl exigirá que o diretório APP_NAME seja inicializado pelo git e ter uma referência remota correspondente ao app-config-repo. Além disso, se o diretório APP_NAME tiver um subdiretório .deployment, o diretório .deployment será inicializado pelo git e terá uma referência remota correspondente ao deployment-repo. Use a sinalização --deployment-repo para modificar o padrão.
GitHub
```
appctl init APP_NAME \
      --app-config-repo=github.com/USERNAME/APP_NAME \
      [--config-path=CONFIG_PATH]
```
Substitua:
- APP_NAME: o nome do seu aplicativo.
- USERNAME: seu nome de usuário do GitHub.
- CONFIG_PATH: o caminho opcional para o diretório de configuração do seu repositório. Se omitido, o padrão é ./config.
Por exemplo, se o repositório de configuração do aplicativo for https://github.com/octocat/myapp e você espera que o repositório de implantação seja https://github.com/octocat/myapp-deploy, execute o seguinte:
```
appctl init myapp \
    --app-config-repo=github.com/octocat/myapp
```
GitLab
```
appctl init APP_NAME \
    --app-config-repo=gitlab.com/USERNAME/APP_NAME \
    [--config-path=CONFIG_PATH]
```
Substitua:
- APP_NAME: o nome do seu aplicativo.
- USERNAME: seu nome de usuário do GitLab.
- CONFIG_PATH: o caminho opcional para o diretório de configuração do seu repositório. Se omitido, o padrão é ./config.
Por exemplo, se o repositório de configuração do aplicativo for gitlab.com/alice/myapp, execute o seguinte:
```
appctl init myapp --app-config-repo=gitlab.com/alice/myapp
```

Como criar uma configuração base

Altere seu diretório de trabalho para o repositório do seu aplicativo.

Crie a configuração da sua carga de trabalho do Kubernetes. Ela pode ser qualquer implantação válida do Kubernetes.

A configuração a seguir define um aplicativo chamado nginx, que implanta três réplicas do contêiner nginx. Copie a configuração no arquivo config/base/myapp.yaml. Se você quiser ativar um LoadBalancer, remova a marca de comentário da linha type: LoadBalancer.

#myapp/config/base/myapp.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  # if your cluster supports it, uncomment the following to automatically create
  # an external load-balanced IP for the frontend service.
  # type: LoadBalancer
  ports:
    - port: 80
  selector:
    app: nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

Configure o Application Delivery para aplicar essa configuração à base. Cole a configuração a seguir em config/base/kustomization.yaml.
```
#config/base/kustomization.yaml

resources:
  - myapp.yaml
```

Como testar e enviar sua configuração

No diretório de repositório do seu aplicativo, teste a configuração com kustomize build:
```
kustomize build config/base/
```
Observação: o appctl usa um Kustomize integrado para evitar conflitos de versão. Pode ser diferente da sua versão Kustomize local ou do Kustomize instalado por meio do gcloud components install pkg. Execute appctl version para ver a versão integrada do Kustomize e execute kustomize version para ver sua versão local do Kustomize.

Se sua configuração for válida, kustomize imprime o YAML que será implantado no cluster quando ele for aplicado.
Depois de validar seu YAML, crie e envie uma confirmação no repositório do seu aplicativo:
```
git add .
git commit -m "Creating APP_NAME"
git push origin master
```

Como adicionar um ambiente de versão

O Application Delivery implanta seu aplicativo em ambientes. Você adiciona ambientes para suas versões com appctl.

Altere para o diretório raiz do repositório do seu aplicativo.
Crie seu ambiente com appctl:
```
appctl env add ENVIRONMENT_NAME \
    --cluster=CLUSTER_NAME
```
Substitua:
- ENVIRONMENT_NAME: o nome do novo ambiente.
- CLUSTER_NAME: o nome do cluster.
appctl cria uma confirmação git contendo uma configuração Kustomize de scaffold.

É possível especificar o nome do namespace para um ambiente de lançamento do aplicativo usando --namespace. Caso contrário, o nome do namespace padrão é APP_NAME-ENVIRONMENT_NAME.

Por exemplo, para adicionar os ambientes staging e prod ao cluster application-cluster usando o nome de namespace padrão, execute este comando:
```
appctl env add staging --cluster=application-cluster
appctl env add prod --cluster=application-cluster
```
Para adicionar o ambiente test no namespace test ao cluster application-cluster, execute o seguinte comando:
```
appctl env add test --cluster=application-cluster --namespace=test
```
Ao adicionar um ambiente, você precisa considerar se as solicitações de envio e as revisões de código são necessárias no repositório de implantação desse ambiente. Por padrão, as solicitações de envio são criadas. Se o ambiente não for essencial de produção e a revisão de código não for necessária, pule a criação de solicitações de envio com --review-required=false.

Por exemplo, para adicionar o ambiente test, que não requer solicitações de envio, execute o seguinte comando:
```
appctl env add test \
    --cluster=application-cluster \
    --review-required=false
```
Observação: appctl solicita um token de acesso para seu repositório do Git.
Se quiser, veja as alterações que o Application Delivery fez no seu repositório do Git com git log:
```
git log -p *
```
Envie a configuração para o repositório do seu aplicativo:
```
git push origin master
```

Opcional: como verificar o repositório de implantação

Abra a página do GitHub ou do GitLab para o repositório de implantação. Por exemplo, se seu nome de usuário do GitHub for octocat e você criar um aplicativo chamado myapp, o URL será https://github.com/octocat/myapp-deployment. Nessa página, você verá as ramificações que foram criadas para cada ambiente.

Como implantar um ambiente

Para implantar um ambiente com o Application Delivery, faça o seguinte:

Crie uma versão com git tag e insira essa tag:
```
git tag VERSION
git push origin VERSION
```
Substitua VERSION pelo número da versão do aplicativo.

Observação: recomendamos que você use o controle de versões semântico para os números de versão. Esse sistema permite que você classifique as versões facilmente nas páginas do GitHub ou do GitLab.

Por exemplo, para enviar a versão v0.1.0, execute os comandos a seguir:
```
git tag v0.1.0
git push origin v0.1.0
```
```
Use appctl prepare para nomear a versão marcada por tag atualmente e gerar uma solicitação de envio no repositório de implantação para análise.

Observação: appctl prepare redefine seu kubeconfig, incluindo o contexto e o namespace padrão. Se você tiver alterado seu contexto padrão, será necessário aplicar novamente essa alteração depois de usar appctl.
```
appctl prepare ENVIRONMENT_NAME
```
Por exemplo, para usar o ambiente staging, execute o comando a seguir:
```
appctl prepare staging \
    --validate=true
```
Esse comando aciona a função de validação kpt gcr.io/kustomize-functions/example-validator para validar a alteração enviada ao repositório de implantação.

O kpt é instalado por gcloud components install pkg. Essa função de validação executa o kubeval em segundo plano, que valida arquivos de configuração do Kubernetes usando esquemas da especificação OpenAPI do Kubernetes.

Para executar kpt prepare staging --validate, é preciso instalar o Docker na máquina.

Por padrão, a sinalização --validate está desativada.

Observação: se o kpt for desinstalado, a ativação da sinalização --validate resultará em um erro.

Se appctl tiver concluído a confirmação no repositório de implantação, ele imprimirá um URL para uma solicitação de envio, desta forma:
```
Created a "Pull Request": "https://github.com/octocat/myapp-deployment/pull/[Pull_Request_ID]"
```
Observação: se o ambiente for criado com --review-required=false, appctl prepare pulará a criação de uma solicitação de envio e enviará a alteração para o repositório de implantação. Você não verá o link de solicitação de envio.
Use o GitHub ou o GitLab para analisar e aprovar a solicitação de envio.

Atenção: ao mesclar solicitações de envio no GitHub ou no GitLab, use uma confirmação de mesclagem. O Application Delivery não identifica as confirmações "Squash e mesclagem" ou "Troca de base e mesclagem".
Depois que a solicitação de envio for aprovada, use appctl apply para concluir a implantação:
```
appctl apply ENVIRONMENT_NAME
```
Substitua ENVIRONMENT_NAME pelo nome do seu ambiente.

Por exemplo, para implantar alterações no ambiente staging, execute o seguinte comando:
```
appctl apply staging
```
Confirme se o seu aplicativo está sendo executado com kubectl ou no console do Google Cloud.
kubectl
Use kubectl describe para visualizar o status do seu aplicativo:
```
kubectl get releasetracks.app.gke.io APP_NAME \
    --n NAMESPACE \
    -w
```
Substitua:
- APP_NAME: o nome do repositório do aplicativo;
- NAMESPACE: o nome do namespace especificado ao criar o ambiente. Se você não tiver especificado um nome de namespace, o padrão é APP_NAME-ENVIRONMENT_NAME.
Por exemplo, para verificar o status do ambiente staging do aplicativo chamado myapp, execute o comando a seguir:
```
kubectl get releasetracks.app.gke.io myapp -n myapp-staging
```
Para verificar o status do ambiente test adicionado anteriormente por env add --namespace test, execute este comando:
```
kubectl get releasetracks.app.gke.io myapp -n test
```
Console
Para informações de status e versão de seus aplicativos implantados com o Application Delivery, consulte a página de aplicativos do GKE no console do Google Cloud.

Como promover uma versão

Para promover um candidato de versão de um ambiente para outro, execute o comando a seguir:
```
appctl prepare TARGET_ENVIRONMENT \
    --from-env=SOURCE_ENVIRONMENT
```
Substitua:
- TARGET_ENVIRONMENT: o nome do ambiente em que você quer implantar o candidato de versão.
- SOURCE_ENVIRONMENT: o nome do ambiente atual.
Por exemplo, para promover staging a prod, execute:
```
appctl prepare prod --from-env=staging
```
Use o GitHub ou o GitLab para analisar e aprovar a solicitação de envio.
Para implantar o candidato de versão no ambiente de destino, execute o comando a seguir:
```
appctl apply TARGET_ENVIRONMENT
```
Por exemplo, para implantar no ambiente prod, execute o seguinte comando:
```
appctl apply prod
```

Visualizar ambientes no console do Google Cloud

Depois que o aplicativo de um ambiente for implantado, será possível vê-lo na página de aplicativos do GKE. Essa página contém uma lista de aplicativos com os respectivos ambientes marcados entre parênteses. Veja uma captura de tela de um aplicativo myapp com dois ambientes staging e prod. O namespace, o cluster e a versão de cada ambiente também são exibidos na página.

Uma captura de tela da página do aplicativo.

Para ver detalhes do aplicativo, como a tag do git, os componentes e a lista de ambientes, clique no nome do aplicativo. A captura de tela a seguir mostra os detalhes de myapp.

Uma captura de tela da página de detalhes do aplicativo.

Como alterar a configuração de um ambiente

Nesta seção, é necessário que você tenha um ambiente staging configurado de acordo com as etapas anteriores. Talvez você precise adaptar essas instruções para seu uso.

Nesta seção, você verá como alterar os parâmetros do ambiente staging usando uma sobreposição kustomize. Depois de fazer a alteração, você as envia e marca com uma tag no git. O Application Delivery atualizará seu cluster.

Crie um arquivo chamado config/envs/staging/patch-replicas.yaml e copie o seguinte texto nele. Isso atualiza a configuração no ambiente staging para executar uma réplica em vez de três.
```
#config/envs/staging/patch-replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
```
Observação: os valores apiVersion, kind e metadata.name são obrigatórios.
Edite o arquivo config/envs/staging/kustomization.yaml e adicione patch-replicas.yaml a uma nova coleção chamada patchesStrategicMerge.
```
#config/envs/staging/kustomization.yaml
namespace: myapp-staging
bases:
   - ../../base
patchesStrategicMerge:
   - patch-replicas.yaml
```
Também é possível adicionar anotações específicas do ambiente nessa sobreposição. O exemplo a seguir inclui uma anotação chamada oncall-team para adicionar todos os recursos nesse ambiente. Para mais informações, consulte campos de arquivos do Kustomize.
```
#config/envs/staging/kustomization.yaml

#Don't change the namespace field
namespace: myapp-staging
bases:
   - ../../base
patchesStrategicMerge:
   - patch-replicas.yaml
commonAnnotations:
  oncall-team: staging-oncall@foo.bar
```
Teste sua configuração com kustomize build:
```
kustomize build config/envs/staging/
```
Adicione e confirme suas alterações.
```
git add .
git commit -m "<var>COMMIT_MESSAGE</var>"
git push origin master
```
Substitua COMMIT_MESSAGE por uma mensagem que descreva as alterações.
Crie uma versão com git tag e envie-a.
```
git tag VERSION
git push origin VERSION
```
Substitua VERSION pelo número da versão desejada.
Use appctl prepare para gerar uma solicitação de envio no repositório de implantação para análise:
```
appctl prepare ENVIRONMENT_NAME
```
Siga o link para criar uma solicitação de envio do GitHub ou do GitLab.
Verifique o conteúdo da sua solicitação de envio. O Application Delivery faz uma alteração de uma linha que define o valor de replicas como 1.
Aprove a solicitação de envio com GitHub ou GitLab.
Use appctl apply para aplicar as alterações:
```
appctl apply staging
```

Como reverter as alterações na configuração

Para reverter para uma versão anterior, execute o seguinte comando:

appctl apply TARGET_ENVIRONMENT \
    --from-tag GIT_TAG

Substitua:

TARGET_ENVIRONMENT: o nome do ambiente em que você quer implantar a versão.
GIT_TAG: o nome da tag da versão.

Como usar `appctl` em scripts

A ferramenta appctl é interativa e espera entradas do usuário por padrão. Se você quiser executar appctl em um script, contêiner ou pipelines, defina a variável de ambiente APPCTL_INTERACTIVE como false.

Por exemplo, no shell bash, execute o comando a seguir:

export APPCTL_INTERACTIVE=false

Informações sobre comandos appctl específicos estão disponíveis com appctl help command. Por exemplo, para receber ajuda com appctl prepare, execute appctl help prepare.

Como desinstalar o gerenciador de aplicativos

Para remover o aplicativo em execução no cluster, exclua todos os namespaces criados com novos ambientes.

Para todos os ambientes e clusters, repita os comandos a seguir:

Mude para o cluster de um determinado ambiente.
```
kubectl config use-context ENVIRONMENT_CLUSTER_NAME
```
Substitua ENVIRONMENT_CLUSTER_NAME pelo nome do cluster no ambiente selecionado.
Exclua o namespace em que o aplicativo para este ambiente está em execução
```
kubectl delete ns NAMESPACE
```
Substitua NAMESPACE pelo nome do namespace que você quer excluir. O padrão é APP_NAME-ENVIRONMENT_NAME.
No GitHub ou no GitLab, exclua os dois repositórios Git criados por appctl.
Exclua o diretório do aplicativo local:
```
rm -rf myapp/
```
É possível desativar o Application Delivery no cluster a partir da gcloud ou do Console do Google Cloud:
gcloud
```
gcloud beta container clusters update CLUSTER_NAME \
    --update-addons ApplicationManager=DISABLED
```
Console
1. Acesse a página Google Kubernetes Engine no console do Google Cloud.
  
  Acessar o Google Kubernetes Engine
2. Na lista de clusters, clique no nome do cluster que você quer modificar.
3. Em Recursos, ao lado do campo Gerenciador de aplicativos, clique em Editar gerenciador de aplicativos.
4. Desmarque a caixa de seleção Ativar o Gerenciador de aplicativos.
5. Clique em Salvar alterações.

Como gerenciar aplicativos com o Application Delivery

Requisitos

Antes de começar

GitHub

GitLab

Como configurar o Application Delivery

Criar um novo cluster com o Application Delivery

gcloud

Console

Como ativar o Application Delivery em um cluster vigente

gcloud

Console

Como confirmar a instalação

Instalar appctl

Como implantar um aplicativo

Como criar novos repositórios

GitHub

GitLab

Inicializar repositórios existentes

GitHub

GitLab

Como criar uma configuração base

Como testar e enviar sua configuração

Como adicionar um ambiente de versão

Opcional: como verificar o repositório de implantação

Como implantar um ambiente

kubectl

Console

Como promover uma versão

Visualizar ambientes no console do Google Cloud

Como alterar a configuração de um ambiente

Como reverter as alterações na configuração

Como usar appctl em scripts

Como desinstalar o gerenciador de aplicativos

gcloud

Console

A seguir

Como usar `appctl` em scripts