Configurar receptores agregados

En este documento, se describe cómo crear receptores agregados. A fin de obtener información sobre cómo administrar receptores existentes, consulta Configura y administra receptores.

Descripción general

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

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

Puedes crear receptores agregados para organizaciones y carpetas de Google Cloud. Debido a que ni los proyectos de Cloud ni las cuentas de facturación contienen recursos secundarios, no puedes crear receptores agregados para ellos.

Destinos admitidos

Puedes usar receptores agregados para enrutar los registros dentro de las mismas organizaciones y carpetas o entre ellas dentro de los siguientes destinos:

  • Cloud Storage: archivos JSON almacenados en buckets 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: entradas de registro alojadas en buckets de registro de Cloud Logging

Antes de comenzar

Antes de crear un receptor, asegúrate de lo siguiente:

  • Tienes una organización o una carpeta de Google Cloud con registros que puedes ver en el Explorador de registros.

  • Tienes una de las siguientes funciones de IAM para la organización o carpeta de Google Cloud desde la que enrutas los registros.

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

    Los permisos que contienen estas funciones te permiten crear, borrar o modificar receptores. Para obtener información sobre cómo configurar las funciones de IAM, consulta la Guía de control de acceso de Logging.

  • Tienes un recurso en un destino compatible o puedes crear uno.

    El destino de enrutamiento se debe crear antes del receptor, a través de la CLI de Google Cloud, Google Cloud Console o las API de Google Cloud. Puedes crear el destino en cualquier proyecto de Cloud de cualquier organización, pero debes asegurarte de que la cuenta de servicio del receptor tenga permisos para escribir en el destino.

Crear un receptor agregado

Para usar receptores agregados, debes crear un receptor en una organización o carpeta de Google Cloud y establecer el parámetro includeChildren del receptor en True. Ese receptor puede enrutar las entradas de registro desde la organización o carpeta, más (de forma recurrente) desde las carpetas contenidas, las cuentas de facturación o los proyectos de Cloud. Configura 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 o carpeta.

A fin de crear un receptor agregado para tu organización o carpeta, haz lo siguiente:

Console

  1. En Google Cloud Console, ve a la página Logging > Enrutador de registros.

    Ir al Enrutador de registros

  2. Selecciona una organización o carpeta existente.

  3. Seleccione Crear receptor.

  4. En el panel Detalles del receptor, ingresa los siguientes detalles:

    • Nombre del receptor: Proporciona un identificador para el receptor. Ten en cuenta que, después de crear el receptor, no puedes cambiar su nombre, pero puedes borrarlo y crear uno nuevo.

    • Descripción del receptor (opcional): Describe el propósito o caso de uso del receptor.

  5. En el panel Destino del receptor, selecciona el servicio y el destino del receptor:

    • Selecciona un servicio de receptor: Selecciona el servicio al que deseas enrutar los registros.

    Según el servicio que elijas, puedes elegir uno de los siguientes destinos:

    • Bucket de Cloud Logging: selecciona o crea un bucket de Logging.
    • Tabla de BigQuery: selecciona o crea el conjunto de datos particular para recibir los registros enrutados. También tienes la opción de usar tablas particionadas.
    • Bucket de Cloud Storage: Selecciona o crea el bucket de Cloud Storage en particular para recibir los registros enrutados.
    • Tema de Pub/Sub: selecciona o crea el tema en particular para recibir los registros enrutados.
    • Splunk: Selecciona el tema de Pub/Sub para tu servicio de Splunk.

      Por ejemplo, si tu destino de receptor es un conjunto de datos de BigQuery, el destino del receptor sería el siguiente:

      bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
      
  6. En el panel Elige registros para incluirlos en el receptor, haz lo siguiente:

    1. Selecciona Incluir los registros transferidos por este recurso y todos los recursos secundarios, lo que crea un receptor agregado.

    2. En el campo Crear filtro de inclusión, ingresa una expresión de filtros que coincida con las entradas de registro que deseas incluir. Si no configuras un filtro, todos los registros del recurso seleccionado se enrutarán al destino.

      Por ejemplo, puede que quieras compilar un filtro para enrutar todos los registros de acceso a los datos a un solo bucket de Logging. Este filtro se verá de la siguiente manera:

      LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")
      

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

    3. Para verificar que ingresaste el filtro correcto, selecciona Obtener vista previa de los registros. Se abrirá el Explorador de registros en una pestaña nueva con el filtro prepropagado.

  7. En el panel Elige registros para excluir del receptor, haz lo siguiente (opcional):

    1. En el campo Nombre del filtro de exclusión, ingresa un nombre.

    2. En el campo Crear un filtro de exclusión, ingresa una expresión de filtros que coincida con las entradas de registro que deseas excluir. También puedes usar la función sample para seleccionar una parte de las entradas de registro que quieres excluir.

    Puedes crear hasta 50 filtros de exclusión por receptor. Ten en cuenta que la longitud de un filtro no puede superar los 20,000 caracteres.

  8. Seleccione Crear receptor.

