Configurar o VMware Spring Cloud Gateway

Este artigo aplica-se a:❌ Basic/Standard ✔️ Enterprise

Este artigo mostra como configurar o VMware Spring Cloud Gateway para VMware Tanzu com o plano Azure Spring Apps Enterprise.

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

Uma instância do VMware Spring Cloud Gateway roteia o tráfego de acordo com as regras. Ele suporta escalonamento para dentro/para fora e para cima/baixo para atender a uma carga de tráfego dinâmica.

O VMware Spring Cloud Gateway 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 transportar declarações JWT (JSON Web Token) autorizadas para serviços de aplicativos
• Autorização de certificado de cliente
• Abordagens de limitação de taxas
• Configuração do disjuntor
• Suporte para acessar serviços de aplicativos por meio de credenciais de autenticação básica HTTP

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

Pré-requisitos

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

Ativar ou desativar o VMware Spring Cloud Gateway

Você pode habilitar ou desabilitar o VMware Spring Cloud Gateway após a criação da instância de serviço usando o portal do Azure ou a CLI do Azure. Antes de desativar o VMware Spring Cloud Gateway, você deve cancelar a atribuição de seu endpoint 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 VMware Spring Cloud Gateway

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

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

Atribuir um endpoint público ao VMware Spring Cloud Gateway

Esta seção descreve como atribuir um endpoint público ao VMware Spring Cloud Gateway e configurar suas propriedades.

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

Configurar metadados do VMware Spring Cloud Gateway

Os metadados do VMware Spring Cloud Gateway geram automaticamente a documentação do OpenAPI versão 3. Você pode configurar os metadados do VMware Spring Cloud Gateway para exibir grupos de rotas no portal da API para VMware Tanzu. Para obter mais informações, consulte Usar o portal da API para 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 o início de sessão único

O VMware Spring Cloud Gateway suporta autenticação e autorização por meio de logon único (SSO) com um provedor de identidade OpenID. O provedor suporta o protocolo OpenID Connect Discovery. A tabela a seguir descreve as propriedades de 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 API Portal.

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 VMware Spring Cloud Gateway suporta apenas os servidores de autorização que suportam o protocolo OpenID Connect Discovery. Além disso, certifique-se de configurar o servidor de autorização externo para permitir redirecionamentos de volta para o gateway. Consulte a documentação do servidor de autorização e adicione https://<gateway-external-url>/login/oauth2/code/sso à lista de URIs de redirecionamento permitidos.

Se você configurar a propriedade SSO errada, como a senha errada, deverá remover toda a propriedade SSO e adicionar a configuração correta.

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

Configurar o logout do SSO

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

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

Sair da sessão de IdP e SSO

