Configura receptores agregados

En este documento, se describe cómo crear receptores agregados. Para obtener información sobre cómo administrar receptores existentes, consulta Administra receptores.

Los receptores agregados combinan y enrutan las entradas de registro de los recursos de Google Cloud contenidos por una organización, carpeta o cuenta de facturación. Por ejemplo, puedes agregar y enrutar entradas de registro de auditoría desde las carpetas de una organización a un bucket de Cloud Storage.

Sin la función de receptor agregado, los receptores se limitan a enrutar las entradas de registro del recurso exacto en el que se creó el receptor: un proyecto de Google Cloud, una organización, una carpeta o una cuenta de facturación.

Para crear un receptor agregado, puedes usar la API de Cloud Logging o la herramienta de línea de comandos de gcloud. Los receptores agregados no se pueden crear mediante Google Cloud Console. Puedes usar Google Cloud Console solo para crear receptores a nivel de proyecto (no agregados). Para crear receptores en proyectos de Cloud, consulta Configura receptores.

Para obtener una descripción general más amplia de los receptores, consulta Descripción general del enrutamiento y el almacenamiento: receptores.

Destinos admitidos

Puedes usar receptores agregados para enrutar registros dentro de las mismas organizaciones, carpetas o cuentas de facturación o entre ellas en los siguientes destinos:

  • Cloud Storage: archivos JSON almacenados en depósitos de Cloud Storage
  • Pub/Sub: Mensajes JSON entregados a temas de Pub/Sub Admite integraciones de terceros, como Splunk, con Logging.
  • BigQuery: tablas creadas en conjuntos de datos de BigQuery
  • Otro bucket de Cloud Logging: las entradas de registro que se encuentran en los buckets de registro de Cloud Logging

Antes de comenzar

Antes de crear un receptor, verifica lo siguiente:

  • Tienes un recurso con registros que puedes ver en el Explorador de registros.

  • Tienes una de las siguientes funciones de IAM para la organización, la carpeta o la cuenta de facturación de Google Cloud desde la que envías registros.

    • Propietario (roles/owner)
    • Administrador de Logging (roles/logging.admin)
    • Escritor de configuración de registros (roles/logging.configWriter)

    Los permisos contenidos en estas funciones te permiten crear, borrar o modificar receptores. Para obtener información sobre la configuración de las funciones de IAM, consulta la Guía de control de acceso de Logging.

  • Tienes un recurso en un destino compatible o tienes la capacidad de crear uno.

    El destino de los receptores de registros debe crearse antes del receptor, a través de la herramienta de línea de comandos de gcloud, Cloud Console o las API de Google Cloud. Puedes crear el destino en cualquier proyecto de Cloud en cualquier organización, pero debes asegurarte de que la cuenta de servicio del receptor tenga permisos para escribir en el destino.

Crea un receptor agregado

Para usar receptores agregados, debes crear un receptor en una organización, carpeta o cuenta de facturación de Google Cloud y establecer el parámetro includeChildren del receptor en True. Ese receptor puede enrutar entradas de registro de la organización, la cuenta de facturación o la carpeta, además de (de manera recurrente) desde cualquier carpeta, cuenta de facturación o proyecto de Cloud contenidos. Establece los filtros de inclusión y exclusión del receptor para especificar las entradas de registro que deseas enrutar a tu destino.

Puedes crear hasta 200 receptores por organización, cuenta de facturación o carpeta.

API

Para crear un receptor de registros, usa organizations.sinks.create, folders.sinks.create o billingAccounts.sinks.create en el API de Logging. Prepara los argumentos del método de la siguiente manera:

  1. Establece el parámetro parent para que sea la organización, la carpeta o la cuenta de facturación de Google Cloud en la que deseas crear el receptor. El superior debe ser uno de los siguientes:

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID
    • billingAccounts/BILLING_ACCOUNT_ID
  2. En el objeto LogSink en el cuerpo de la solicitud del método, haz lo siguiente:

    • Establece includeChildren en True.

    • Configura la propiedad filter. Ten en cuenta que la longitud de un filtro no puede superar los 20,000 caracteres.

      A fin de obtener algunos ejemplos de filtros útiles, consulta Crea filtros para receptores agregados.

    • Establece los campos LogSink restantes como lo harías para cualquier otro receptor. A fin de obtener más información, consulta Crea receptores.

  3. Llama a organizations.sinks.create, folders.sinks.create o billingAccounts.sinks.create para crear el receptor.

  4. Recuperar el nombre de la cuenta de servicio del campo writer_identity que muestra la respuesta de la API

  5. Otórgale permiso a esa cuenta de servicio para que escriba en el destino del receptor.

    Si no tienes permiso para realizar ese cambio en el destino del receptor, envía el nombre de la cuenta de servicio a alguien que pueda realizarlo por ti.

    A fin de obtener más información sobre cómo otorgar permisos de cuentas de servicio para recursos, consulta la sección Establece permisos de destino.

