Como gerenciar aplicativos com o Application Delivery


Neste 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, veja se você realizou as seguintes tarefas:

Defina as configurações padrão da gcloud usando um dos métodos a seguir:

  • Use gcloud init se quiser orientações para definir os padrões.
  • Use gcloud config para definir individualmente a região, a zona e o ID do projeto.

Como usar o gcloud init

Se você receber o erro One of [--zone, --region] must be supplied: Please specify location, conclua esta seção.

  1. Execute gcloud init e siga as instruções:

    gcloud init

    Se você estiver usando SSH em um servidor remoto, utilize a sinalização --console-only para impedir que o comando inicie um navegador:

    gcloud init --console-only
  2. Siga as instruções para autorizar a gcloud a usar sua conta do Google Cloud.
  3. Crie uma nova configuração ou selecione uma atual.
  4. Escolha um projeto do Google Cloud.
  5. Escolha uma zona padrão do Compute Engine para clusters zonais ou uma região para clusters regionais ou de Autopilot.

Como usar o gcloud config

  • Defina o ID do projeto padrão:
    gcloud config set project PROJECT_ID
  • Se você estiver trabalhando com clusters zonais, defina a zona do Compute padrão:
    gcloud config set compute/zone COMPUTE_ZONE
  • Se você estiver trabalhando com clusters de Autopilot ou regionais, defina a região do Compute padrão:
    gcloud config set compute/region COMPUTE_REGION
  • Atualize gcloud para a versão mais recente:
    gcloud components update
  • 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:

  1. 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.
  2. Instale a appctl, a ferramenta de linha de comando do Application Delivery.

Criar um novo cluster com o Application Delivery

É possível criar um novo cluster com o Application Delivery ativado usando a ferramenta gcloud ou o Console do 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

  1. Acesse a página do Google Kubernetes Engine no Console do Cloud:

    Acessar o Google Kubernetes Engine

  2. Clique em Criar.

  3. Na seção Padrão, clique em Configurar.

  4. Especifique o Nome do cluster.

  5. Escolha uma Versão do plano de controle de 1.15.x ou posterior.

  6. Configure o cluster como quiser.

  7. No painel de navegação, em Cluster, clique em Recursos.

  8. Marque a caixa de seleção Ativar o Gerenciador de aplicativos.

  9. Clique em Criar.

Como ativar o Application Delivery em um cluster vigente

Ative o Application Delivery em um cluster atual usando a ferramenta gcloud ou o Console do 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

  1. Acesse a página do Google Kubernetes Engine no Console do 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. Marque a caixa de seleção Ativar o Gerenciador de aplicativos.

  5. Clique em Salvar alterações.

Como confirmar a instalação

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

  1. 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.

  2. 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 Application Delivery, appctl, use a ferramenta gcloud para instalar o 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:

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

Como criar novos repositórios

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

  1. Altere para o diretório em que você gostaria de criar o diretório do seu aplicativo.
  2. 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
    
  3. appctl solicita que você confirme seus novos repositórios privados.

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.

  1. Altere para o diretório em que você quer criar o diretório do aplicativo.

  2. 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.

    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

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

  2. 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
    
  3. 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

  1. No diretório de repositório do seu aplicativo, teste a configuração com kustomize build:

    kustomize build config/base/
    

    Se sua configuração for válida, kustomize imprime o YAML que será implantado no cluster quando ele for aplicado.

  2. 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.

  1. Altere para o diretório raiz do repositório do seu aplicativo.

  2. 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
    
  3. Se quiser, veja as alterações que o Application Delivery fez no seu repositório do Git com git log:

    git log -p *
    
  4. 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:

  1. 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.

    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
    ```
    
  2. 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.

    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.

    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]"
    
  3. Use o GitHub ou o GitLab para analisar e aprovar a solicitação de envio.

  4. 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
    
  5. Confirme se o aplicativo está em execução com kubectl ou no Console do 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 "Aplicativos" do GKE no Console do Cloud.

Como promover uma versão

  1. 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
    
  2. Use o GitHub ou o GitLab para analisar e aprovar a solicitação de envio.

  3. 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
    

Como visualizar ambientes no Console do 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.

  1. 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
    
  2. 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
    
  3. Teste sua configuração com kustomize build:

    kustomize build config/envs/staging/
    
  4. 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.

  5. 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.

  6. Use appctl prepare para gerar uma solicitação de envio no repositório de implantação para análise:

    appctl prepare ENVIRONMENT_NAME
    
  7. Siga o link para criar uma solicitação de envio do GitHub ou do GitLab.

  8. 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.

  9. Aprove a solicitação de envio com GitHub ou GitLab.

  10. 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:

  1. 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.

  2. 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.

  3. No GitHub ou no GitLab, exclua os dois repositórios Git criados por appctl.

  4. Exclua o diretório do aplicativo local:

    rm -rf myapp/
    
  5. É possível desativar o Application Delivery no cluster a partir do gcloud ou do Console do Cloud:

    gcloud

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

    Console

    1. Acesse a página do Google Kubernetes Engine no Console do 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.

A seguir

Leia mais sobre o Kustomize.