API

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

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

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID
  2. En el objeto LogReceptor del cuerpo de la solicitud de 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 ver 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 Configura y administra receptores.

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

  4. Recupera el nombre de la cuenta de servicio del campo writer_identity que se muestra en la respuesta de la API.

  5. 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.

    Si quieres obtener más información sobre cómo otorgar permisos a las cuentas de servicio para los recursos, consulta la sección Establece permisos de destino.

gcloud

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

  1. Proporciona el nombre del receptor, el destino del receptor, el filtro y el ID de la carpeta o la organización desde la que deseas enrutar los registros:

    gcloud logging sinks create SINK_NAME
    SINK_DESTINATION  --include-children \
    --folder=FOLDER_ID filter
    

    Por ejemplo, si creas un receptor agregado a nivel de carpeta y cuyo destino es un conjunto de datos de BigQuery, tu comando podría verse de la siguiente manera:

    gcloud logging sinks create SINK_NAME \
    bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID --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 que el receptor incluya todos los recursos dentro de la organización, se debe establecer la marca --include-children, incluso cuando la marca --organizationse pasa a create. Cuando se establece como false (la opción predeterminada), un receptor solo exporta los registros del recurso de host.

    • A fin de ver 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.

    Si quieres obtener más información sobre cómo otorgar permisos a las cuentas de servicio para los recursos, consulta la sección Establece permisos de destino.

Cualquier cambio que se realice en un receptor puede tardar unos minutos en aplicarse.

Crear filtros para receptores agregados

Como cualquier receptor, el receptor agregado contiene un filtro que selecciona entradas de registro individuales. Si quieres obtener ejemplos de filtros que puedes 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 con texto de color. Reemplácelos por 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.

Seleccionar la fuente del registro

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

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 los registros solo de un recurso supervisado específico en un proyecto de Cloud, usa varias comparaciones a fin de 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 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 coinciden 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 Identity and Access Management para escribir los registros en el destino de tu receptor. Para obtener la 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. Tu destino del 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 el propietario y el que administra. La cuenta de servicio se borra si se borra el receptor.

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

Sigue estos pasos a fin de establecer permisos para que tu receptor se enrute a su destino:

Console

  1. Obtén la identidad de escritor del receptor, una dirección de correo electrónico, del receptor nuevo. Ve a la página Enrutador de registros y selecciona Menú > Ver detalles del receptor. La identidad del escritor aparece en el panel Detalles del receptor.

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

    • Para los destinos de Cloud Storage, agrega la identidad de escritor del receptor a tu bucket 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 el caso de Pub/Sub, agrega la identidad de escritor del receptor a tu tema y asígnale la función de publicador de Pub/Sub.
    • Para los destinos de buckets de Logging en diferentes proyectos de Cloud, agrega la identidad de escritor del receptor al bucket de destino y asígnale el permiso roles/logging.bucketWriter.

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

API

  1. Obtén la cuenta de servicio del campo writerIdentity en tu receptor mediante una llamada al método de API organizations.sinks.get o folders.sinks.get.

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

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
    
  2. Agrega la nueva identidad de escritor del receptor a la lista de permisos del destino, de forma que el escritor escriba en el destino.

    Si tienes acceso de Propietario de IAM al 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 el caso de Pub/Sub, incluyendo 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 de buckets de Logging en diferentes proyectos de Cloud, agrega la identidad de escritor del receptor al bucket de registros de destino y asígnale el permiso roles/logging.bucketWriter.

    Si no tienes acceso de Propietario al destino del receptor, envía el nombre de la cuenta de servicio del escritor a alguien que tenga esa capacidad. Esa persona debería 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 de IAM al 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 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 el caso de Pub/Sub, 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 del escritor a alguien que tenga esa capacidad. Esa persona debería seguir las instrucciones del paso anterior para agregar la identidad de escritor al destino del receptor.

    Por ejemplo, si enrutas registros entre buckets 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 Identity and Access Management para el proyecto de destino de Cloud 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 creado. 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 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?