Configurar um Config Server do Spring Cloud gerenciado no Azure Spring Apps

  • Artigo

Observação

Azure Spring Apps é o novo nome do serviço Azure Spring Cloud. Embora o serviço tenha um novo nome, você verá o nome antigo em alguns locais por um tempo enquanto trabalhamos para atualizar ativos como capturas de tela, vídeos e diagramas.

Este artigo aplica-se a: ✔️ Java ✔️ C#

Este artigo aplica-se a: ✔️ Consumo padrão e dedicado (Pré-visualização) ✔️ Basic/Standard ❌ Enterprise

Este artigo mostra como configurar um Config Server do Spring Cloud gerenciado no serviço Azure Spring Apps.

O Config Server do Spring Cloud oferece suporte no lado do servidor e do cliente para configuração externalizada em um sistema distribuído. A instância do Config Server fornece um local central para gerenciar propriedades externas de aplicativos em todos os ambientes. Para saber mais, confira a Documentação do Config do Spring Cloud.

Observação

Para usar o servidor de configuração no plano de consumo padrão e dedicado, você deve habilitá-lo primeiro. Para obter mais informações, consulte Habilitar e desabilitar o Spring Cloud Config Server nos aplicativos Spring do Azure.

Pré-requisitos

Restrição

Há algumas restrições quando você usa o Servidor de Configuração com um back-end do Git. Algumas propriedades são injetadas automaticamente no ambiente de aplicativo para acessar o Config Server e a Descoberta de Serviço. Se você também configurar essas propriedades em seus arquivos do Servidor de Configuração, poderá enfrentar conflitos e um comportamento inesperado.

eureka.client.service-url.defaultZone
eureka.client.tls.keystore
eureka.instance.preferIpAddress
eureka.instance.instance-id
server.port
spring.cloud.config.tls.keystore
spring.config.import
spring.application.name
spring.jmx.enabled
management.endpoints.jmx.exposure.include

Cuidado

Não coloque essas propriedades nos arquivos de aplicativo do Config Server.

Criar seus arquivos do Servidor de Configuração

Os Aplicativos Spring do Azure dão suporte ao Servidor de DevOps do Azure, GitHub, GitLab e Bitbucket para armazenar seus arquivos do Servidor de Configuração. Quando o repositório estiver pronto, crie os arquivos de configuração e armazene-os lá.

Algumas propriedades configuráveis estão disponíveis apenas para determinados tipos. As seções a seguir descrevem as propriedades de cada tipo de repositório.

Observação

O Config Server aceita master (no Git) como o rótulo padrão, caso você não especifique um. No entanto, o GitHub alterou recentemente a ramificação padrão de master para main. Para evitar a falha do Config Server do Azure Spring Apps, preste bastante atenção ao rótulo padrão ao configurar o Config Server com o GitHub, especialmente para repositórios criados recentemente.

Repositório público

Ao usar um repositório público, as propriedades configuráveis serão mais limitadas do que com um repositório privado.

A tabela a seguir lista as propriedades configuráveis que você pode usar para configurar um repositório Git público.

Observação

Usar um hífen ("-") para separar palavras é a única convenção de nomenclatura compatível no momento. Por exemplo, você pode usar default-label, mas não defaultLabel.

Propriedade Obrigatório Recurso
uri Sim O URI do repositório Git que é usado como o back-end do Config Server. Deve começar com http://, https://, git@ ou ssh://.
default-label Não O rótulo padrão do repositório Git. Deve ser o nome do branch, o nome da tag ou a ID de commit do repositório.
search-paths Não Uma matriz de cadeias de caracteres usada para pesquisar subdiretórios do repositório Git.

Repositório privado com autenticação SSH

A tabela a seguir lista as propriedades configuráveis que você pode usar para configurar um repositório Git privado com SSH.

Observação

Usar um hífen ("-") para separar palavras é a única convenção de nomenclatura compatível no momento. Por exemplo, você pode usar default-label, mas não defaultLabel.

Propriedade Obrigatório Recurso
uri Sim O URI do repositório Git que é usado como o back-end do Config Server. Deve começar com http://, https://, git@ ou ssh://.
default-label Não O rótulo padrão do repositório Git. Deve ser o nome do branch, o nome da tag ou a ID de commit do repositório.
search-paths Não Uma matriz de cadeias de caracteres usada para pesquisar subdiretórios do repositório Git.
private-key Não A chave privada SSH para acessar o repositório Git. Necessário quando o URI começa com git@ ou ssh://.
host-key Não A chave do host do servidor de repositório Git. Não deve incluir o prefixo de algoritmo abordado por host-key-algorithm.
host-key-algorithm Não O algoritmo de chave do host. Deve ser ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384 ou ecdsa-sha2-nistp521. Necessário somente se host-key existir.
strict-host-key-checking Não Indica se a instância do Config Server falha ao iniciar ao usar o host-keyarquivo privado . Deve ser true (valor padrão) ou false.

