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

Este procedimento abrange o upgrade da Apigee híbrida versão 1.16.x para a Apigee híbrida versão 1.17.3 e de versões anteriores da Apigee híbrida 1.17.x para a versão 1.17.3.

Use os mesmos procedimentos para upgrades de versão secundária (por exemplo, 1.16 para 1.17) e para upgrades de versão de patch (por exemplo, 1.17.0 para 1.17.3).

Se estiver fazendo upgrade da Apigee híbrida versão 1.15 ou anterior, primeiro você precisará fazer upgrade para a versão híbrida 1.16 antes de fazer upgrade para a versão 1.17.3. Consulte as instruções sobre Como fazer upgrade da Apigee híbrida para a versão 1.16.

Mudanças em relação à Apigee híbrida v1.16

Observe as seguintes mudanças:

  • Suporte ao Protocolo de Contexto de Modelo (MCP): a Apigee híbrida versão 1.17 adiciona suporte ao Protocolo de Contexto de Modelo (MCP), um protocolo aberto que permite que aplicativos de IA agêntica usem suas APIs como ferramentas por meio de endpoints gerenciados do MCP. A Apigee híbrida roteia, autoriza e protege essas chamadas de ferramenta do MCP da mesma forma que gerencia suas outras APIs. Assim, você não precisa executar nem manter seus próprios servidores MCP. Para mais informações, consulte Visão geral do Protocolo de Contexto de Modelo (MCP) na Apigee e o Guia de início rápido do MCP.
  • Rotação de certificado de CA raiz: a versão 1.17 da Apigee híbrida adiciona suporte para alternar o certificado de autoridade certificadora (CA) raiz que ancora a confiança para a comunicação TLS entre os componentes do ambiente de execução. Agora é possível substituir a CA raiz antes que ela expire, sem inatividade, seguindo um procedimento de rotação em fases. Para mais informações, consulte Alternar o certificado de CA raiz.
  • Suporte ao TLS 1.3: a Apigee híbrida versão 1.17 adiciona suporte ao TLS 1.3, a versão mais recente do protocolo Transport Layer Security. O TLS 1.3 oferece handshakes de conexão mais rápidos e segurança mais forte do que as versões anteriores do TLS. Para informações sobre como configurar o TLS no gateway de entrada, consulte Como configurar o TLS e o mTLS no gateway de entrada.
  • Suporte a proxy de encaminhamento para políticas de IA: a Apigee híbrida versão 1.17 adiciona suporte a proxy de encaminhamento para as políticas de IA, como as políticas de Model Armor e de armazenamento em cache semântico. As chamadas de saída que essas políticas fazem agora podem ser roteadas por um proxy de encaminhamento HTTP, que não era compatível com versões anteriores da Apigee híbrida. Para mais informações, consulte Configurar o encaminhamento de proxy para proxies de API.
  • Suporte ao endpoint do Private Service Connect (PSC) do cache semântico: a Apigee híbrida versão 1.17 adiciona suporte ao endpoint do Private Service Connect (PSC) para armazenamento em cache semântico. As políticas de armazenamento em cache semântico agora podem alcançar os serviços de apoio por um endpoint do Private Service Connect, que mantém esse tráfego na sua rede privada. Para mais informações, consulte Começar a usar as políticas de armazenamento em cache semântico.

Para mais informações sobre os recursos da versão 1.17 da Apigee híbrida, consulte as notas da versão v1.17.3 da Apigee híbrida.

Pré-requisitos

Antes de fazer upgrade para a versão híbrida 1.17, verifique se a instalação atende aos seguintes requisitos:

Antes de fazer upgrade para a versão 1.17.3: limitações e observações importantes

  • O upgrade para a Apigee híbrida versão 1.17 pode exigir inatividade.

    Ao fazer upgrade do controlador da Apigee para a versão 1.17.3, todas as implantações da Apigee passam por uma reinicialização gradual. Para minimizar a inatividade em ambientes híbridos de produção durante uma reinicialização gradual, verifique se você está executando pelo menos dois clusters (na mesma ou diferente região/data center). Divida todo o tráfego de produção para um único cluster. Pegue o cluster que você está prestes a fazer upgrade off-line e continue o processo de upgrade. Repita o processo para cada cluster.

    A Apigee recomenda que, depois de iniciar o upgrade, você faça upgrade de todos os clusters o mais rápido possível para reduzir as chances de impacto na produção. Não há limite de tempo para o upgrade de todos os clusters restantes depois do upgrade do primeiro. No entanto, até que todos os clusters restantes sejam atualizados, o backup e a restauração do Cassandra não funcionam com versões mistas. Por exemplo, um backup da versão híbrida 1.16 não pode ser usado para restaurar uma instância da versão híbrida 1.17.

  • As alterações do plano de gerenciamento não precisam ser totalmente suspensas durante um upgrade. Todas as suspensões temporárias necessárias às alterações do plano de gerenciamento estão indicadas nas instruções de upgrade abaixo.

Como fazer upgrade para a versão 1.17.3

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

  1. Prepare-se para o upgrade.
  2. Instale o ambiente de execução híbrido versão 1.17.3.

Preparar para fazer upgrade para a versão 1.17

Faça o backup da instalação híbrida

  1. Estas instruções usam a variável de ambiente APIGEE_HELM_CHARTS_HOME para o diretório no seu sistema de arquivos em que você instalou os gráficos do Helm. Se necessário, mude o diretório para seu diretório e defina a variável com o seguinte comando:

    Linux 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Mac OS 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Windows 

    set APIGEE_HELM_CHARTS_HOME=%CD%
echo %APIGEE_HELM_CHARTS_HOME%
  2. Faça uma cópia de backup do diretório $APIGEE_HELM_CHARTS_HOME/ da versão 1.16. É possível usar qualquer processo de backup. Por exemplo, você pode criar um arquivo tar de todo o diretório com: 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Faça o backup do banco de dados Cassandra seguindo as instruções em Backup e recuperação do Cassandra.
  4. Verifique se o certificado TLS e os arquivos de chave (.crt, .key e/ou .pem) estão no diretório $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/.

Fazer upgrade da versão do Kubernetes

Verifique a versão da plataforma do Kubernetes e, se necessário, faça upgrade para uma versão compatível com as versões híbridas 1.16 e 1.17. Siga a documentação da plataforma se precisar de ajuda.

Extraia os gráficos do Apigee Helm.

Os gráficos da Apigee híbrida são hospedados no Google Artifact Registry:

oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts

Usando o comando pull, copie todos os gráficos da Apigee híbrida do Helm para o armazenamento local com o seguinte comando: 

export CHART_REPO=oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts
export CHART_VERSION=1.17.3
helm pull $CHART_REPO/apigee-operator --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-datastore --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-env --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-ingress-manager --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-org --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-redis --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-telemetry --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-virtualhost --version $CHART_VERSION --untar

Editar kustomization.yaml para um namespace personalizado da Apigee

Se o namespace da Apigee não for apigee, edite o arquivo apigee-operator/etc/crds/default/kustomization.yaml e substitua o valor namespace pelo namespace da Apigee.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE

Se você estiver usando apigee como namespace, não será necessário editar o arquivo.

  • Instale os CRDs atualizados da Apigee:

    1. Use o recurso de simulação kubectl executando o seguinte comando:

      kubectl apply -k  apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false --dry-run=server

    2. Depois de validar com o comando de simulação, execute o seguinte:

      kubectl apply -k  apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
    3. Valide a instalação com o comando kubectl get crds: 
      kubectl get crds | grep apigee

      A resposta será semelhante a esta:

      apigeedatastores.apigee.cloud.google.com                    2024-08-21T14:48:30Z
