Como gerenciar aplicativos com o Application Delivery

beta

Neste tutorial, 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.

Para mais informações sobre o Application Delivery, consulte o documento sobre ele.

Requisitos

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

  • Git 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 1.15 ou superior.
  • Um usuário com privilégios clusterAdmin.

Antes de começar

Antes de começar, veja se você realizou as seguintes tarefas:

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

  • Use gcloud init se você quiser ser orientado sobre como definir padrões.
  • Use gcloud config para definir individualmente a região, a zona e o ID do projeto.

Como usar o gcloud init

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

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 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 (em inglês).
  • Teste suas chaves com ssh:

    GitHub

    ssh -T git@github.com

    GitLab

    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, crie um novo cluster com ele ativado ou ative-o em um cluster do GKE atual com a versão 1.15 e superior. Em seguida, instale appctl, a ferramenta de linha de comando do Application Delivery.

Criar um novo cluster com o Application Delivery

Crie um novo cluster com o Application Delivery ativado usando gcloud ou o Console do Google Cloud.

gcloud

Escolha uma versão de cluster 1.15.x ou superior.

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

Console

  1. Acesse Criar um cluster do Kubernetes no Console do Google Cloud.
  2. Nomeie o cluster.
  3. Escolha uma Versão mestre de 1.15.x ou superior.
  4. Selecione outras opções que você quiser ativar.
  5. Role até a parte inferior e clique em Disponibilidade, rede, segurança e outros recursos.
  6. Em Outros recursos, marque a caixa Ativar gerenciador de aplicativos.
  7. Clique em Criar.

Como ativar o Application Delivery em um cluster vigente

Ative o Application Delivery em um vigente usando a gcloud ou o Console do Google Cloud.

gcloud

gcloud beta container clusters update [CLUSTER_NAME] --update-addons ApplicationManager=ENABLED

Console

  1. Acesse a página de clusters no Console do Google Cloud.
  2. Selecione o cluster no qual você quer instalar o Application Delivery. A tela "Detalhes do cluster" será exibida.
  3. Clique em Editar.
  4. Clique em Complementos. O menu será expandido.
  5. Em Gerenciador de aplicativos, escolha Ativado.
  6. Clique em Salvar para atualizar seu cluster.

Como confirmar a instalação

Para verificar o status da instalação do Application Delivery, execute comandos kubectl a seguir.

kubectl get pods kalm-controller-manager-0 -n kalm-system
kubectl get pods application-controller-manager-0 -n application-system

Quando o Application Delivery está em execução, os dois comandos retornam que há exatamente um pod com STATUS de Running.

NAME                        READY   STATUS    RESTARTS   AGE
    kalm-controller-manager-0   2/2     Running   0          1h
    
NAME                               READY   STATUS    RESTARTS   AGE
    application-controller-manager-0   1/1     Running   0          1h
    

Instalar appctl

Instale appctl, a ferramenta de linha de comando Application Delivery, com gcloud.

gcloud components install appctl

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

Como implantar um aplicativo

As seções a seguir descrevem como:

  1. criar repositórios git com appctl;
  2. criar uma configuração base;
  3. criar um ou mais ambientes para sua implantação;
  4. opcionalmente, aplicar sobreposições de configuração aos seus ambientes no repositório do seu aplicativo;
  5. criar um candidato de versão no formato de uma solicitação de envio ou mesclagem;
  6. implantar sua versão.

Como criar repositórios

Crie repositórios para o Application Delivery no GitHub ou GitLab ou 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

appctl init [APPLICATION_NAME] \
    --app-config-repo=github.com/[USER_NAME]/[APPLICATION_NAME]

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

appctl init [APPLICATION_NAME] \
    --app-config-repo=gitlab.com/[USER_NAME]/[APPLICATION_NAME]

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.

appctl cria dois repositórios Git particulares e remotos:

  • O repositório do aplicativo github.com/[USER_NAME]/[APPLICATION_NAME]. Esse repositório é clonado no diretório atual.
  • O repositório de implantação github.com/[USER_NAME]/[APPLICATION_NAME]-deployment.

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

