Esta página foi traduzida pela API Cloud Translation.
Switch to English

Como monitorar mudanças de recursos

Esta página explica como criar e gerenciar feeds em um projeto.

Visão geral

Para receber notificações em tempo real sobre alterações de recursos e políticas, crie e inscreva-se em um feed. Ao configurar o feed, é possível especificar que você quer monitorar as alterações dos tipos de recurso compatíveis, políticas de IAM, políticas de acesso e políticas da organização em uma organização, pasta ou para recursos específicos. Além disso, é possível adicionar condições ao seu feed para receber notificações apenas para determinados tipos de alteração em um recurso. Depois de configurar seu feed, você receberá notificações imediatamente sempre que os recursos especificados forem alterados, enviados por meio do Pub/Sub (formatado como um TemporalAsset). As notificações em tempo real se conectam às suas cargas de trabalho atuais. Com esta funcionalidade, é possível mesclar ações, como criar uma Função do Cloud para reverter uma alteração de recurso depois de detectada.

Antes de começar

  1. Ative a API Cloud Asset no projeto.

  2. Crie uma nova conta de serviço se ainda não tiver uma no projeto.

  3. Conceda permissão à conta de serviço para chamar a API em feeds em tempo real. As seguintes permissões são necessárias para cada operação:

    Permissão Descrição
    cloudasset.feeds.create e cloudasset.assets.exportResource Criar feeds
    cloudasset.feeds.update e cloudasset.assets.exportResource Atualizar feeds
    cloudasset.feeds.delete Excluir feeds
    cloudasset.feeds.get Acessar feeds
    cloudasset.feeds.list Listar feeds

    A concessão do papel de Proprietário de recursos do Cloud (roles/cloudasset.owner) à sua conta de serviço concede todas as permissões relacionadas à API Cloud Asset, incluindo as permissões listadas na tabela anterior. Para mais informações sobre papéis e permissões, consulte Noções básicas sobre papéis.

  4. Crie um tópico do Pub/Sub se você não tiver um tópico do Pub/Sub atual. Verifique se service-PROJECT_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com tem a permissão pubsub.topics.publish no tópico, em que PROJECT_NUMBER é o número do projeto com a API Cloud Asset ativada da qual você pretende criar o feed. Por padrão, essa conta de serviço tem a permissão pubsub.topics.publish em todos os tópicos neste projeto habilitado com a API Cloud Asset.

    A conta de serviço será criada ao chamar a API uma vez. Se preferir, use o seguinte comando:

      gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
    

Configurar o ambiente

GCLOUD

  1. Instale o SDK do Cloud no cliente local, se o SDK do Cloud não estiver instalado.

  2. Se você tiver o SDK do Cloud instalado, atualize todos os componentes instalados para a versão mais recente.

  3. Ative a API Resource Manager para o projeto.

API

  1. Acesse a página Criar uma instância e selecione a conta de serviço no seu projeto para configurar uma nova instância de VM do Compute Engine.

  2. Em Escopos de acesso, selecione Permitir acesso total a todas as APIs do Cloud:

  3. Inicie a instância clicando em Criar.

  4. Acesse a página Instâncias de VMs.

  5. Abra um cliente SSH Web conectado à instância clicando em SSH ao lado da listagem de instâncias.

  6. No cliente SSH Web, gere um token de autenticação para a conta de serviço com a chamada a seguir.

    TOKEN=$(gcloud auth application-default print-access-token)
    

As seguintes chamadas de API pressupõem que você esteja criando e gerenciando feeds em um projeto. Se você quiser criar e gerenciar feeds para uma organização ou uma pasta, troque /projects/PROJECT_NUMBER/ por /organizations/ORGANIZATION_NUMBER/ ou /folders/FOLDER_NUMBER/.

Como criar um feed

É possível criar até 200 feeds em um recurso. Esse limite se aplica somente aos feeds que seguem logo esse recurso e não conta os feeds dos filhos. Por exemplo, se você tiver 10 projetos em uma organização, cada projeto pode ter até 200 feeds, e a organização também pode ter até 200 feeds.

Para criar um feed, você pode usar uma das seguintes opções:

  • FEED_ID é o identificador exclusivo do feed de recurso atribuído pelo cliente.
  • ASSET_NAME é uma lista de nomes completos de recursos de que você quer receber notificações de alteração.
  • ASSET_TYPE é uma lista de tipos de recurso para os quais você quer receber notificações de alteração.
  • CONTENT_TYPE é o tipo de conteúdo do recurso que você quer receber notificações de mudanças.
  • TOPIC_NAME é o nome do tópico do Pub/Sub para publicar notificações.
  • CONDITION_TITLE é o título da condição a ser aplicada no feed.
  • CONDITION_DESCRIPTION é a descrição da condição a ser aplicada no feed.
  • CONDITION_EXPRESSION é a expressão da condição a ser aplicada no feed.

