Configurar políticas de armazenamento de mensagens

Se você publicar mensagens no endpoint global do Pub/Sub, o Pub/Sub armazenará automaticamente as mensagens na região do Google Cloud mais próxima. Se você quiser controlar as regiões em que suas mensagens são armazenadas e processadas, configure uma política de armazenamento de mensagens no seu tópico.

Visão geral da política de armazenamento de mensagens

É possível definir uma política de armazenamento de mensagens ao criar um novo tópico ou ao atualizar um tópico usando o console, a Google Cloud CLI ou as APIs REST.

A política de armazenamento de mensagens só é aplicada ao conteúdo das mensagens. A política não se aplica a outros dados, como nomes de tópicos, rótulos ou configurações do Identity and Access Management (IAM).

O Pub/Sub armazena mensagens quando um cliente as publica no Pub/Sub. Uma política de armazenamento de mensagens garante que o Pub/Sub armazene e processe mensagens somente no conjunto de regiões do Google Cloud especificadas, independentemente da origem das solicitações de publicação ou assinatura. Se a política permitir várias regiões para operações de publicação, o Pub/Sub armazenará a mensagem em uma região permitida mais próxima de onde a mensagem publicada entra na rede do Google Cloud.

Ao especificar uma política de armazenamento de mensagens, você pode definir enforceInTransit como True. Essa sinalização rege o seguinte:

As solicitações de publicação, pull e streamingPull recebidas em uma região não permitida na política de armazenamento de mensagens são rejeitadas com um erro FAILED_PRECONDITION.
A entrega para assinaturas de push é processada apenas nas regiões permitidas do Cloud. Em alguns casos, essa restrição pode pausar completamente a entrega de mensagens para assinaturas de push. Quando uma assinatura de push entra nesse estado devido a restrições excessivas por uma combinação de fatores como local de armazenamento de mensagens, regiões permitidas e local de recurso de exportação, esse estado fica visível no Stackdriver.

Políticas de armazenamento de mensagens para novos tópicos

Se você não especificar uma política de armazenamento de mensagens ao criar um tópico, ela será determinada automaticamente com base na política da organização Restrição de local de recursos em vigor. Quando nenhuma política da organização está em vigor, a política de armazenamento de mensagens permite todas as regiões.
Da mesma forma, na ausência de uma política de armazenamento de mensagens especificada, a sinalização enforceInTransit será determinada com base na política da organização Aplicar regiões em trânsito para mensagens do Pub/Sub. Para mais informações sobre essa política da organização, consulte Restrições da política da organização.
Se você especificar uma política de armazenamento de mensagens ao criar um tópico, essa política poderá conter apenas as regiões permitidas pela política da organização Restrição de localização de recursos em vigor. Quando nenhuma política da organização estiver em vigor, a política de armazenamento de mensagens poderá conter qualquer região.

Políticas de armazenamento de mensagens para tópicos existentes

Quando uma política da organização é atualizada, as alterações não se propagam automaticamente para tópicos existentes. Desse modo, a política de armazenamento de mensagens de um tópico existente pode ficar fora de sincronia com a política da organização mais recente. Para mais informações, consulte Gerenciar diferenças entre políticas de tópicos e da organização.
Quando a política de armazenamento de mensagens de um tópico é atualizada, as alterações não são propagadas para mensagens já publicadas. As mensagens já armazenadas com base em uma política antiga não são movidas para ficarem consistentes com a nova política. Em vez disso, as alterações se aplicam somente às mensagens publicadas após a atualização.

Exceções

A política especifica uma lista de nomes de regiões permitidas do Google Cloud. Dessa maneira, os seguintes itens não são compatíveis:

Listas de exclusão
Zonas ou locais multirregionais

Se você publicar uma mensagem com uma chave de ordem e a política de armazenamento de mensagens excluir a região mais próxima, o serviço Pub/Sub retornará um erro.

Configurar políticas de armazenamento de mensagens

Há duas maneiras de configurar políticas de armazenamento de mensagens para tópicos, por exemplo:

Defina uma política de armazenamento de mensagens usando uma política da organização.
Configure uma política de armazenamento de mensagens ao criar um tópico.

Definir uma política de armazenamento de mensagens usando uma política da organização

Console

Para configurar uma política de armazenamento de mensagens que se aplique a vários tópicos, defina uma política da organização para Restrição de local de recursos.

Acesse a página Políticas da organização no console do Identity and Access Management.

Acessar as políticas da organização
Selecione o nó da hierarquia de recursos (organização, pasta ou projeto) em que você quer definir uma política da organização.
No filtro, insira Restrição de local de recursos.
Clique em Google Cloud - Restrição de local de recursos.
Clique em EDITAR.
Adicione ou remova regiões conforme necessário.