Repositório privado com autenticação Básica

A tabela a seguir lista as propriedades configuráveis que você pode usar para configurar um repositório Git privado com autenticação básica.

Observação

Usar um hífen ("-") para separar palavras é a única convenção de nomenclatura compatível no momento. Por exemplo, use default-label, não defaultLabel.

Propriedade Obrigatório Recurso
uri Sim O URI do repositório Git que é usado como o back-end do Config Server. Deve começar com http://, https://, git@ ou ssh://.
default-label Não O rótulo padrão do repositório Git. Deve ser o nome do branch, o nome da tag ou a commit-id do repositório.
search-paths Não Uma matriz de cadeias de caracteres usada para pesquisar subdiretórios do repositório Git.
username Não O nome de usuário usado para acessar o servidor de repositório Git. Obrigatório quando o servidor de repositório Git dá suporte à autenticação básica HTTP.
password Não A senha ou o token de acesso pessoal usado para acessar o servidor de repositório Git. Obrigatório quando o servidor de repositório Git dá suporte à autenticação básica HTTP.

Observação

Muitos servidores de repositório Git são compatíveis com o uso de tokens em vez de senhas para autenticação básica HTTP. Alguns repositórios permitem que os tokens persistam indefinidamente. No entanto, alguns servidores de repositório Git, incluindo o Azure DevOps Server, forçam tokens a expirar em algumas horas. Os repositórios que fazem com que os tokens expirem não devem usar a autenticação baseada em token com o Azure Spring Apps. Se você usar esse token, lembre-se de atualizá-lo antes que ele expire.

O GitHub removeu o suporte para autenticação de senha, portanto, você precisa usar um token de acesso pessoal em vez de autenticação de senha para o GitHub. Para obter mais informações, confira Requisitos de autenticação de token para operações do Git.

Outros repositórios Git

A tabela a seguir lista as propriedades configuráveis que você pode usar para configurar um repositório Git com um padrão.

Observação

Usar um hífen ("-") para separar palavras é a única convenção de nomenclatura compatível no momento. Por exemplo, use default-label, não defaultLabel.

Propriedade Obrigatório Recurso
repos Não Um mapa que consiste nas configurações de um repositório Git com um determinado nome.
repos."uri" Sim em repos O URI do repositório Git que é usado como o back-end do Config Server. Deve começar com http://, https://, git@ ou ssh://.
repos."name" Sim em repos Um nome para identificar o repositório. Por exemplo, team-A ou team-B. Necessário somente se repos existir.
repos."pattern" Não Uma matriz de cadeias de caracteres usada para corresponder a um nome de aplicativo. Para cada padrão, use o formato {application}/{profile} com caracteres curinga.
repos."default-label" Não O rótulo padrão do repositório Git. Deve ser o nome do branch, o nome da tag ou o IOD do commit do repositório.
repos."search-paths" Não Uma matriz de cadeias de caracteres usada para pesquisar subdiretórios do repositório Git.
repos."username" Não O nome de usuário usado para acessar o servidor de repositório Git. Obrigatório quando o servidor de repositório Git dá suporte à autenticação básica HTTP.
repos."password" Não A senha ou o token de acesso pessoal usado para acessar o servidor de repositório Git. Obrigatório quando o servidor de repositório Git dá suporte à autenticação básica HTTP.
repos."private-key" Não A chave privada SSH para acessar o repositório Git. Obrigatório quando o URI começa com git@ ou ssh://.
repos."host-key" Não A chave do host do servidor de repositório Git. Não deve incluir o prefixo de algoritmo abordado por host-key-algorithm.
repos."host-key-algorithm" Não O algoritmo de chave do host. Deve ser ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384 ou ecdsa-sha2-nistp521. Necessário somente se host-key existir.
repos."strict-host-key-checking" Não Indica se a instância do Config Server falha ao iniciar ao usar o host-keyarquivo privado . Deve ser true (valor padrão) ou false.

A tabela a seguir mostra alguns exemplos de padrões para configurar seu serviço com um repositório extra opcional. Para obter mais informações, consulte a seção Repositórios extras e a seção Correspondência de padrões e repositórios múltiplos da documentação do Spring.