GCLOUD

Para criar um feed usando o comando gcloud asset feeds create para projetos, pastas e organizações:

  • Projetos:

    gcloud asset feeds create FEED_ID --project=PROJECT_ID --asset-names="ASSET_NAME"
    --content-type=CONTENT_TYPE --asset-types="ASSET_TYPE"
    --pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE"
    --condition-description="CONDITION_DESCRIPTION"
    --condition-expression="CONDITION_EXPRESSION"
    

  • Pastas:

    gcloud asset feeds create FEED_ID --folder=FOLDER_ID --asset-names="ASSET_NAME"
    --content-type=CONTENT_TYPE --asset-types="ASSET_TYPE"
    --pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE"
    --condition-description="CONDITION_DESCRIPTION"
    --condition-expression="CONDITION_EXPRESSION"
    

  • Organizações:

    gcloud asset feeds create FEED_ID --organization=ORGANIZATION_ID --asset-names="ASSET_NAME"
    --content-type=CONTENT_TYPE --asset-types="ASSET_TYPE"
    --pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE"
    --condition-description="CONDITION_DESCRIPTION"
    --condition-expression="CONDITION_EXPRESSION"
    

API

Para criar um feed usando a API feeds.create() para projetos, pastas e organizações:

  • Projetos:
    curl -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" -X POST \
      -d '{"feedId": "FEED_ID",
           "feed": { "assetNames": ["ASSET_NAME"],
           "assetTypes": ["ASSET_TYPE"], "contentType": "CONTENT_TYPE",
           "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}},
           "condition": {"title": "CONDITION_TITLE",
           "description": "CONDITION_DESCRIPTION",
           "expression": "CONDITION_EXPRESSION"}}}' \
      https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds
    
  • Pastas:
    curl -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" -X POST \
      -d '{"feedId": "FEED_ID",
           "feed": { "assetNames": ["ASSET_NAME"],
           "assetTypes": ["ASSET_TYPE"], "contentType": "CONTENT_TYPE",
           "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}},
           "condition": {"title": "CONDITION_TITLE",
           "description": "CONDITION_DESCRIPTION",
           "expression": "CONDITION_EXPRESSION"}}}' \
      https://cloudasset.googleapis.com/v1/folders/FOLDER_NUMBER/feeds
    
  • Organizações:
    curl -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" -X POST \
      -d '{"feedId": "FEED_ID",
           "feed": { "assetNames": ["ASSET_NAME"],
           "assetTypes": ["ASSET_TYPE"], "contentType": "CONTENT_TYPE",
           "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}},
           "condition": {"title": "CONDITION_TITLE",
           "description": "CONDITION_DESCRIPTION",
           "expression": "CONDITION_EXPRESSION"}}}' \
      https://cloudasset.googleapis.com/v1/organizations/ORGANIZATION_NUMBER/feeds
    

O Inventário de recursos do Cloud configura uma notificação em qualquer recurso que corresponda a pelo menos um dos parâmetros ASSET do feed E também corresponde à expressão condicional, se especificado. Por exemplo, se você especificar ASSET_TYPE, ASSET_NAME e CONDITION_EXPRESSION, receberá notificações sobre os recursos que correspondem a ASSET_TYPE ou ASSET_NAME e satisfazem CONDITION_EXPRESSION.

Os seguintes comandos criam notificações do tópico quick_start_topic Pub/Sub quando o conteúdo é alterado no bucket quick_start_bucket do Cloud Storage ou em qualquer tabela do BigQuery:

GCLOUD

 gcloud asset feeds create quick_start_feed --project=PROJECT_ID --asset-names="//storage.googleapis.com/quick_start_bucket"
  --content-type=resource --asset-types="bigquery.googleapis.com/Table"
  --pubsub-topic="projects/PROJECT_ID/topics/quick_start_topic"
 

API

 curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -X POST \
  -d '{"feedId": "quick_start_feed",
       "feed": { "assetNames": ["storage.googleapis.com/quick_start_bucket"],
       "assetTypes": ["bigquery.googleapis.com/Table"],
       "contentType": "RESOURCE",
       "feedOutputConfig": {"pubsubDestination": {"topic":"projects/PROJECT_ID/topics/quick_start_topic"}}}}' \
        https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds
 