Todos os novos tópicos que você criar herdam essas configurações. As alterações não se propagam automaticamente para os tópicos atuais. Para atualizar os tópicos atuais, execute uma operação de atualização.

Para mais informações sobre as políticas da organização, consulte Gerenciar recursos do Google Cloud.

Configurar uma política de armazenamento de mensagens ao criar um tópico

Console

Ao usar o console do Google Cloud, não é possível configurar uma política de armazenamento de mensagens ao criar um tópico. Em vez disso, todos os novos tópicos herdam automaticamente a política da organização Restrição de local de recursos.

No entanto, depois de criar um tópico, é possível alterar a política de armazenamento de mensagens dele no console com uma operação de atualização.

CLI da gcloud

Para criar um tópico com uma política de armazenamento de mensagens específica, use o comando gcloud pubsub topics create com a sinalização --message-storage-policy-allowed-regions:

gcloud pubsub topics create TOPIC_ID \
    --message-storage-policy-allowed-regions=REGION1, REGION2

Substitua:

TOPIC_ID: o ID ou nome do novo tópico.
REGION1, REGION2: uma lista separada por vírgulas de regiões compatíveis do Google Cloud.

REST

Para criar um tópico com uma política de armazenamento de mensagens, use o método projects.topics.create.

A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization. Para conseguir um token de acesso para o Application Default Credentials: gcloud auth application-default print-access-token.

 POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
 Authorization: Bearer $(gcloud auth application-default print-access-token)
 Content-Type: application/json --data @response-body.json

Especifique os campos a seguir no corpo da solicitação:

{
  "name": "projects/PROJECT_ID/topics/TOPIC_ID",
  "messageStoragePolicy": {
    "allowedPersistenceRegions": ["REGION"],
    "enforceInTransit": true
  }
}

Em que:

PROJECT_ID é o ID do projeto;
TOPIC_ID é o ID do tópico.
REGION é a região especificada.

Exemplo de resposta:

{
  "name": "projects/PROJECT_ID/topics/TOPIC_ID",
  "messageStoragePolicy": {
    "allowedPersistenceRegions": [
      "REGION"
    ],
    "enforceInTransit": true
  }
}

Consulte as seguintes referências de API para mais informações sobre como configurar políticas de armazenamento de mensagens.

Atualizar políticas de armazenamento de mensagens

Console

No console do Google Cloud, abra a página Detalhes do tópico.

Acessar os detalhes do tema
Selecione um tópico para atualizar.

Você pode selecionar vários temas.
No Painel de informações, selecione a guia Política de armazenamento.

Este painel pode estar recolhido por padrão. Se estiver recolhido, clique em Mostrar painel de informações.
Marque ou desmarque quantas regiões forem necessárias.
Clique em Atualizar.

CLI da gcloud

Para enviar por push a política de armazenamento de mensagens definida na política de Restrição de local de recursos da organização para um tópico, execute o seguinte comando gcloud pubsub topics update:

gcloud pubsub topics update TOPIC_ID \
    --recompute-message-storage-policy

Para atualizar a política de armazenamento de mensagens de um tópico com regiões específicas, execute o comando gcloud pubsub topics update com a sinalização --message-storage-policy-allowed-regions:

gcloud pubsub topics update TOPIC_ID \
    --message-storage-policy-allowed-regions=REGION1, REGION2

Substitua:

TOPIC_ID: o ID do tema que você está atualizando.
REGION1, REGION2: uma lista separada por vírgulas de regiões compatíveis do Google Cloud.

REST

Para atualizar um tópico com uma política de armazenamento de mensagens, use o método projects.topics.patch.

 PATCH https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
 Authorization: Bearer $(gcloud auth application-default print-access-token)
 Content-Type: application/json --data @response-body.json

Especifique os campos a seguir no corpo da solicitação:

{
  "name": "projects/PROJECT_ID/topics/TOPIC_ID",
  "messageStoragePolicy": {
    "allowedPersistenceRegions": ["REGION"], // Replace with your required region
    "enforceInTransit": true
  }
}

Em que:

PROJECT_ID é o ID do projeto;
TOPIC_ID é o ID do tópico.
REGION é a região especificada.

Exemplo de resposta:

{
  "name": "projects/PROJECT_ID/topics/TOPIC_ID",
  "messageStoragePolicy": {
    "allowedPersistenceRegions": [
      "REGION"
    ],
    "enforceInTransit": true
  }
}

Consulte as seguintes referências de API para mais informações sobre como atualizar políticas de armazenamento de mensagens.

Gerenciar diferenças entre políticas de tópicos e da organização

Conferir as diferenças entre as políticas da organização e de tópicos

Console

O console do Google Cloud mostra as diferenças entre a política da organização e as políticas de armazenamento de mensagens de tópicos individuais.

Para ver se algum tópico está fora de sincronia com a política da organização:

Acesse a página Detalhes do tema.