apigeedeployments.apigee.cloud.google.com                   2024-08-21T14:48:30Z
apigeeenvironments.apigee.cloud.google.com                  2024-08-21T14:48:31Z
apigeeissues.apigee.cloud.google.com                        2024-08-21T14:48:31Z
apigeeorganizations.apigee.cloud.google.com                 2024-08-21T14:48:32Z
apigeeredis.apigee.cloud.google.com                         2024-08-21T14:48:33Z
apigeerouteconfigs.apigee.cloud.google.com                  2024-08-21T14:48:33Z
apigeeroutes.apigee.cloud.google.com                        2024-08-21T14:48:33Z
apigeetelemetries.apigee.cloud.google.com                   2024-08-21T14:48:34Z
cassandradatareplications.apigee.cloud.google.com           2024-08-21T14:48:35Z

  • Verifique os identificadores nos nós do cluster. Por padrão, a Apigee programa pods de dados em nós com o rótulo cloud.google.com/gke-nodepool=apigee-data e os pods de ambiente de execução são programados em nós com o rótulo cloud.google.com/gke-nodepool=apigee-runtime. É possível personalizar os rótulos do pool de nós no arquivo overrides.yaml.

    Para mais informações, consulte Como configurar pools de nós dedicados.

    • Fazer upgrade do cert-manager

    A Apigee híbrida v1.17 é compatível com as versões 1.16 a 1.19 do cert-manager. Há uma mudança no cert-manager 1.18 que pode causar um problema com seu tráfego. Na versão 1.18 do cert-manager, o valor padrão de Certificate.Spec.PrivateKey.rotationPolicy foi alterado de Never para Always. Para instalações híbridas da Apigee que foram atualizadas, isso pode causar um problema com o tráfego. Ao fazer upgrade para a versão híbrida 1.17 de uma versão anterior, é necessário editar o certificado apigee-ca para compensar essa mudança ou manter a versão do cert-manager na versão 1.17.x ou anterior.

    Antes de fazer upgrade do cert-manager para a versão 1.18 ou 1.19, siga as etapas abaixo para editar o certificado apigee-ca e definir o valor de Certificate.Spec.PrivateKey.rotationPolicy como Never.

    1. Verifique o conteúdo do certificado apigee-ca para ver se rotationPolicy está definido: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      Procure os valores em spec.privateKey na saída:

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    # Note: rotationPolicy would appear here if it is set.
    size: 256
  secretName: apigee-ca
...
    2. Se rotationPolicy não estiver definido ou se estiver definido como Always, edite o certificado apigee-ca para definir o valor de rotationPolicy como Never:
      1. Faça primeiro uma simulação: 
        kubectl patch Certificate \
  --dry-run=server \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
      2. Aplique um patch no certificado: 
        kubectl patch Certificate \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
    3. Verifique se o valor de rotationPolicy agora está definido como Never: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      A saída será parecida com esta:

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    rotationPolicy: Never
    size: 256
  secretName: apigee-ca
...
    4. Faça upgrade do cert-manager. O comando a seguir vai baixar e instalar o cert-manager v1.19.2: 
      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

      Consulte Plataformas e versões compatíveis: cert-manager para conferir uma lista de versões compatíveis.

    Veja estes tópicos:

    Instalar o ambiente de execução híbrido 1.17.3

    1. Caso contrário, acesse o diretório APIGEE_HELM_CHARTS_HOME. Execute os comandos a seguir nesse diretório.
    2. Faça upgrade do operador/controlador da Apigee:

      Simulação:

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Faça upgrade do gráfico:

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Verifique a instalação do operador da Apigee:

      helm ls -n APIGEE_NAMESPACE

      NAME       NAMESPACE       REVISION   UPDATED                                STATUS     CHART                   APP VERSION
operator   apigee   3          2024-08-21 00:42:44.492009 -0800 PST   deployed   apigee-operator-1.17.3   1.17.3

      Para saber se ele está funcionando, confira a disponibilidade:

      kubectl -n APIGEE_NAMESPACE get deploy apigee-controller-manager

      NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
apigee-controller-manager   1/1     1            1           7d20h
    3. Faça upgrade do repositório de dados da Apigee:

      Simulação:

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Faça upgrade do gráfico:

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Para saber se o apigeedatastore está em execução, confira o estado dele:

      kubectl -n APIGEE_NAMESPACE get apigeedatastore default

      NAME      STATE       AGE
default   running    2d
    4. Faça upgrade da telemetria da Apigee:

      Simulação:

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Faça upgrade do gráfico:

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Para saber se ele está funcionando, confira o estado dele:

      kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry

      NAME               STATE     AGE
apigee-telemetry   running   2d
    5. Faça o upgrade do Apigee Redis:

      Simulação:

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Faça upgrade do gráfico:

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Para saber se ele está funcionando, confira o estado dele:

      kubectl -n APIGEE_NAMESPACE get apigeeredis default

      NAME      STATE     AGE