gcloud

Para crear un receptor de registros, usa el comando logging sinks create.

  1. Proporciona el nombre del receptor, el destino del receptor, el filtro y el ID de la carpeta, la cuenta de facturación o la organización.

    Por ejemplo, configura un receptor agregado a nivel de la carpeta de la siguiente manera:

    gcloud logging sinks create SINK_NAME \
    storage.googleapis.com/STORAGE_BUCKET_NAME --include-children \
    --folder=FOLDER_ID --log-filter="logName:activity"

    Notas:

    • Para crear un receptor a nivel de la organización, reemplaza --folder=FOLDER_ID por --organization=ORGANIZATION_ID. Para una cuenta de facturación, reemplaza --folder=FOLDER_ID por --billing-account=BILLING_ACCOUNT_ID.

    • Para que el receptor incluya todos los proyectos dentro de la organización, se debe establecer la marca --include-children, incluso cuando la marca --organizationse pasa a create. Cuando se establece en false (el valor predeterminado), un receptor solo enrutará los registros del recurso de host.

    • A fin de obtener algunos ejemplos de filtros útiles, consulta Crea filtros para receptores agregados.

  2. Recupera el nombre de la cuenta de servicio usado para crear el receptor del resultado del comando.

  3. Otorga permiso a esa cuenta de servicio para escribir en el destino del receptor.

    Si no tienes permiso para realizar ese cambio en el destino del receptor, envía el nombre de la cuenta de servicio a alguien que pueda realizarlo por ti.

    A fin de obtener más información sobre cómo otorgar permisos de cuentas de servicio para recursos, consulta la sección Establece permisos de destino.

Crea filtros para receptores agregados

Como cualquier receptor, tu receptor agregado contiene un filtro que selecciona entradas de registro individuales. A fin de obtener ejemplos de filtros que podrías usar para crear tu receptor agregado, consulta Consultas de muestra mediante el Explorador de registros.

A continuación, se presentan algunos ejemplos de comparaciones de consultas que son útiles cuando se usa la función de receptores agregados. Algunos ejemplos usan la siguiente notación:

  • : es el operador de la substring. No sustituyas el operador =.
  • ... representa cualquier comparación de filtro adicional.
  • Las variables se indican mediante texto de color. Reemplázalos con valores válidos.

Ten en cuenta que la longitud de un filtro no puede superar los 20,000 caracteres.

Para obtener más detalles sobre la sintaxis de filtrado, consulta Lenguaje de consulta de Logging.

Selecciona la fuente del registro

Para enrutar registros de organizaciones, carpetas o proyectos específicos de Cloud, usa una de las siguientes comparaciones de ejemplo:

logName:"projects/PROJECT_ID/logs/" AND ... 
logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ... 
logName:"folders/FOLDER_ID/logs/" AND ... 
logName:"organizations/ORGANIZATION_ID/logs/" AND ... 

Selecciona el recurso supervisado

Para enrutar registros desde solo un recurso supervisado específico en un proyecto de Cloud, usa varias comparaciones para especificar el recurso con exactitud:

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

Para obtener una lista de los tipos de recursos, consulta Tipos de recursos supervisados.

Selecciona una muestra de entradas de registro

Para enrutar una muestra aleatoria de entradas de registro, agrega la función integrada sample. Por ejemplo, para enrutar solo el diez por ciento de las entradas de registro que coincidan con tu filtro actual, usa esta adición:

sample(insertId, 0.10) AND ...

Para obtener más información, consulta la función sample.

Para obtener más información sobre los filtros de Cloud Logging, consulta Lenguaje de consulta de Logging.

Configura los permisos de destino

En esta sección, se describe cómo otorgar a Logging los permisos de administración de identidades y accesos para escribir registros en el destino de tu receptor. Para obtener una lista completa de las funciones y los permisos de Logging, consulta Control de acceso.

Cuando creas un receptor, Logging crea una cuenta de servicio nueva para él, denominada identidad de escritor única. El destino de tu receptor debe permitir que esta cuenta de servicio escriba entradas de registro. No puedes administrar esta cuenta de servicio directamente, ya que Cloud Logging es su propietario y administrador. La cuenta de servicio se borra si se borra el receptor.