Padrões Descrição
test-config-server-app-0/* O padrão e o URI do repositório corresponderão a um aplicativo Spring Boot chamado test-config-server-app-0 com qualquer perfil.
test-config-server-app-1/dev O padrão e o URI do repositório corresponderão a um aplicativo Spring Boot chamado test-config-server-app-1 com um perfil de desenvolvimento.
test-config-server-app-2/prod O padrão e o URI do repositório corresponderão a um aplicativo Spring Boot chamado test-config-server-app-2 com um perfil de produção.

Screenshot of Azure portal showing the Config Server page with the Patterns column of the Additional repositories table highlighted.

Anexar o repositório do Config Server ao Azure Spring Apps

Agora os arquivos de configuração estão salvos em um repositório, siga as próximas etapas para conectar o serviço Aplicativos Spring do Azure ao repositório.

  1. Entre no portal do Azure.

  2. Acesse a página Visão Geral do Azure Spring Apps.

  3. Escolha Config Server no painel de navegação à esquerda.

  4. Na seção Repositório padrão, defina URI como https://github.com/Azure-Samples/piggymetrics-config.

  5. Selecione Validar.

    Screenshot of Azure portal showing the Config Server page.

  6. Quando a validação for concluída, selecione Aplicar para salvar as alterações.

    Screenshot of Azure portal showing Config Server page with Apply button highlighted.

A atualização da configuração pode levar alguns minutos. Você deverá receber uma notificação quando a configuração for concluída.

Insira as informações do repositório diretamente para o portal do Azure

Você pode inserir informações do repositório para o repositório padrão e, opcionalmente, para repositórios extras.

Repositório padrão

Use as etapas nesta seção para inserir informações para um repositório público ou privado.

  • Repositório público: na seção Repositório padrão, na caixa Uri, cole o URI do repositório. Insira configuração para a definição rótulo. Verifique se a configuração Autenticação é Pública e selecione Aplicar.

  • Repositório privado: o Azure Spring Apps é compatível com SSH e autenticação básica baseada em token/senha.

    • Autenticação Básica: na seção Repositório padrão, na caixa URI, cole o URI do repositório e selecione a configuração em Autenticação para abrir o painel Editar Autenticação. Na lista suspensa Tipo de autenticação, selecione HTTP Básico e insira seu nome de usuário e senha/token para permitir acesso aos Aplicativos Spring do Azure. Selecione OK e Aplicar para concluir a configuração de sua instância do Servidor de Configuração.

    Screenshot of the Default repository section showing authentication settings for Basic authentication.

    Observação

    Muitos servidores de repositório Git são compatíveis com o uso de tokens em vez de senhas para autenticação básica HTTP. Alguns repositórios permitem que os tokens persistam indefinidamente. No entanto, alguns servidores de repositório Git, incluindo o Azure DevOps Server, forçam tokens a expirar em algumas horas. Os repositórios que fazem com que os tokens expirem não devem usar a autenticação baseada em token com o Azure Spring Apps. Se você usar esse token, lembre-se de atualizá-lo antes que ele expire.

    O GitHub removeu o suporte para autenticação de senha, portanto, você precisa usar um token de acesso pessoal em vez de autenticação de senha para o GitHub. Para obter mais informações, confira Requisitos de autenticação de token para operações do Git.

    • SSH: na seção Repositório padrão, na caixa Uri, cole o URI do repositório e selecione a configuração em Autenticação para abrir o painel Editar Autenticação. No painel Editar Autenticação, na lista suspensa Tipo de autenticação, selecione SSH e insira sua chave privada. Opcionalmente, especifique a chave do host e o algoritmo de chave do host. Inclua a chave pública no repositório do Config Server. Selecione OK e Aplicar para concluir a configuração de sua instância do Servidor de Configuração.

    Screenshot of the Default repository section showing authentication settings for SSH authentication.

Repositórios extras

Se você quiser configurar seu serviço com um repositório extra opcional, especifique as configurações de Uri e Autenticação como fez para o repositório padrão. Não deixe de incluir a configuração Nome para o padrão e depois selecione Aplicar para anexá-la à instância.

Inserir informações do repositório em um arquivo YAML

Se você tiver escrito um arquivo YAML com as configurações do repositório, poderá importá-lo diretamente do computador local para o Azure Spring Apps. O exemplo a seguir mostra um arquivo YAML simples de um repositório privado com autenticação básica.

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/azure-spring-apps-samples-pr/config-server-repository.git
          username: <username>
          password: <password/token>

Selecione o botão Importar configurações e, em seguida, selecione o arquivo YAML do diretório do projeto. Selecione Importar.

Screenshot of the Config Server Import settings pane.

Suas Notificações exibem uma operação async. O Config Server deve relatar êxito após um a dois minutos. As informações do arquivo YAML são exibidas no portal do Azure. Clique em Aplicar para concluir a importação.

Usar o Azure Repos para a configuração dos Aplicativos Spring do Azure

O Azure Spring Apps poderá acessar repositórios Git públicos, protegidos por SSH ou por uma autenticação básica HTTP. A autenticação básica HTTP é a opção mais fácil para criar e gerenciar repositórios com o Azure Repos.

Obter URL e credenciais do repositório

Use as etapas a seguir para obter a URL e as credenciais do repositório.

  1. No portal do Azure Repos do seu projeto, clique no botão Clonar:

  2. Copie a URL a ser clonada da caixa de texto. Essa URL normalmente está na seguinte forma:

    https://<organization name>@dev.azure.com/<organization name>/<project name>/_git/<repository name>

    Remova tudo após https:// e antes de dev.azure.com, incluindo o símbolo @. A URL resultante deve estar neste formato:

    https://dev.azure.com/<organization name>/<project name>/_git/<repository name>

    Salve essa URL para uso na próxima seção.

  3. Selecione Gerar Credenciais do Git para exibir um nome de usuário e uma senha, que devem ser salvos para uso na seção a seguir.

Configurar o Azure Spring Apps para acessar o repositório Git

  1. Entre no portal do Azure.

  2. Acesse a página Visão Geral do Azure Spring Apps.

  3. Escolha o serviço a ser configurado.

  4. No painel à esquerda da página do serviço, em Configurações, escolha a guia Config Server. Configure o repositório que você criou, desta forma:

    • Adicione o URI do repositório que você salvou na seção anterior.
    • Selecione a configuração em Autenticação para abrir o painel Editar autenticação.
    • Para Tipo de autenticação, selecione HTTP Básico.
    • Para Nome de Usuário, especifique o nome de usuário que você salvou na seção anterior.
    • Para Senha, especifique a senha que você salvou na seção anterior.
    • Selecione OK e aguarde a conclusão da operação.

    Screenshot of repository configuration settings.

Excluir sua configuração

Selecione Redefinir na guia Config Server para apagar as configurações existentes. Exclua as configurações do servidor de configuração se quiser conectar sua instância do Config Server a outra origem, como quando estiver migrando do GitHub para o Servidor de DevOps do Azure.

Atualização do Config Server

Quando as propriedades são alteradas, os serviços que consomem essas propriedades precisam ser notificados para que as alterações possam ser feitas. A solução padrão para o Config Server do Spring Cloud é disparar manualmente o evento de atualização, o que pode não ser viável quando há muitas instâncias do aplicativo. Para obter mais informações, confira Configuração Centralizada

Como alternativa, você pode atualizar automaticamente os valores do Config Server, permitindo que o cliente de configuração sonde se há alterações com base em uma atualização interna. Use as etapas a seguir para atualizar automaticamente os valores do Config Server.

  1. Registre uma tarefa agendada para atualizar o contexto em um determinado intervalo, conforme é mostrado no exemplo a seguir.

    @ConditionalOnBean({RefreshEndpoint.class})
@Configuration
@AutoConfigureAfter({RefreshAutoConfiguration.class, RefreshEndpointAutoConfiguration.class})
@EnableScheduling
public class ConfigClientAutoRefreshConfiguration implements SchedulingConfigurer {
    @Value("${spring.cloud.config.refresh-interval:60}")
    private long refreshInterval;
    @Value("${spring.cloud.config.auto-refresh:false}")
    private boolean autoRefresh;
    private RefreshEndpoint refreshEndpoint;
    public ConfigClientAutoRefreshConfiguration(RefreshEndpoint refreshEndpoint) {
        this.refreshEndpoint = refreshEndpoint;
    }
    @Override
    public void configureTasks(ScheduledTaskRegistrar scheduledTaskRegistrar) {
        if (autoRefresh) {
            // set minimal refresh interval to 5 seconds
            refreshInterval = Math.max(refreshInterval, 5);
            scheduledTaskRegistrar.addFixedRateTask(() -> refreshEndpoint.refresh(), refreshInterval * 1000);
        }
    }
}

  2. Habilite a atualização automática e defina o intervalo de atualização apropriado no arquivo application.yml . No exemplo a seguir, o cliente pesquisa alterações de configuração a cada 60 segundos, que é o valor mínimo que você pode definir para um intervalo de atualização.

    Por padrão, a atualização automática é definida como false e o intervalo de atualização é definido como 60 segundos.

    spring:
    cloud:
         config:
          auto-refresh: true
          refresh-interval: 60
management:
    endpoints:
         web:
          exposure:
            include:
              - refresh

  3. Adicione @RefreshScope no código. No exemplo a seguir, a variável connectTimeout é atualizada automaticamente a cada 60 segundos.

    @RestController
@RefreshScope
public class HelloController {
    @Value("${timeout:4000}")
    private String connectTimeout;
}

Para obter mais informações, confira o exemplo config-client-polling.

Próximas etapas

Neste artigo, você aprendeu como habilitar e configurar sua instância do Config Server do Spring Cloud. Para saber mais como gerenciar seu aplicativo, confira Escalar um aplicativo no Azure Spring Apps.