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:

Preparação

Crie e atualize contas de serviço.
Planeje grupos de ambientes.
Copie e atualize arquivos de modificações.

Atualize o Istio e o cert-manager.
Instale o ambiente de execução híbrido versão 1.3.
Fazer a limpeza.

Pré-requisito

Apigee híbrida versão 1.2. Se você estiver atualizando de uma versão anterior, consulte as instruções sobre Como fazer upgrade da Apigee híbrida para a versão 1.2.

Preparação

(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
```
(Recomendado) Faça o backup do banco de dados do Cassandra seguindo as instruções em Backup e recuperação do Cassandra.

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

Se você não estiver usando o Apigee Connect na instalação híbrida, ative o Apigee Connect.

Verifique se a API Apigee Connect está ativada:

gcloud services list | grep apigeeconnect

apigeeconnect.googleapis.com         Apigee Connect API

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

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.

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
```
Dica: caso você precise do endereço de e-mail da conta do serviço MART, execute o seguinte comando:
```
gcloud iam service-accounts list | grep mart
```

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"
      }

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
```
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.
Dica: se você precisar receber o endereço de e-mail da conta de serviço do inspetor, execute o comando a seguir:
```
gcloud iam service-accounts list | grep watcher
```
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
  ...
```
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.
Clique para ver um exemplo de uso de grupos de ambiente para substituir routingRules

Neste exemplo, o seguinte routingRules na rota de arquivo overrides.yaml direciona para os proxies de API foo e bar para o ambiente prod- env-1 e o proxy foo-test para o ambiente test-env:
```
virtualhosts:
  - name: default
    hostAliases:
      - "*.acme.com"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    routingRules:
      - paths:
        - /foo
        - /bar
      - env: prod-env-1
      - paths:
        - foo-test
      -env: test-env
```
Para duplicar isso na versão híbrida 1.3.6:
1. Implante os proxies foo e bar no ambiente prod-env-1.
2. Implante o proxy foo-test e bar no ambiente test-env.
3. Crie um grupo de ambiente com um alias de host para os proxies, como api.acme.com.
  Dica: crie um grupo de ambiente com o mesmo nome do virtualhosts usado na versão 1.2.
4. Revise a estrofe de virtualhosts em overrides.yaml para
  - Substitua virtualhosts:name pelo nome do grupo de ambientes.
  - Remova virtualhosts:routingRules.
  Exemplo:
```
virtualhosts:
  - name: default # environment group name
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
```
Atualize seu arquivo de modificação:

Faça uma cópia do seu arquivo de modificação.

Atualize as estrofes gcp e k8sCluster.

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

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

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"

Adicione a conta de serviço de métricas (apigee-metrics) ao arquivo de modificações:
```
metrics:
 serviceAccountPath: "service account file"
```
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
```
Atualize as estrofes mart e connectAgent:.
Observação:se você não planeja usar o Apigee Connect na instalação híbrida do 1.3, pule esta etapa e siga a dica na etapa 5 no Apigee Connect após o upgrade.
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)

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

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

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
```
Faça o download e instale o ASM seguindo as instruções de instalação em Fazer o download e instalar o ASM.

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

Exclua a implantação atual do cert-manager:

kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook

Verifique sua versão do Kubernetes:
```
kubectl version
```

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

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)

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

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

Renomeie o diretório apigeectl/ atual para um nome de diretório de backup. Exemplo:
```
mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
```
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
```
cd ao diretório base.
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
```

Exclua o job apigee-resources-install de apigee-system:

kubectl -n apigee-system delete job apigee-resources-install

Exclua o CRD antigo:

kubectl delete crd apigeetelemetries.apigee.cloud.google.com

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).
  
  Observação: você removerá a propriedade externalSeedHost em uma etapa posterior depois que o novo Cassandra estiver em execução e verificado.
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.
  Durante o processo de upgrade, cada componente realizará uma reinicialização gradual. Portanto, para ambientes de produção, é melhor aplicar o upgrade a um componente por vez.
  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
Observação: este procedimento requer o comando apigeectl da versão 1.2 no seu diretório de backup. Se você precisar fazer o download de outra cópia da versão apigeectl 1.2, use o seguinte comando:
```
curl -LO \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/1.2.0/apigeectl_your_system.tar.gz
```
em que your_system é linux_32, linux_64 mac_32 ou mac_64.
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

Observação: a exclusão dos recursos do Istio versão 1.4.6 também excluirá a entrada do MART. A entrada da MART é substituída pelo Apigee Connect na versão híbrida da Apigee 1.3.
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.

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

Como fazer upgrade para a versão 1.3.6.

Pré-requisito

Preparação

Clique para ver um exemplo de uso de grupos de ambiente para substituir routingRules

Fazer upgrade do Istio e do cert-manager

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

Fazer upgrade do cert-manager

Instalar o ambiente de execução híbrido

Produção

Demonstração/Experimental

Limpeza

Excluir recursos da versão híbrida 1.2.0

Desativar a instância antiga do Cassandra

Excluir recursos da versão 1.4.6 do Istio

Clique para ver um exemplo de uso de grupos de ambiente para substituir `routingRules`