A fin de enrutar los registros a un recurso protegido por un perímetro de servicio, debes agregar la cuenta de servicio para ese receptor de registros a un nivel de acceso y, luego, asignarla al servicio de destino. perímetro Esto no es necesario para los receptores a nivel de proyecto (no agregados). Para obtener más detalles, consulta Controles del servicio de VPC: Cloud Logging.

A fin de establecer permisos para que tu receptor se enrute a su destino, haz lo siguiente:

API

  1. Obtén la cuenta de servicio del campo writerIdentity en tu receptor; para ello, llama al método de la API organizations.sinks.get y folders.sinks.get. o billingAccounts.sinks.get.

    La cuenta de servicio se verá de la siguiente manera:

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
    
  2. Agrega la identidad de escritor del receptor nuevo a la lista de permisos del destino, lo que le otorga permiso para escribir en el destino.

    Si tienes acceso de Propietario al IAM de destino, agrega la cuenta de servicio al destino de la siguiente manera:

    • Para los destinos de Cloud Storage, agrega la identidad de escritor del receptor a tu bucket de Cloud Storage y asígnale la función de creador de objetos de almacenamiento.
    • Para los destinos de BigQuery, agrega la identidad de escritor del receptor a tu conjunto de datos y asígnale la función de editor de datos de BigQuery.
    • En Pub/Sub, incluido Splunk, agrega la identidad de escritor del receptor a tu tema y asígnale la función de publicador de Pub/Sub.
    • Para los destinos del bucket de Logging en diferentes proyectos de Cloud, agrega la identidad de escritor del receptor al bucket de registro de destino y otórgale el permiso roles/logging.bucketWriter.

    Si no tienes acceso de Propietario al destino del receptor, envía el nombre de la cuenta de servicio de la identidad de escritor a alguien que tenga esa capacidad. Esa persona debe seguir las instrucciones del paso anterior para agregar la identidad de escritor al destino del receptor.

gcloud

  1. Obtén la identidad de escritor del receptor nuevo, que es una dirección de correo electrónico:

  2. Obtén la cuenta de servicio del campo writerIdentity en tu receptor:

    gcloud logging sinks describe SINK_NAME
    

    La cuenta de servicio se verá de la siguiente manera:

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
    
  3. Si tienes acceso de Propietario al IAM de destino, agrega la cuenta de servicio al destino de la siguiente manera:

    • Para los destinos de Cloud Storage, agrega la identidad de escritor del receptor a tu bucket de Cloud Storage y asígnale la función de creador de objetos de almacenamiento.
    • Para los destinos de BigQuery, agrega la identidad de escritor del receptor a tu conjunto de datos y asígnale la función Editor de datos de BigQuery.
    • En Pub/Sub, incluido Splunk, agrega la identidad de escritor del receptor a tu tema y asígnale la función de publicador de Pub/Sub.
    • Para los destinos del bucket de Logging en diferentes proyectos de Cloud, agrega la identidad de escritor del receptor al bucket de registro de destino y otórgale el permiso roles/logging.bucketWriter.

    Si no tienes acceso de Propietario al destino del receptor, envía el nombre de la cuenta de servicio de la identidad de escritor a alguien que tenga esa capacidad. Esa persona debe seguir las instrucciones del paso anterior para agregar la identidad de escritor al destino del receptor.

    Por ejemplo, si enrutas registros entre depósitos de Logging en diferentes proyectos de Cloud, debes agregar roles/logging.bucketWriter a la cuenta de servicio de la siguiente manera:

    1. Obtén la política de administración de identidades y accesos para el proyecto de Cloud de destino y escríbela en un archivo local en formato JSON:

      gcloud projects get-iam-policy DESTINATION_PROJECT_ID --format json > output.json
      
    2. Agrega una condición de IAM que permita que la cuenta de servicio solo escriba en el destino que creaste. Por ejemplo:

      {
      "bindings": [
       {
         "members": [
           "user:username@gmail.com"
         ],
         "role": "roles/owner"
       },
       {
         "members": [
           "SERVICE_ACCOUNT"
         ],
         "role": "roles/logging.bucketWriter",
         "condition": {
             "title": "Bucket writer condition example",
             "description": "Grants logging.bucketWriter role to service account SERVICE_ACCOUNT used by log sink SINK_NAME",
             "expression":
               "resource.name.endsWith(\'locations/global/buckets/BUCKET_ID\')"
         }
       }
      ],
      "etag": "BwWd_6eERR4=",
      "version": 3
      }
    3. Actualiza la política de IAM:

      gcloud projects set-iam-policy DESTINATION_PROJECT_ID output.json
      

¿Qué sigue?