Como fazer upgrade da Apigee híbrida para a versão 1.3.6

Como fazer upgrade para a versão 1.3.6.

Os procedimentos para fazer upgrade da Apigee híbrida são organizados nas seguintes seções:

  1. Preparação
    1. Crie e atualize contas de serviço.
    2. Planeje grupos de ambientes.
    3. Copie e atualize arquivos de modificações.
  2. Atualize o Istio e o cert-manager.
  3. Instale o ambiente de execução híbrido versão 1.3.
  4. Fazer a limpeza.

Pré-requisito

Preparação

  1. (Recomendado) Faça uma cópia de backup do seu diretório $APIGEECTL_HOME/ da versão 1.2. Exemplo:
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
  2. (Recomendado) Faça o backup do banco de dados do Cassandra seguindo as instruções em Backup e recuperação do Cassandra.
  3. Faça o upgrade da plataforma do Kubernetes da seguinte maneira. Siga a documentação da plataforma se precisar de ajuda:
    Plataforma Fazer upgrade para a versão
    GKE 1.15.x
    Anthos 1.5
    AKS 1.16.x usando clusters anexados ao Anthos
  4. Se você não estiver usando o Apigee Connect na instalação híbrida, ative o Apigee Connect.
    1. Verifique se a API Apigee Connect está ativada:
      gcloud services list | grep apigeeconnect
      
      apigeeconnect.googleapis.com         Apigee Connect API
    2. Se não estiver, ative a API:
      gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID

      Em que $PROJECT_ID é o ID do projeto no Google Cloud.

    3. Na linha de comando, receba as credenciais de autenticação de gcloud. Veja o exemplo a seguir:

      TOKEN=$(gcloud auth print-access-token)

      Para verificar se o token foi preenchido, use echo, como mostra o exemplo a seguir:

      echo $TOKEN

      Isso exibirá seu token como uma string codificada.

      Para mais informações, consulte a visão geral da ferramenta de linha de comando gcloud.

    4. Verifique se o Apigee Connect está ativado para sua organização:
      curl -H "Authorization: Bearer $TOKEN" \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      Em que $ORG_NAME é o ID da organização.

      Se a saída contiver:

            "name" : "features.mart.connect.enabled",
            "value" : "true"

      O Apigee Connect está ativado.

    5. Se o Apigee Connect não estiver ativado, atribua o papel de agente do Apigee Connect à conta de serviço MART:
      gcloud projects add-iam-policy-binding $PROJECT_ID \
        --member serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com \
        --role roles/apigeeconnect.Agent
    6. Ative o Apigee Connect com o seguinte comando:
      curl -H "Authorization: Bearer $TOKEN" -X PUT \
        -H "Content-Type: application/json" \
        -d '{
          "name" : "'"$ORG_NAME"'",
          "properties" : {
            "property" : [ {
              "name" : "features.hybrid.enabled",
              "value" : "true"
            }, {
              "name" : "features.mart.connect.enabled",
              "value" : "true"
            } ]
          }
        }' \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"
      

      Se o resultado contiver as duas propriedades a seguir, o Apigee Connect foi ativado com sucesso:

            {
              "name": "features.mart.connect.enabled",
              "value": "true"
            },
            {
              "name": "features.hybrid.enabled",
              "value": "true"
            }
      
  5. Crie a conta de serviço apigee-watcher. O inspetor da Apigee é uma nova conta de serviço introduzida na versão 1.3. Ele estabelece uma sincronização de alterações no nível da organização e as aplica para configurar a entrada do Istio.

    No diretório híbrido principal:

    ./tools/create-service-account apigee-watcher ./service-accounts
  6. Atribua o papel de Agente de ambiente de execução da Apigee à conta de serviço do inspetor:
    gcloud projects add-iam-policy-binding $PROJECT_ID \
      --member serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com \
      --role roles/apigee.runtimeAgent

    em que PROJECT_ID é o ID do projeto no Google Cloud. Se os endereços de e-mail da sua conta de serviço forem diferentes desse padrão, substitua-os.

    A saída precisa incluir uma lista de todas as contas de serviço e os respectivos papéis, incluindo:

      ...
    - members:
      - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
      role: roles/apigee.runtimeAgent
      ...
  7. Planeje seus grupos de ambiente para o roteamento. A Apigee híbrida 1.3 gerencia o roteamento de caminho base com grupos de ambiente em vez de routingRules. Se estiver usando routingRules na configuração híbrida, crie grupos de ambiente para replicar o roteamento.

    É preciso criar pelo menos um grupo de ambiente.

    Consulte Sobre grupos de ambientes.

  8. Atualize seu arquivo de modificação:
    1. Faça uma cópia do seu arquivo de modificação.
    2. Atualize as estrofes gcp e gcp.

      As seguintes propriedades de configuração foram substituídas na versão híbrida 1.3:

      • "gcpRegion" substituído por "gcp:region"
      • "gcpProjectID" substituído por "gcp:projectID"
      • "gcpProjectIDRuntime" substituído por "gcp:gcpProjectIDRuntime"
      • "k8sClusterName" substituído por "k8s:clusterName"
      • "k8sClusterRegion" substituído por "k8s:clusterRegion"

      Por exemplo, substitua a seguinte estrutura:

      gcpRegion: gcp region
      gcpProjectID: gcp project ID
      gcpProjectIDRuntime: gcp project ID
      
      k8sClusterName: name
      k8sClusterRegion: region

      por:

      gcp:
       projectID: gcp project ID
       region: gcp region
       gcpProjectIDRuntime: gcp project ID # optional. This is only required if you
                                             # want logger/metrics data to be sent in
                                             # different gcp project.
      
      k8sCluster:
       name: gcp project ID
       region: gcp region
      
    3. Se você ainda não tiver um identificador exclusivo de instância no seu arquivo de modificação, adicione um:
      # unique identifier for this installation. 63 chars length limit
      instanceID: ID

      Em que ID é um identificador exclusivo para esta instalação híbrida, como "my-hybrid-131-installation" ou "acmecorp-hybrid-131".

    4. Adicione a conta de serviço do inspetor (apigee-watcher) ao arquivo de modificações:
      # Note: the SA should have the "Apigee Runtime Agent" role
      watcher:
       serviceAccountPath: "service account file"
    5. Adicione a conta de serviço de métricas (apigee-metrics) ao arquivo de modificações:
      metrics:
       serviceAccountPath: "service account file"
    6. Atualize a estrofe virtualhosts: para substituir routingRules pelo seu grupo de ambientes.
      1. -name: Substitua o nome pelo grupo de ambientes. É possível ter várias entradas de nomes, uma para cada grupo de ambiente.
      2. hostAliases:[] Exclua esta linha.
      3. Mantenha (ou adicione) as entradas sslCertPath: e sslKeyPath:.
      4. Excluir todas as routingRules entradas.

      Exemplo:

      virtualhosts:
        - name: default
          hostAliases:
            - "*.acme.com"
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
          routingRules:
            - paths:
              - /foo
              - /bar
            - env: my-environment

      torna-se:

      virtualhosts:
        - name: example-env-group
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
    7. Atualize as estrofes mart e connectAgent:.
      1. Em mart:, remova as entradas hostAlias:, sslCertPath: e sslKeyPath:.
      2. Adicione uma estrofe de connectAgent:.
      3. Em connectAgent:, adicione uma entrada serviceAccountPath: e forneça o caminho para o arquivo de contagem de serviço que tem o papel de agente da Apigee Connect atribuído a ele (geralmente a conta de serviço de MART).

      Exemplo:

      mart:
        hostAlias: "mart.apigee-hybrid-docs.net"
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
        sslCertPath: ./certs/fullchain.pem
        sslKeyPath: ./certs/privkey.key

      torna-se:

      mart:
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
      
      connectAgent:
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json

