Configurar o Spring Cloud Gateway do VMware

Este artigo se aplica a(o):❌ Básico/Standard ✔️ Enterprise

Esse artigo mostra como configurar o Spring Cloud Gateway da VMware para a VMware Tanzu com o plano Enterprise dos Aplicativos Spring do Azure.

O Spring Cloud Gateway do VMware é um componente comercial do VMware Tanzu baseado no projeto do Spring Cloud Gateway de código aberto. O Spring Cloud Gateway da VMware para Tanzu cuida de preocupações variadas das equipes de desenvolvimento de API, como logon único (SSO), controle de acesso, limitação de taxa, resiliência, segurança, entre outros. Você pode acelerar a entrega de API usando padrões nativos de nuvem modernos em sua escolha de linguagem de programação para desenvolvimento de API.

Uma instância do Spring Cloud Gateway da VMware encaminha o tráfego de acordo com as regras. Ela dá suporte à escala horizontal/vertical e à escala para cima/para baixo para atender a uma carga de tráfego dinâmico.

O Spring Cloud Gateway do VMware inclui os seguintes recursos:

• Configuração de roteamento dinâmico, independente de aplicativos individuais, que você pode aplicar e alterar sem recompilar
• Filtros de rota de API comercial para transporte de declarações Token Web JSON (JWT) autorizadas para os serviços de aplicativo
• Autorização de certificado do cliente
• Abordagens de limitação de taxa
• Configuração do disjuntor
• Suporte para acessar serviços de aplicativo usando as credenciais de Autenticação HTTP Básica.

Para a integração com o portal de API do VMware Tanzu, o Spring Cloud Gateway da VMware gera automaticamente a documentação do OpenAPI versão 3 após quaisquer adições ou alterações na configuração da rota. Para obter mais informações, consulte Usar o portal de API do VMware Tanzu.

Pré-requisitos

• Uma instância de serviço já provisionada do plano Enterprise dos Aplicativos Spring do Azure com o Spring Cloud Gateway da VMware habilitado. Para obter mais informações, confira Início Rápido: criar e implantar aplicativos nos Aplicativos Spring do Azure usando o plano Enterprise.
• CLI do Azure versão 2.0.67 ou posterior. Use o seguinte comando para instalar a extensão dos Aplicativos Spring do Azure: az extension add --name spring.

Habilitar ou desabilitar o Spring Cloud Gateway da VMware

Você pode habilitar ou desabilitar o Spring Cloud Gateway da VMware após a criação da instância de serviço usando o portal do Azure ou a CLI do Azure. Antes de desabilitar o Spring Cloud Gateway da VMware, você deve cancelar a atribuição de seu ponto de extremidade e remover todas as configurações de rota.

az spring gateway create \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name>

az spring gateway delete \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name>

Reinicie o Spring Cloud Gateway da VMware

Depois de concluir a ação de reinicialização, as instâncias do Spring Cloud Gateway da VMware são reiniciadas sem interrupção.

az spring gateway restart \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name>

Como atribuir um ponto de extremidade público ao Spring Cloud Gateway da VMware

Esta seção descreve como atribuir um ponto de extremidade ao Spring Cloud Gateway da VMware e configurar suas propriedades.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --assign-endpoint true

Configurar os metadados do Spring Cloud Gateway do VMware

Os metadados do Spring Cloud Gateway da VMware geram automaticamente a documentação do OpenAPI versão 3. Você pode configurar metadados do Spring Cloud Gateway da VMware para exibir grupos de rotas no portal de API da VMware Tanzu. Para obter mais informações, consulte Usar o portal de API da VMware Tanzu.

A tabela a seguir descreve as opções de metadados disponíveis:

Você pode usar o portal do Azure ou a CLI do Azure para editar propriedades de metadados.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --api-description "<api-description>" \
    --api-title "<api-title>" \
    --api-version "v0.1" \
    --server-url "<gateway-endpoint-URL>" \
    --allowed-origins "*"

Configurar logon único

O Spring Cloud Gateway da VMware dá suporte à autenticação e autorização por meio de logon único (SSO) com um provedor de identidade OpenID. O provedor dá suporte ao protocolo de Descoberta do OpenID Connect. A tabela a seguir descreve as propriedades do SSO:

Para configurar o SSO com o Microsoft Entra ID, consulte Configurar o logon único usando o Microsoft Entra ID para o Spring Cloud Gateway e o Portal de API.

Você pode usar o portal do Azure ou a CLI do Azure para editar propriedades de SSO.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --client-id <client-id> \
    --client-secret <client-secret> \
    --issuer-uri <issuer-uri> \
    --scope <scope>