As expressões regulares também são compatíveis com o campo ASSET_TYPE. Os comandos a seguir criam notificações do tópico quick_start_topic do Pub/Sub quando o conteúdo muda nos recursos em que o tipo de recurso começa com "compute.googleapis.com". Consulte RE2 para ver todas as sintaxes de expressão regular compatíveis.

GCLOUD

 gcloud asset feeds create quick_start_feed --project=PROJECT_ID
  --content-type=resource --asset-types="compute.googleapis.com.*"
  --pubsub-topic="projects/PROJECT_ID/topics/quick_start_topic"
 

API

 curl -H "Authorization: Bearer $TOKEN" 
-H "Content-Type: application/json" -X POST
-d '{"feedId": "quick_start_feed", "feed": { "assetTypes": ["compute.googleapis.com.*"], "contentType": "RESOURCE", "feedOutputConfig": {"pubsubDestination": {"topic":"projects/PROJECT_ID/topics/quick_start_topic"}}}}'
https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds

Para ver o feed que você criou, use o seguinte comando:

GCLOUD

 gcloud asset feeds describe FEED_ID --project=PROJECT_ID
 

API

 curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds/FEED_ID
 

O feed é retornado no seguinte formato, em que FULL_NAME_FEED é o identificador do feed junto com o pai do recurso:

{
  "name": "FULL_NAME_FEED",
  "assetTypes": ["ASSET_TYPES"],
  "assetNames": ["ASSET_NAMES"],
  "contentType": "CONTENT_TYPES",
  "feedOutputConfig": {
    "pubsubDestination": {
      "topic": "TOPIC_NAME"
    }
  },
  "condition": {
    "title": "CONDITION_TITLE",
    "description": "CONDITION_DESCRIPTION",
    "expression": "CONDITION_EXPRESSION"
  }
}

Como receber atualizações

Depois de criar um feed, assine as atualizações do tópico Pub/Sub especificado no feed. Um novo feed pode levar até cinco minutos para começar a enviar notificações. Uma notificação é enviada para cada alteração em um recurso que corresponde a assetNames ou assetTypes e satisfaz condition no feed.

Para saber mais sobre o Pub/Sub, consulte o guia do Pub/Sub.

Como atualizar um feed

Para atualizar os atributos de um feed, você precisa especificar o caminho do atributo no update_mask e o valor desse atributo. O comando a seguir atualiza o valor assetNames e topic de um feed em um projeto.

GCLOUD

gcloud asset feeds update FEED_ID --project=PROJECT_ID --add-asset-names=ASSET_NAME
   --pubsub-topic="TOPIC"

API

 curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -X PATCH \
  -d '{"feed": {"assetNames": [ASSET_NAME], "feedOutputConfig": {"pubsubDestination": {"topic":TOPIC}}},
       "update_mask": {"paths": ["asset_names", "feed_output_config.pubsub_destination.topic"]}}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds/FEED_ID
 

Como excluir um feed

Se você não quiser mais receber notificações sobre alterações de recurso, use o seguinte comando para excluir um feed em um projeto.

GCLOUD

gcloud asset feeds delete FEED_ID --project=PROJECT_ID

API

 curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -X DELETE \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds/FEED_ID
 

Como adicionar uma condição a um feed

Para visualizar apenas determinado tipo de alteração de um determinado recurso, você pode adicionar uma condição ao seu feed.

O objeto condition é opcional. Se um feed não tiver um objeto condition, o destino configurado receberá todas as alterações nos recursos.

O objeto condition tem a seguinte estrutura:

"condition": {
    "title": ...
    "description": ...
    "expression": ...
}

Title e description são opcionais. Esses campos podem ajudar a identificar e descrever a condição.

O campo expression define a expressão usada para avaliar a notificação em Common Expression Language (CEL). A expressão condicional pode conter várias instruções, e as instruções são combinadas com operadores lógicos, seguindo a especificação da linguagem CEL.

Como usar CEL

Common Expression Language (CEL) é a linguagem usada para especificar uma condição de feed. Ela é personalizada para expressar expressões lógicas baseadas em atributos. Para saber mais, veja a especificação da CEL e a respectiva definição de linguagem.

Em uma condição de feed, o CEL é usado para tomar decisões booleanas com base em dados do atributo. Uma expressão condicional consiste em uma ou mais instruções que são unidas usando operadores lógicos (&&, || ou !). Cada instrução expressa uma regra de controle baseada em atributo que se aplica ao TemporalAsset para determinar se a notificação é enviada.