Fazer upgrade do Istio e do cert-manager

A versão da Apigee híbrida versão 1.3 requer o cert-manager v0.14.2 para gerenciar e verificar certificados e a distribuição do Istio disponibilizada pelo Anthos Service Mesh (ASM) versão 1.5.7 (ou mais recente) para criar e gerenciar o gateway de entrada do ambiente de execução.

Fazer upgrade do Istio 1.4.6 para o ASM 1.5.7 (ou mais recente)

  1. Para minimizar o tempo de inatividade, as implantações do Istio e os HPAs precisam ter pelo menos duas réplicas cada. Execute os seguintes comandos para determinar o número de réplicas:
    kubectl -n istio-system get deployments # list of deployments
    kubectl -n istio-system get hpa # list of hpa
  2. Edite cada implantação que tem apenas uma réplica e aumente o replicas: para 2 ou mais:
    kubectl -n istio-system edit deployment name

    Exemplo:

    spec:
      progressDeadlineSeconds: 600
      replicas: 2
  3. Edite cada HPA que tem apenas uma réplica e aumente o minReplicas: para 2 ou mais:
    kubectl -n istio-system edit hpa name

    Exemplo:

    spec:
      maxReplicas: 5
      minReplicas: 2
    
  4. Faça o download e instale o ASM seguindo as instruções de instalação em Fazer o download e instalar o ASM.
  5. Após a instalação, execute o comando "version" para confirmar que você tem a versão 1.5.x instalada corretamente:
    ./bin/istioctl version
    
    client version: 1.5.8-asm.0
    apigee-mart-ingressgateway version:
    citadel version: 1.4.6
    galley version: 1.4.6
    ingressgateway version: 1.5.8-asm.0
    pilot version: 1.4.6
    policy version: 1.4.6
    sidecar-injector version: 1.4.6
    telemetry version: 1.4.6
    pilot version: 1.5.8-asm.0
    data plane version: 1.4.6 (1 proxies), 1.5.8-asm.0 (2 proxies)