Como criar uma configuração base

  1. Altere seu diretório de trabalho para o repositório do seu aplicativo. Por exemplo, se você usou o nome do aplicativo myapp, execute:

    cd myapp
  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 kubectl apply -k:

    kubectl apply -k config/base/ --dry-run -o yaml

    Se sua configuração for válida, kubectl 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 [APPLICATION_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, por exemplo, cd myapp.
  2. Crie seu ambiente com appctl.

    appctl env add [ENVIRONMENT_NAME] --cluster=[CLUSTER_NAME]

    appctl cria uma confirmação git contendo uma configuração Kustomize de scaffold.

    Por exemplo, para adicionar os ambientes staging e prod ao cluster application-cluster, execute o comando a seguir:

    appctl env add staging --cluster=application-cluster
        appctl env add prod --cluster=application-cluster
  3. Opcionalmente, 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

  1. 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, você precisa fazer o seguinte:

  1. Criar uma versão com git tag e inserir essa tag.

    git tag [VERSION]
        git push origin [VERSION]

    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

    Se appctl tiver concluído a confirmação no repositório de implantação, ele imprimirá um URL para criar uma solicitação de envio.

    Click to create a "Pull Request":
        "https://github.com/octocat/myapp-deployment/compare/[VERSION_BRANCH]"
        

    Abra o URL no seu navegador. A tela Como comparar alterações, no GitHub, ou a tela Nova solicitação de mesclagem, no GitLab, é exibida.

  3. Use o GitHub ou o GitLab (em inglês) 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]

    Por exemplo, para implantar alterações no ambiente staging, execute o seguinte:

    appctl apply staging
  5. Confirme se 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 [APPLICATION_NAME] -n 
    [APPLICATION_NAME]-[ENVIRONMENT_NAME] -w

    Em que [APPLICATION_NAME] é o nome do repositório do seu aplicativo e [ENVIRONMENT_NAME] é o nome do seu ambiente.

    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

    Console do Google Cloud

    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

  1. Para promover um candidato de versão de um ambiente para outro, execute o comando a seguir:

    appctl prepare [TARGET_ENVIRONMENT_NAME] \
        --from-env [SOURCE_ENVIRONMENT_NAME]

    Em que [TARGET_ENVIRONMENT_NAME] é o nome do ambiente em que você quer implantar o candidato de versão em execução atualmente em [SOURCE_ENVIRONMENT_NAME].

    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_NAME]

    Por exemplo, para implantar no ambiente prod, execute:

    appctl apply prod

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 (em inglês). Depois de fazer a alteração, você as envia e marca com uma tag no git. O Application Delivery atualizará seu cluster.

  1. Crie o arquivo config/envs/staging/patch-replicas.yaml e copie o texto a seguir 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 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 (páginas em inglês).

    #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 kubectl apply -k:

    kubectl apply -k config/envs/staging/ --dry-run -o yaml

  4. Adicione e confirme suas alterações.

    git add .
        git commit -m "[COMMIT_MESSAGE]"
        git push origin master

    Em que [COMMIT_MESSAGE] é uma mensagem que descreve suas alterações.

  5. Crie uma versão com git tag e envie-a.

    git tag [VERSION]
        git push origin  [VERSION]
  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

Use appctl apply para reverter para uma versão anterior.

appctl apply
    [TARGET_ENVIRONMENT_NAME] --from-tag [GIT_TAG]

Em que [TARGET_ENVIRONMENT_NAME] é o nome do ambiente em que você quer implantar a versão marcada com [GIT_TAG].

Como usar o appctl em scripts

A ferramenta appctl é interativa e espera por entrada 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 ${CONTEXT_OF_ENV_CLUSTER}
  2. Exclua o namespace no qual seu aplicativo para este ambiente está em execução

     kubectl delete ns [APPLICATION_NAME]-[ENVIRONMENT_NAME]

    Em que [APPLICATION_NAME] é o nome do repositório do seu aplicativo, e [ENVIRONMENT_NAME] é o nome do seu ambiente.

  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 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 de clusters no Console do Google Cloud e selecione qual você quer atualizar.
    2. Clique em Editar. A tela Editar clusters é exibida.
    3. Clique em Complementos.
    4. Em Gerenciador de aplicativos, escolha Desativado.
    5. Clique em Salvar para atualizar seu cluster.

A seguir

Leia mais sobre o Kustomize (em inglês).