Os seguintes recursos de CEL são os mais importantes para as condições do feed:

  • Variáveis: condições usam variáveis para expressar um determinado atributo, como temporal_asset.deleted (do tipo booleano) ou temporal_asset.asset.name (do tipo String). Essas variáveis são preenchidas com valores com base no contexto no ambiente de execução.
  • Operadores: todos os tipos de dados, como String, são compatíveis com um conjunto de operadores que podem ser usados para criar uma expressão lógica. Geralmente, os operadores são usados para comparar o valor contido em uma variável com um valor literal, como temporal_asset.asset.name == "//cloudresourcemanager.googleapis.com/projects/12345". Neste exemplo, se o valor de entrada de temporal_asset.asset.name for //cloudresourcemanager.googleapis.com/projects/12345, a expressão avalia como true.
  • Funções: uma função é um operador composto de tipos de dados compatíveis com operações mais complexas. Em expressões condicionais, existem funções predefinidas que podem ser usadas em conjunto com um determinado tipo de dados. Por exemplo, temporal_asset.asset.name.contains("keyword") usa uma string que contém uma função e avalia para true se o valor de temporal_asset.asset.name contém "keyword".
  • Operadores lógicos: as condições são compatíveis com três operadores lógicos que podem ser usados para criar expressões lógicas complexas a partir de instruções de expressões simples: &&, || e !. Esses operadores lógicos possibilitam o uso de muitas variáveis de entrada em uma expressão condicional. Por exemplo: temporal_asset.deleted && temporal_asset.window.start_time.getFullYear() > 2020 une duas instruções simples e exige que ambas sejam atendidas para produzir um resultado geral de avaliação true.

Para mais informações sobre os recursos de CEL, consulte a definição de linguagem.

Como usar variáveis de condição

As variáveis de condição permitem que você crie condições em atributos diferentes. As variáveis de condição compatíveis são:

  • serial_asset: a alteração atual de recurso no formato TemporalAsset. Se a condição for avaliada como verdadeira, o TemporalAsset será enviado ao destino configurado.

Exemplo de expressões condicionais

A expressão de condição a seguir envia notificações sobre eventos de criação:

!temporal_asset.deleted &&
temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST

A expressão de condição a seguir envia notificações para os recursos que estão localizados nas pastas 12345 e 23456:

"folders/12345" in temporal_asset.asset.ancestors ||
"folders/23456" in temporal_asset.asset.ancestors

A expressão de condição a seguir enviará notificações quando novas regras permitidas forem adicionadas aos firewalls, supondo que asset_type já esteja definido como compute.googleapis.com/Firewall no feed.

size(temporal_asset.asset.resource.data.allowed) >
size(temporal_asset.prior_asset.resource.data.allowed)

A expressão de condição a seguir envia notificações para instâncias de VM com o tipo de máquina n1-standard-1, supondo que asset_type já esteja definido como compute.googleapis.com/Instance no feed.

temporal_asset.asset.resource.data.machineType.endsWith("/machineTypes/n1-standard-1")

A expressão de condição a seguir envia notificações para buckets de armazenamento com qualquer política de IAM para allUsers, supondo que asset_type esteja definido como storage.googleapis.com/Bucket e content_type esteja definido como IAM_POLICY no feed.

temporal_asset.asset.iam_policy.bindings.exists(b, b.members.exists(m, m == "allUsers"))

Limitações conhecidas

  • A maioria dos nomes de variáveis em expressões de condição é representada em snake_case. A única exceção são os nomes de variáveis dos subcampos de data no objeto Recurso, representados em camelCase.

  • As expressões de condição têm um limite de 1.000 caracteres.

  • Algumas validações em expressões de condição são realizadas durante a criação/atualização do feed. No entanto, essas validações não são abrangentes, especialmente para condições definidas no campo temporal_asset.asset.resource.data, que tem tipo dinâmico. Recomendamos condições de feed simples com o asset_type adequado especificado no feed. Se ocorrerem erros de validação durante o tempo de avaliação, a notificação não será enviada e os erros serão registrados. Saiba mais sobre como visualizar registros.

  • Para tipos dinâmicos em temporal_asset.asset.resource.data, as condições especificadas em campos ausentes acionam erros de ambiente de execução, e as notificações não são publicadas. Por exemplo, para a condição temporal_asset.asset.resource.data.name != "my_name", se o campo name estiver ausente em uma atualização, a avaliação falhará e você não receberá notificações. Se sua condição funcionar apenas na presença de determinados campos, verifique a existência na condição para garantir que ela seja avaliada corretamente.

  • Os tipos de enumeração estáticos podem ser representados como nomes de caminho totalmente qualificados ou inteiros brutos. Por exemplo, as expressões a seguir são válidas para prior_asset_state:

    temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST
    

    e

    temporal_asset.prior_asset_state == 3
    

    Os tipos de enumeração dinâmica em temporal_asset.asset.resource.data são representados como strings brutas. Por exemplo, a expressão a seguir é válida para o tipo de recurso cloudresourcemanager.googleapis.com/Project:

    temporal_asset.asset.resource.data.lifecycleState == "ACTIVE"
    