O Spring Cloud Gateway da VMware dá suporte apenas aos servidores de autorização que dão suporte ao protocolo de Descoberta do OpenID Connect. Configure o servidor de autorização externo para permitir redirecionamentos para o gateway. Veja a documentação do servidor de autorização e adicione https://<gateway-external-url>/login/oauth2/code/sso à lista de URIs de redirecionamento permitidos.

Ao configurar a propriedade de SSO incorreta, como a senha incorreta, deve-se removê-la inteiramente e adicionar a configuração correta.

Depois de configurar o SSO, lembre-se de definir ssoEnabled: true para as rotas do Spring Cloud Gateway da VMware.

Configurar o logoff do SSO

As instâncias de serviço do Spring Cloud Gateway da VMware fornecem um ponto de extremidade de API padrão para sair da sessão de SSO atual. O caminho para esse ponto de extremidade é /scg-logout. O logoff resulta em um dos seguintes resultados, dependendo de como você chama o ponto de extremidade de logoff:

• Faça logoff da sessão e redirecione para o logoff do provedor de identidade (IdP).
• Faça logoff da sessão da instância de serviço.

Fazer logoff da sessão de IdP e SSO

Se você enviar uma solicitação GET para o ponto de extremidade /scg-logout, o ponto de extremidade enviará uma resposta de redirecionamento 302 para a URL de logoff do IdP. Para obter o ponto de extremidade para retornar o usuário a um caminho na instância de serviço do gateway, adicione um parâmetro de redirecionamento à solicitação GET com o ponto de extremidade/scg-logout. Por exemplo, você pode usar ${server-url}/scg-logout?redirect=/home.

O valor do parâmetro de redirecionamento deve ser um caminho válido na instância de serviço do Spring Cloud Gateway da VMware. Você não pode redirecionar para uma URL externa.

As etapas a seguir descrevem um exemplo de como implementar a função em seus microsserviços:

1. Obtenha uma configuração de rota para rotear a solicitação de logoff para seu aplicativo. Para obter um exemplo, consulte a configuração de rota no repositório animal-rescue no GitHub.

2. Adicione qualquer lógica de logoff necessária ao aplicativo. No final, você precisa de uma solicitação GET para o ponto de extremidade /scg-logout do gateway, conforme mostrado no valor return do método getActionButton no repositório animal-rescue.

Faça logoff apenas da sessão de SSO

Se você enviar a solicitação GET para o ponto de extremidade /scg-logout usando XMLHttpRequest, o redirecionamento 302 poderá ser engolido e não tratado no manipulador de resposta. Nesse caso, o usuário só seria desconectado da sessão de SSO na instância de serviço do Spring Cloud Gateway da VMware. O usuário ainda teria uma sessão IdP válida. Normalmente, se o usuário tentar fazer logon novamente, ele será enviado automaticamente para o gateway como autenticado do IdP.

Você precisa ter uma configuração de rota para rotear a solicitação de logoff para seu aplicativo, conforme mostrado no exemplo a seguir. Esse código faz uma sessão de SSO de logoff somente no gateway.