Fazer upgrade do cert-manager

  1. Exclua a implantação atual do cert-manager:
    kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
  2. Verifique sua versão do Kubernetes:
    kubectl version
  3. Execute o seguinte comando para instalar o cert-manager do Jetstack:
    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml 

Instalar o ambiente de execução híbrido

  1. Armazene o número da versão mais recente em uma variável:
    export VERSION=$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
  2. Verifique se a variável foi preenchida com um número de versão. Se você quiser usar uma versão diferente, salve-a na variável de ambiente. Exemplo:
    echo $VERSION
      1.3.6
  3. Faça o download do pacote de lançamento para seu sistema operacional:

    Mac 64 bits:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_64.tar.gz

    Linux de 64 bits:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_64.tar.gz

    Mac 32 bits:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_32.tar.gz

    Linux de 32 bits:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
  4. Renomeie o diretório apigeectl/ atual para um nome de diretório de backup. Exemplo:
    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
  5. Extraia o conteúdo do arquivo gzip baixado para seu diretório base híbrido. Exemplo:

    tar xvzf filename.tar.gz -C hybrid-base-directory
  6. cd ao diretório base.
  7. O conteúdo de tar é, por padrão, expandido em um diretório com a versão e a plataforma no nome. Por exemplo, ./apigeectl_1.0.0-f7b96a8_linux_64. Renomeie esse diretório para apigeectl:

    mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
  8. Exclua o job apigee-resources-install de apigee-system:
    kubectl -n apigee-system delete job apigee-resources-install
  9. Exclua o CRD antigo:
    kubectl delete crd apigeetelemetries.apigee.cloud.google.com
  10. Atualize a estrofe cassandra: no arquivo de modificações com uma propriedade externalSeedHost. Essa propriedade ajudará a garantir que a nova instalação híbrida da versão 1.3.6 usará o mesmo cluster do Kubernetes que a instalação da versão 1.2. Esta é uma etapa única necessária apenas para fazer o upgrade da versão híbrida 1.2 para a versão 1.3.6 (ou mais recente).
    1. Encontre um dos endereços IP do Cassandra atual no mesmo cluster do Kubernetes em que você está atualizando a instalação 1.2.0.
      kubectl -n namespace get pods -o wide

      Em que namespace é seu namespace da Apigee híbrida.

      Anote o endereço IP de um nó do Cassandra. Exemplo:

      kubectl -n apigee get pods -o wide
      NAME                  READY   STATUS    RESTARTS   AGE   IP          NODE
      apigee-cassandra-0    1/1     Running   0          33d   10.68.8.24   gke-example-cluster-rc5-apigee-data-c8bf1234-09kc
      apigee-cassandra-1    1/1     Running   0          16d   10.68.8.33   gke-example-cluster-rc5-apigee-data-c9221ee7-10kc
      apigee-cassandra-2    1/1     Running   0          23h   10.68.9.11   gke-example-cluster-rc5-apigee-data-d123e456-11kc
    2. Adicione o valor da propriedade externalSeedHost:
      cassandra:
       externalSeedHost: Cassandra_node_IP

      Em que Cassandra_node_IP é o IP do nó do cassandra (10.68.8.24 no exemplo anterior).

  11. No novo diretório apigeectl/, execute apigeectl init, apigeectl apply e apigeectl check-ready:
    1. Inicialize a Apigee híbrida 1.3.6:
      apigeectl init -f overrides_1.3.yaml

      Em que overrides_1.3.yaml é o arquivo editado overrides.yaml editado.

    2. Na versão 1.3 da versão híbrida, a sintaxe da sinalização --dry-run depende da versão de kubectl que você está executando. Verifique a versão de kubectl:
      gcloud version
    3. Verifique se há erros com uma simulação:

      kubectl versão 1.17 e anteriores:

      apigeectl apply -f overrides_1.3.yaml --dry-run=true

      kubectl versão 1.18 e mais recentes:

      apigeectl apply -f overrides_1.3.yaml --dry-run=client
    4. Aplique as substituições. Selecione e siga as instruções para ambientes de produção ou ambientes de demonstração/experimental, dependendo da sua instalação.

      Produção

      Para ambientes de produção, você precisa fazer upgrade de cada componente híbrido individualmente e verificar o status do componente atualizado para o processo de confirmação do próximo componente.

      1. Aplique as modificações para fazer upgrade do Cassandra:
        apigeectl apply -f overrides_1.3.yaml --datastore
      2. Verifique a conclusão:
        kubectl -n namespace get pods

        Em que namespace é seu namespace da Apigee híbrida.

        Passe para a próxima etapa somente quando os pods estiverem prontos.

      3. Aplique as modificações para fazer upgrade dos componentes de telemetria e verificar a conclusão:
        apigeectl apply -f overrides_1.3.yaml --telemetry
        kubectl -n namespace get pods
      4. Aplique as modificações para fazer upgrade dos componentes no nível da organização (MART, Watcher e Apigee Connect) e verifique a conclusão:
        apigeectl apply -f overrides_1.3.yaml --org
        kubectl -n namespace get pods
      5. Aplique as modificações para fazer upgrade dos seus ambientes. Você tem duas opções:
        • Aplique as modificações a um ambiente de cada vez e verifique a conclusão. Repita esta etapa para cada ambiente:
          apigeectl apply -f overrides_1.3.yaml --env env_name
          kubectl -n namespace get pods

          Em que env_name é o nome do ambiente que você está atualizando.

        • Aplique as modificações a todos os ambientes de uma vez e verifique a conclusão:
          apigeectl apply -f overrides_1.3.yaml --all-envs
          kubectl -n namespace get pods

      Demonstração/Experimental

      Na maioria dos ambientes experimentais ou de demonstração, é possível aplicar as modificações a todos os componentes de uma só vez. Se o ambiente de demonstração/experimental for grande e complexo ou for muito semelhante a um ambiente de produção, use as instruções para fazer upgrade de ambientes de produção.

      1. apigeectl apply -f overrides_1.3.yaml
      2. Verifique o status:
        apigeectl check-ready -f overrides_1.3.yaml

      Para mais instruções, consulte Configuração híbrida do GKE - Etapa 5: instalar a Apigee híbrida no GKE.

    5. Depois de configurar e executar as configurações híbridas 1.3, verifique se todos os nós do Cassandra (antigos e novos) fazem parte do mesmo cluster do Cassandra. Execute o comando a seguir em um dos nós do Cassandra:
      kubectl -n namespace get pods
      kubectl -n namespace exec old Cassandra pod -- nodetool status

      Na saída de exemplo a seguir, 10.68.8.24 é da versão 1.2.0 e é o IP de nó que você usou como externalSeedHost. 10.68.7.11 é da versão 1.3.6:

      Datacenter: dc-1
      ================
      Status=Up/Down
      |/ State=Normal/Leaving/Joining/Moving
      --  Address     Load        Tokens       Owns (effective)  Host ID                               Rack
      UN  10.68.8.24  379.41 KiB  256          50.8%             11bbd43b-af64-464b-a96d-0d6dd0521de1  ra-1
      UN  10.68.7.11  1.35 MiB    256          49.2%             0b4d9e08-f353-413a-b4a9-7d18a8d07e58  ra-1

      Se não estiverem no mesmo cluster, verifique o valor externalSeedHost.

    6. Quando todos os pods estiverem em execução, remova externalSeedHost do arquivo de modificações e execute apigeectl apply novamente com a opção --datastore:
      apigeectl apply --datastore -f overrides_1.3.6.yaml

    Limpeza

    Depois de verificar se todos os pods estão ativos e íntegros e os endpoints do ASM são válidos para a nova instalação, limpe:

    • Recursos da versão híbrida 1.2
    • A instância antiga do Cassandra
    • Recursos do Istio 1.4.6.

    Excluir recursos da versão híbrida 1.2.0

    1. Remova os detalhes do roteamento virtual do host 1.2.0:
      $APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml

      Em que $APIGEECTL_HOME-v1.2 é o diretório em que você fez backup do diretório apigeectl da versão 1.2.

    2. Se o endpoint ainda estiver funcionando como esperado e você verificar que todos os componentes 1.3.0 estão funcionando, execute o seguinte comando para excluir os recursos da Apigee híbrida 1.2.0:
      $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
        -f 1.2.0_overrides.yaml

    Desativar a instância antiga do Cassandra

    1. cd para o diretório apigeectl recém-instalado.
    2. Execute o script tools/cas_cleanup.sh:

      Esse script desativa o pod antigo do Cassandra do anel Cassandra, exclui o STS antigo e exclui os PVCs.

      bash cas_cleanup.sh Apigee namespace

    Excluir recursos da versão 1.4.6 do Istio

    1. Execute o seguinte comando para excluir os recursos mais recentes do Istio v.1.4.6:
      kubectl delete all -n istio-system --selector \
        'app in (apigee-mart-istio-ingressgateway, galley, security, istio-nodeagent, istio-mixer, sidecarInjectorWebhook, istio-mixer)'
    2. Execute os seguintes comandos para excluir jobs mais antigos da instalação do Istio 1.4.6:
      kubectl -n istio-system delete job istio-init-crd-10-1.4.6
      kubectl -n istio-system delete job istio-init-crd-11-1.4.6
      kubectl -n istio-system delete job istio-init-crd-14-1.4.6

    Parabéns! Você fez upgrade para a versão 1.3.6 da Apigee híbrida.