Se você enviar uma GET solicitação para o /scg-logout ponto de extremidade, o ponto de extremidade enviará uma 302 resposta de redirecionamento para a URL de logout do IdP. Para fazer com que o ponto de extremidade retorne o usuário a um caminho na instância de serviço do gateway, adicione um parâmetro de redirecionamento à GET solicitação com o ponto de /scg-logout extremidade. Por exemplo, pode utilizar ${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 VMware Spring Cloud Gateway. Não é possível redirecionar para um URL externo.

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 logout para seu aplicativo. Para obter um exemplo, consulte a configuração de rota no repositório de resgate de animais no GitHub.

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

Sair apenas da sessão SSO

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

Você precisa ter uma configuração de rota para rotear a solicitação de logout para seu aplicativo, conforme mostrado no exemplo a seguir. Esse código faz uma sessão SSO de logout somente do 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 de outro domínio fora do domínio a partir do qual o primeiro recurso foi servido. A tabela a seguir descreve as opções de configuração do CORS disponíveis.

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

Usar o dimensionamento de serviço

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

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

A tabela a seguir descreve o uso de recursos padrão.

Configurar TLS entre o gateway e os aplicativos

Para melhorar a segurança e ajudar a proteger informações confidenciais contra intercetação por partes não autorizadas, você pode habilitar o Transport Layer Security (TLS) entre o VMware Spring Cloud Gateway 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 (CA) 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 Azure Spring Apps, carregue o certificado no Azure Spring Apps. Para obter mais informações, consulte a seção Importar um certificado de Usar certificados TLS/SSL em seu aplicativo no Azure Spring Apps.

Com o certificado atualizado para o Azure Spring Apps, 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 da rota

Você deve especificar o protocolo como HTTPS na configuração de rota. O objeto JSON a seguir instrui o VMware Spring Cloud Gateway 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.

Rodar certificados

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

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

O VMware Spring Cloud Gateway é 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>

Configurar configurações de dimensionamento automático

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

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 de usuário de Métricas para aplicativos Azure Spring.

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.

Habilite o cache de resposta globalmente

Depois de habilitar o cache de resposta globalmente, o cache de resposta é automaticamente habilitado 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 LocalResponseCache filtro. O exemplo a seguir mostra como usar o LocalResponseCache filtro 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 de Como usar os filtros de rota do VMware Spring Cloud Gateway com o plano do Azure Spring Apps Enterprise e LocalResponseCache na documentação do VMware.

Em vez de configurar size e timeToLive para cada LocalResponseCache filtro individualmente, você pode definir esses parâmetros no nível do Spring Cloud Gateway. Essa opção permite que você use o LocalResponseCache filtro 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 LocalResponseCache filtro 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 Azure Spring Apps gerencia e ajusta o VMware Spring Cloud Gateway. Exceto para os casos de uso que configuram o monitoramento de desempenho de aplicativos (APM) e o nível de log, normalmente não é necessário configurar o VMware Spring Cloud Gateway com variáveis de ambiente.

Se você tiver requisitos que não pode ser atendido por outras configurações descritas neste artigo, tente configurar as variáveis de ambiente mostradas na lista Propriedades comuns do aplicativo. Certifique-se de verificar 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 as variáveis de ambiente, o VMware Spring Cloud Gateway é reiniciado.

Configurar o monitoramento de desempenho do aplicativo

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

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

• Visão geral do Application Insights
• Variáveis de ambiente Dynatrace
• Novas variáveis de ambiente da Relíquia
• 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 VMware Spring Cloud Gateway, você pode criar a configuração do APM no nível da instância de serviço e vinculá-la ao Spring Cloud Gateway. Dessa forma, você pode configurar convenientemente o APM apenas uma vez e vincular o mesmo APM ao Spring Cloud Gateway e aos seus aplicativos.

Gerenciar o APM no VMware Spring Cloud Gateway (preterido)

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

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 níveis de log

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

• Você pode definir os níveis de log como TRACE, , , WARNINFO, ERROR, ou OFFDEBUG. O nível de log padrão para o VMware Spring Cloud Gateway é INFO.
• Você pode desativar os logs definindo os níveis de log como OFF.
• Quando o nível de log estiver definido como WARN, ERRORou OFF, talvez seja necessário ajustá-lo ao INFO solicitar suporte da equipe do Azure Spring Apps. Essa alteração causa uma reinicialização do VMware Spring Cloud Gateway.
• Quando o nível de log é definido como TRACE ou DEBUG, isso pode afetar o desempenho do VMware Spring Cloud Gateway. Tente evitar essas configurações em seu ambiente de produção.
• Você pode definir níveis de log para o root registrador ou para registradores específicos, como io.pivotal.spring.cloud.gateway.

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

Para obter chaves de variáveis 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 configuração do complemento

O recurso de configuração de complemento permite personalizar determinadas propriedades do VMware Spring Cloud Gateway usando uma cadeia de caracteres no 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 suportadas 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 VMware Spring Cloud Gateway.

• Configuração de SSO:

  • Nome da chave: sso

  • Tipo de valor: Objeto

  • Propriedades:

    • RolesAttributeName (String): especifica o nome do atributo que contém as funções associadas à sessão 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 (String): um identificador exclusivo para o grupo de APIs disponíveis na instância do VMware Spring Cloud Gateway. O valor pode conter apenas 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 padrão do pod.

  • Tipo de valor: Objeto

  • Propriedades

    • Containers: Esta matriz contém a configuração para contêineres individuais dentro do pod. Somente o contêiner nomeado gateway é suportado atualmente.
      • Name: Especifica o nome do contêiner. O contêiner deve ser chamado gateway.
      • Lifecycle: PreStop é um gancho de ciclo de vida que é 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 que o Kubernetes espera que um pod termine graciosamente antes de matá-lo à força.

  • Exemplo:

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

    Quando um pod contendo esse contêiner está sendo encerrado, o PreStop gancho executa o comando /bin/sh -c 'sleep 20', fazendo com que o contêiner permaneça em repouso por 20 segundos. Essa pausa dá ao contêiner algum tempo para concluir quaisquer tarefas ou limpezas em andamento antes que ele realmente pare.

    A TerminationGracePeriodSeconds configuração fornece um total de 120 segundos para o pod terminar normalmente, incluindo o tempo gasto por qualquer gancho de ciclo de vida, como PreStop.

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

Próximos passos

• Usar o Spring Cloud Gateway