default   running   2d
    6. Faça upgrade do gerenciador de entrada da Apigee:

      Simulação:

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Faça upgrade do gráfico:

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Para saber se ele está funcionando, confira a disponibilidade:

      kubectl -n APIGEE_NAMESPACE get deployment apigee-ingressgateway-manager

      NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
apigee-ingressgateway-manager   2/2     2            2           2d
    7. Faça upgrade da organização da Apigee:

      Simulação:

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Faça upgrade do gráfico:

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Para saber se ele está funcionando, confira o estado da respectiva organização:

      kubectl -n APIGEE_NAMESPACE get apigeeorg

      NAME                      STATE     AGE
apigee-my-org-my-env      running   2d
    8. Faça upgrade do ambiente.

      É preciso instalar um ambiente de cada vez. Especifique o ambiente com --set env=ENV_NAME.

      Simulação:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server
      • ENV_RELEASE_NAME é um nome usado para rastrear a instalação e os upgrades do gráfico apigee-env. Esse nome precisa ser diferente dos outros nomes de versões do Helm na instalação. Geralmente, é o mesmo que ENV_NAME. No entanto, se o ambiente tiver o mesmo nome do grupo de ambientes, use nomes de versão diferentes para o ambiente e o grupo de ambientes, por exemplo, dev-env-release e dev-envgroup-release. Para mais informações sobre versões no Helm, consulte Três grandes conceitos na documentação do Helm.
      • ENV_NAME é o nome do ambiente que você está fazendo upgrade.
      • OVERRIDES_FILE é o novo arquivo de substituição para a v.1.17.3

      Faça upgrade do gráfico:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE

      Para saber se ele está funcionando, confira o estado do respectivo ambiente:

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      NAME                          STATE       AGE   GATEWAYTYPE
apigee-my-org-my-env          running     2d
    9. Faça upgrade dos grupos de ambiente (virtualhosts).
      1. É necessário fazer upgrade de um grupo de ambiente (virtualhost) por vez. Especifique o grupo de ambientes com --set envgroup=ENV_GROUP_NAME: Repita os seguintes comandos para cada grupo de ambientes mencionado no arquivo overrides.yaml:

        Simulação:

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server

        ENV_GROUP_RELEASE_NAME é o nome com que você instalou anteriormente o gráfico apigee-virtualhost. Normalmente, é ENV_GROUP_NAME.

        Faça upgrade do gráfico:

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE
      2. Verifique o estado da ApigeeRoute (AR).

        A instalação de virtualhosts cria a ApigeeRouteConfig (ARC), que gera internamente a ApigeeRoute (AR) depois que o inspetor da Apigee extrai detalhes relacionados ao grupo de ambientes do plano de controle. Portanto, verifique se o estado de RA correspondente está em execução: 

        kubectl -n APIGEE_NAMESPACE get arc

        NAME                                STATE   AGE
apigee-org1-dev-egroup                       2d
         
        kubectl -n APIGEE_NAMESPACE get ar

        NAME                                        STATE     AGE
apigee-org1-dev-egroup-123abc               running   2d

    Como reverter para uma versão anterior

    Para reverter para a versão anterior, use a versão mais antiga do gráfico para reverter o processo de upgrade na ordem inversa. Comece com apigee-virtualhost, volte para apigee-operator e depois reverta as CRDs.

    1. Reverta os gráficos. Os comandos a seguir pressupõem que você está usando os gráficos da versão anterior (v1.16.x).

      1. Execute o seguinte comando para cada grupo de ambiente:

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=ENV_GROUP_NAME \
  -f 1.16_OVERRIDES_FILE

      2. Execute o seguinte comando para cada ambiente:

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=ENV_NAME \
  -f 1.16_OVERRIDES_FILE

      3. apigee-org:

        helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      4. apigee-ingress-manager:

        helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      5. apigee-redis:

        helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      6. apigee-telemetry:

        helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      7. apigee-datastore:

        helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      8. apigee-operator:

        helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE
    2. Reverta os CRDs reinstalando os CRDs mais antigos. 
      kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false