const req = new XMLHttpRequest();
req.open("GET", "/scg-logout);
req.send();

Configurar o compartilhamento de recursos entre origens

O compartilhamento de recursos entre origens (CORS) permite que recursos restritos em uma página da Web sejam solicitados por outro domínio externo ao domínio cujo primeiro recurso foi atendido. As opções de configuração de CORS disponíveis estão descritas na tabela a seguir.

Certifique-se de ter a configuração CORS correta se desejar integrar com o portal API. Para obter mais informações, consulte a seção Atribuir um ponto de extremidade público ao Spring Cloud Gateway da VMware.

Usar escala de serviço

Você pode personalizar a alocação de recursos para instâncias do Spring Cloud Gateway da VMware, incluindo vCPU, memória e contagem de instâncias.

Para alta disponibilidade, não recomendamos usar uma única réplica.

A tabela a seguir descreve o uso do recurso padrão.

Configurar o TLS entre o gateway e os aplicativos

Para aprimorar a segurança e ajudar a proteger informações confidenciais contra interceptação por partes não autorizadas, você pode habilitar o Transport Layer Security (TLS) entre o Spring Cloud Gateway da VMware e seus aplicativos.

Antes de configurar o TLS, você precisa ter um aplicativo habilitado para TLS e um certificado TLS. Para preparar um certificado TLS, gere um certificado de uma autoridade de certificação (AC) confiável. O certificado verifica a identidade do servidor e estabelece uma conexão segura.

Depois de ter um aplicativo habilitado para TLS em execução no Aplicativos Spring do Azure, carregue o certificado nos Aplicativos Spring do Azure. Para obter mais informações, consulte a seção Importar um certificado de Usar certificados TLS/SSL em seu aplicativo nos Aplicativos Spring do Azure.

Com o certificado atualizado para os Aplicativos Spring do Azure, você pode configurar o certificado TLS para o gateway e habilitar a verificação de certificado. Você pode configurar o certificado no portal do Azure ou usando a CLI do Azure.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-cert-verify <value> \
    --certificate-names <certificate-name-in-Azure-Spring-Apps>

Preparar a configuração de rota

Você deve especificar o protocolo como HTTPS na configuração de rota. O objeto JSON a seguir instrui o Spring Cloud Gateway da VMware a usar o protocolo HTTPS para todo o tráfego entre o gateway e o aplicativo.

1. Crie um arquivo chamado test-tls-route.json com o seguinte conteúdo:

   {
       "routes": [
         {
           "title": "Test TLS app",
           "predicates": [
             "Path=/path/to/your/app",
             "Method=GET"
           ]
         }
        ],
       "uri": "https://<app-custom-domain-name>"
   }
   

2. Use o seguinte comando para aplicar a regra ao aplicativo:

   az spring gateway route-config create \
       --resource-group <resource-group-name> \
       --service <Azure-Spring-Apps-instance-name> \
       --name test-tls-app \
       --routes-file test-tls-route.json
   

Agora você pode testar se o aplicativo está habilitado para TLS com o ponto de extremidade do gateway. Para obter mais informações, consulte a seção Configurar rotas de Usar o Spring Cloud Gateway.

Girar certificados

À medida que os certificados expiram, você precisa girar certificados no Spring Cloud Gateway da VMware usando as seguintes etapas:

1. Gere novos certificados de uma AC confiável.
2. Importe os certificados para Aplicativos Spring do Azure. Para obter mais informações, consulte a seção Importar um certificado de Usar certificados TLS/SSL em seu aplicativo nos Aplicativos Spring do Azure.
3. Sincronize os certificados usando o portal do Azure ou a CLI do Azure.

O Spring Cloud Gateway da VMware é reiniciado para garantir que o gateway use o novo certificado para todas as conexões.

az spring gateway restart \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name>

Definições da configuração do dimensionamento automático

Você pode definir modos de dimensionamento automático para o Spring Cloud Gateway da VMware.

az monitor autoscale create \
    --resource-group <resource-group-name> \
    --name <autoscale-setting-name> \
    --resource /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.AppPlatform/Spring/<service-instance-name>/gateways/default \
    --min-count 1 \
    --max-count 5 \
    --count 1

az monitor autoscale rule create \
    --resource-group <resource-group-name> \
    --autoscale-name <autoscale-setting-name> \
    --scale out 1 \
    --cooldown 1 \
    --condition "GatewayHttpServerRequestsSecondsCount > 100 avg 1m"

Para obter mais informações sobre as métricas disponíveis, consulte a seção Opções de métricas do usuário de Métricas para os Aplicativos Spring do Azure.

Configurar o cache de resposta

A configuração do cache de resposta fornece uma maneira de definir um cache de resposta HTTP que você pode aplicar globalmente ou no nível da rota.

Habilitar o cache de resposta globalmente

Depois de habilitar o cache de resposta globalmente, o cache de resposta será habilitado automaticamente para todas as rotas aplicáveis.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name>
    --enable-response-cache \
    --response-cache-scope Instance \
    --response-cache-size {Examples are 1GB, 100MB, 100KB} \
    --response-cache-ttl {Examples are 1h, 30m, 50s}

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-response-cache false

Habilitar o cache de resposta no nível da rota

Para habilitar o cache de resposta para qualquer rota, use o filtro LocalResponseCache. O exemplo a seguir mostra como usar o filtro LocalResponseCache na configuração da regra de roteamento:

{
   "filters": [
      "<other-app-level-filter-of-route>",
   ],
   "routes": [
      {
        "predicates": [
            "Path=/api/**",
            "Method=GET"
         ],
         "filters": [
            "<other-filter-of-route>",
            "LocalResponseCache=3m, 1MB"
         ],
      }
   ]
}

Para obter mais informações, consulte a seção LocalResponseCache sobre Como usar filtros de rota do Spring Cloud Gateway da VMware com o plano Enterprise dos Aplicativos Spring do Azure e LocalResponseCache na documentação da VMware.

Em vez de configurar size e timeToLive para cada filtro LocalResponseCache individualmente, você pode definir esses parâmetros no nível do Spring Cloud Gateway. Essa opção permite que você use o filtro LocalResponseCache sem especificar esses valores inicialmente, mantendo a flexibilidade para substituí-los posteriormente.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-response-cache \
    --response-cache-scope Route \
    --response-cache-size {Examples are 1GB, 100MB, 100KB} \
    --response-cache-ttl {Examples are 1h, 30m, 50s}

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --enable-response-cache false

O exemplo a seguir mostra como usar o filtro LocalResponseCache quando size e timeToLive são definidos no nível do Spring Cloud Gateway:

{
   "filters": [
      "<other-app-level-filter-of-route>",
   ],
   "routes": [
      {
        "predicates": [
            "Path=/api/path1/**",
            "Method=GET"
         ],
         "filters": [
            "<other-filter-of-route>",
            "LocalResponseCache"
         ],
      },
      {
        "predicates": [
            "Path=/api/path2/**",
            "Method=GET"
         ],
         "filters": [
            "<other-filter-of-route>",
            "LocalResponseCache=3m, 1MB"
         ],
      }
   ]
}

Configurar variáveis de ambiente

O serviço Aplicativos Spring do Azure gerencia e ajusta o Spring Cloud Gateway da VMware. Com exceção dos casos de uso que configuram o monitoramento de desempenho do aplicativo (APM) e o nível de log, normalmente você não precisa configurar o Spring Cloud Gateway da VMware com variáveis de ambiente.

Se você tiver requisitos que não pode atender por outras configurações descritas neste artigo, poderá tentar configurar as variáveis de ambiente mostradas na lista de propriedades do aplicativo Comum. Verifique sua configuração em seu ambiente de teste antes de aplicá-la ao seu ambiente de produção.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --properties <key=value> \
    --secrets <key=value>

Depois de atualizar variáveis de ambiente, o Spring Cloud Gateway da VMware será reiniciado.

Configurar o monitoramento de desempenho de aplicativos

Para monitorar o Spring Cloud Gateway da VMware, você pode configurar o APM. A tabela a seguir lista os cinco tipos de agentes Java do APM que o Spring Cloud Gateway da VMware fornece, juntamente com suas variáveis de ambiente necessárias.

Para outras variáveis de ambiente com suporte, consulte as seguintes fontes:

• Visão geral do Application Insights
• Variáveis de ambiente do Dynatrace
• Variáveis de ambiente do New Relic
• Variáveis de ambiente do AppDynamics
• Variáveis de ambiente elástico

Configurar a integração do APM no nível da instância de serviço (recomendado)

Para habilitar o monitoramento do APM no Spring Cloud Gateway da VMware, você pode criar a configuração do APM no nível da instância de serviço e associá-la ao Spring Cloud Gateway. Dessa forma, você pode configurar convenientemente o APM apenas uma vez e associar o mesmo APM ao Spring Cloud Gateway e aos seus aplicativos.

Gerenciar o APM no Spring Cloud Gateway da VMware (preterido)

Você pode usar o portal do Azure ou a CLI do Azure para configurar o APM no Spring Cloud Gateway da VMware. Você também pode especificar os tipos de agentes Java do APM a serem usados e as variáveis de ambiente do APM correspondentes às quais eles dão suporte.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --apm-types <APM-type> \
    --properties <key=value> \
    --secrets <key=value>

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --apm-types ApplicationInsights \
    --properties APPLICATIONINSIGHTS_CONNECTION_STRING=<your-Application-Insights-connection-string> APPLICATIONINSIGHTS_SAMPLE_RATE=10

Configurar os níveis de log

Você pode configurar os níveis de log do Spring Cloud Gateway da VMware das seguintes maneiras para obter mais detalhes ou reduzir logs:

• Você pode definir níveis de log como TRACE, DEBUG, INFO, WARN, ERROR ou OFF. O nível de log padrão do Spring Cloud Gateway da VMware é INFO.
• Você pode desativar logs definindo os níveis de log como OFF.
• Quando o nível de log é definido como WARN, ERROR ou OFF, você pode ser obrigado a ajustá-lo para INFO ao solicitar suporte da equipe dos Aplicativos Spring do Azure. Essa alteração causa uma reinicialização do Spring Cloud Gateway da VMware.
• Quando o nível de log é definido como TRACE ou DEBUG, isso pode afetar o desempenho do Spring Cloud Gateway da VMware. Tente evitar essas configurações em seu ambiente de produção.
• Você pode definir níveis de log para o agente root ou para agentes específicos como io.pivotal.spring.cloud.gateway.

Os seguintes agentes podem conter informações valiosas de solução de problemas nos níveis TRACE e DEBUG:

Para obter chaves de variável de ambiente, adicione o prefixo logging.level. e defina o nível de log configurando o ambiente logging.level.{loggerName}={logLevel}. Os exemplos a seguir mostram as etapas para o portal do Azure e a CLI do Azure.

az spring gateway update \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --properties \
      logging.level.root=INFO \
      logging.level.io.pivotal.spring.cloud.gateway=DEBUG \
      logging.level.org.springframework.cloud.gateway=DEBUG \
      logging.level.org.springframework.boot.autoconfigure.web=TRACE \
      logging.level.org.springframework.security.web=ERROR

Atualizar a configuração do complemento

O recurso de configuração de complemento permite personalizar determinadas propriedades do Spring Cloud Gateway da VMware usando uma cadeia de caracteres de formato JSON. O recurso é útil quando você precisa configurar propriedades que não são expostas por meio da API REST.

A configuração do complemento é um objeto JSON com pares chave/valor que representam a configuração desejada. O exemplo a seguir mostra a estrutura do formato JSON:

{
    "<addon-key-name>": {
        "<addon-key-name>": "<addon-value>"
        ...
    },
    "<addon-key-name>": "<addon-value>",
    ...
}

A lista a seguir mostra as configurações de complemento com suporte para os nomes de chave de complemento e tipos de valor. Esta lista está sujeita a alterações à medida que atualizamos a versão do Spring Cloud Gateway da VMware.

• Configuração de SSO:

  • Nome da chave: sso

  • Tipo de valor: Objeto

  • Propriedades:

    • RolesAttributeName (Cadeia de caracteres): especifica o nome do atributo que contém as funções associadas à sessão de SSO.
    • InactiveSessionExpirationInMinutes (Inteiro): especifica o tempo de expiração, em minutos, para sessões de SSO inativas. Um valor de 0 significa que a sessão nunca expira.

  • Exemplo:

    {
        "sso": {
            "rolesAttributeName": "roles",
            "inactiveSessionExpirationInMinutes": 1
        }
    }
    

• Configuração de metadados:

  • Nome da chave: api

  • Tipo de valor: Objeto

  • Propriedades

    • groupId (Cadeia de caracteres): um identificador exclusivo para o grupo de APIs disponíveis na instância do Spring Cloud Gateway da VMware. O nome só pode conter letras minúsculas e números.

  • Exemplo:

    {
        "api": {
            "groupId": "id1"
        }
    }
    

• Configuração do pod

  • Nome da chave: PodOverrides, que é usado para especificar substituições para a configuração de pod padrão.

  • Tipo de valor: Objeto

  • Propriedades

    • Containers: esta matriz contém a configuração para contêineres individuais dentro do pod. No momento, há suporte apenas para o contêiner nomeado gateway.
      • Name: especifica o nome do contêiner. O contêiner deve ser nomeado gateway.
      • Lifecycle: PreStop é um gancho de ciclo de vida executado quando um contêiner está prestes a ser encerrado. Este gancho permite que você execute qualquer limpeza necessária antes que o contêiner pare.
    • TerminationGracePeriodSeconds: especifica a quantidade de tempo pela qual o Kubernetes aguarda que um pod seja terminado normalmente antes de encerrá-lo à força.

  • Exemplo:

    {
        "PodOverrides": {
            "Containers": [
                {
                    "Name": "gateway",
                    "Lifecycle": {
                        "PreStop": {
                            "Exec": {
                                "Command": [
                                    "/bin/sh",
                                    "-c",
                                    "sleep 20"
                                ]
                            }
                        }
                    }
                }
            ],
            "TerminationGracePeriodSeconds": 120
        }
    }
    

    Quando um pod que contém este contêiner está sendo encerrado, o gancho PreStop executa o comando /bin/sh -c 'sleep 20', fazendo com que o contêiner seja colocado em suspensão por 20 segundos. Esta pausa dá ao contêiner algum tempo para concluir as tarefas ou a limpeza em andamento antes que ele realmente pare.

    A configuração TerminationGracePeriodSeconds fornece um total de 120 segundos para que o pod termine normalmente, incluindo o tempo gasto por quaisquer ganchos de ciclo de vida, como PreStop.

Use as seguintes etapas para atualizar a configuração do complemento.

Próximas etapas

• Usar o Spring Cloud Gateway