Solução de problemas

Nesta seção, mostramos como solucionar problemas comuns.

Falha ao criar ou atualizar um feed

Se você não criar ou atualizar um feed com a mensagem de erro Fail to use [TOPIC_NAME] as feed output destination, significa que há um problema ao publicar a mensagem no tópico especificado no destino de saída do feed. Para resolver o problema:

  • Verifique se você especificou o nome do tópico correto
  • Verifique se a conta de serviço (service-[PROJECT_NUMBER]@gcp-sa-cloudasset.iam.gserviceaccount.com) tem a permissão pubsub.topics.publish no tópico, em que [PROJECT_NUMBER] é o número do projeto habilitado para o Inventário de recursos do Cloud que você planeja criar o feed.

Falha ao receber atualizações de recursos ou atualizações de políticas do IAM

Se você não estiver recebendo notificações de atualização de recursos ou de políticas do IAM, verifique as configurações a seguir.

  • Verifique se os metadados foram alterados nos seus recursos. O feed em tempo real só envia atualizações quando os metadados dos tipos de recursos compatíveis são alterados. Operações como o upload de um novo arquivo para o bucket do Cloud Storage não acionam uma alteração nos metadados.
  • Verifique se os recursos atendem a um dos critérios especificados no feed, que são nomes e tipos de recursos.
  • Verifique se há erros ao publicar atualizações no tópico.

Uso do Cloud Logging

Nesta seção, descrevemos como configurar e visualizar o Logging para feeds em tempo real do Inventário de recursos do Cloud.

Quando os feeds em tempo real não enviam recursos ou atualizações de política do IAM por meio do Pub/Sub, o Inventário de recursos do Cloud registra o status de erro e a mensagem por meio do Logging. A geração de registros é ativada por padrão. Saiba mais sobre os preços do pacote de operações do Google Cloud.

Como visualizar os registros do pacote de operações do Google Cloud

Para visualizar os registros, acesse o Visualizador de registros.

A geração de registros de feed em tempo real é indexada por um tópico do Pub/Sub. Para ver todos os registros, selecione Tópico do Cloud Pub/Sub > Todos os IDs de tópicos no primeiro menu suspenso. Para ver os registros do tópico especificado no seu feed, selecione um único ID do tópico da lista.

A codificação UTF-8 é aplicada aos campos de registro. Os caracteres que não forem UTF-8 serão substituídos por pontos de interrogação.

Informações registradas

As entradas de registro do feed em tempo real contêm os seguintes tipos de informações:

  • Informações gerais exibidas na maioria dos registros do Google Cloud, como gravidade, ID do projeto, número do projeto ou carimbo de data/hora;
  • Campos de registro de feed em tempo real em jsonPayload, que contêm nome de recurso, configuração de saída do feed, status de erro ao publicar recursos ou atualizações de política do IAM.

A tabela a seguir mostra quais tipos de informações cada campo contém.

Campo Tipo e descrição
name

string

Nome completo do feed. O formato é um dos seguintes:
  • projects/{project_number}/feeds/{feed_id}
  • folders/{folder_number}/feeds/{feed_id}
  • organizations/{organization_number}/feeds/{client-assigned_feed_identifier}
asset_name

string

Nome completo do recurso para receber atualizações. Por exemplo: //compute.googleapis.com/projects/my_project_123/zones/zone1/instances/instance1

Consulte Nomes de recursos para mais informações.

feed_output_config

FeedOutputConfig

Configuração de saída do feed que define onde as atualizações de recursos serão publicadas.

condition

Expr

Condição do feed que determina se uma atualização de recurso será publicada.

error_status

Status

Status quando há falha na publicação de atualizações de recursos em um feed.