Acessar os detalhes do tema
Selecione um tópico.
No Painel de informações, selecione a guia Política de armazenamento.

Este painel pode estar recolhido por padrão. Se estiver recolhido, clique em Mostrar painel de informações.

Suas políticas de armazenamento são mostradas no painel, bem como todas as diferenças entre políticas de organização e de tópico.

CLI da gcloud

Para examinar a política atual atribuída a um tópico, execute o seguinte comando:

gcloud pubsub topics describe TOPIC_ID

Substitua:

TOPIC_ID: o ID do tópico que você está examinando.

Resolver diferenças entre políticas de tópicos e da organização

Console

No console do Google Cloud, abra a página Detalhes do tópico.

Ir para o Pub/Sub
Selecione um tópico.
No Painel de informações, selecione a guia Política de armazenamento.

Este painel pode estar recolhido por padrão. Se estiver recolhido, clique em Mostrar painel de informações.

Suas políticas de armazenamento são mostradas no painel com as discrepâncias.

Se houver discrepâncias, o painel de informações exibirá três opções para sincronizar a política de armazenamento do tópico com a da organização, incluindo:
- Os tópicos permitem o armazenamento em locais não permitidos.
  
  Atualize para permitir o armazenamento apenas em locais permitidos pela sua política.
- O tópico não permite o armazenamento em alguns locais permitidos.
  
  Atualize para permitir o armazenamento em qualquer lugar permitido pela sua política.
- Os temas estão desatualizados e têm locais permitidos e não permitidos.
  
  Atualize para permitir o armazenamento em um lugar permitido pela sua política.
Selecione a opção adequada para resolver os problemas.
Clique em Atualizar tópico.

A caixa de diálogo Sincronizar com a política de armazenamento da organização é aberta.
Clique em Atualizar tópico.

Monitoramento e solução de problemas

Para ajudar você a entender onde os dados da mensagem são armazenados, o Pub/Sub oferece métricas detalhadas por cada região do Google Cloud.

Você pode usar essas métricas para:

entender como seus dados são distribuídos em todo o mundo;
otimizar o local de implantação de editores e assinantes com base nesses dados.

Métricas de armazenamento de mensagens

Contagens de mensagens armazenadas não confirmadas:

subscription/num_unacked_messages_by_region

Volume de dados armazenados:

subscription/unacked_bytes_by_region

Idade da mensagem mais antiga:

subscription/oldest_unacked_message_age_by_region

Métricas análogas estão disponíveis para tópicos e snapshots. Além disso, as métricas correspondentes estão disponíveis para mensagens confirmadas que são retidas opcionalmente para repetição. Exemplo:

subscription/num_retained_acked_messages_by_region

Consequências de desempenho e disponibilidade

A política de armazenamento de mensagens não afeta o SLA geral, mas introduz uma compensação entre disponibilidade e controle quando editores ou assinantes são executados fora do Google Cloud ou em regiões não permitidas pela política. Os usuários que executam clientes editor no conjunto de regiões permitido pela política de armazenamento de mensagens não percebem alterações na latência ou na disponibilidade do serviço.

Para entender essas compensações, vale a pena considerar como as solicitações de publicação são encaminhadas. Geralmente, o Pub/Sub tenta armazenar as mensagens o mais próximo possível da origem da solicitação. As solicitações originadas no Google Cloud são, em regra, vinculadas às instâncias do Pub/Sub na mesma região. Se um editor estiver localizado em uma única região, adicionar mais regiões à política de armazenamento de mensagens não aumentará a disponibilidade. Ao publicar de fora do Google Cloud, uma camada adicional de roteamento é envolvida para enviar a solicitação a uma região próxima do Google Cloud em que o serviço do Pub/Sub está disponível.

Considere uma política de armazenamento de mensagens que permita apenas a região us-central1.

Um cliente editor em execução em us-east1 emite uma solicitação Publish.
A solicitação é roteada para um servidor Pub/Sub em us-east1.
Em vez de armazenar os dados em us-east1, a solicitação é roteada para a região mais próxima permitida pela política de armazenamento de mensagens, que é us-central1.
O Pub/Sub armazena as mensagens publicadas em us-central1 e as encaminha para os assinantes a partir desse local.

Esse mecanismo tem implicações na latência da solicitação e na disponibilidade geral do sistema. Como a solicitação transfere mais links de rede, a conclusão leva mais tempo e tem uma chance relativamente maior de falha. Isso também significa que os assinantes podem ver a mensagem um pouco mais tarde, porque ela precisa viajar até a região permitida mais próxima antes de ser enviada. Se a política permitir uma única região, mas seus aplicativos editores forem executados em várias regiões, o aplicativo distribuído ficará tão disponível quanto a única região permitida.

A seguir

Consulte Visão geral das APIs Pub/Sub para informações sobre como usar endpoints globais ou locais.