Recopila y enruta registros a nivel de la organización y de la carpeta a destinos compatibles

En este documento, se describe cómo crear sumideros agregados. Los receptores agregados te permiten combinar y enrutar los registros que generan los recursosGoogle Cloud de tu organización o carpeta a una ubicación centralizada.

Antes de comenzar

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

  • Que estés familiarizado con el comportamiento de los receptores agregados Para obtener información sobre estos consumidores, consulta la descripción general de los consumidores agregados.

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

  • Tienes uno de los siguientes roles de IAM para la organización o carpeta deGoogle Cloud desde la que enrutas las entradas de registro.

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

    Los permisos contenidos en estos roles te permiten crear, borrar o modificar receptores. Para obtener información sobre cómo configurar roles de IAM, consulta la Guía de control de acceso de Logging.

  • El destino del sumidero agregado existe o tienes la capacidad de crearlo.

    Cuando el destino es un proyecto de Google Cloud , el proyecto puede estar en cualquier organización. Todos los demás destinos pueden estar en cualquier proyecto de cualquier organización.

  • Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    Para usar las muestras de la API de REST en esta página en un entorno de desarrollo local, debes usar las credenciales que proporcionas a la CLI de gcloud.

      After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    Para obtener más información, consulta Autentica para usar REST en la documentación de autenticación de Google Cloud .

Crea un receptor agregado

Para configurar un receptor agregado, créalo y, luego, otórgale los permisos para escribir en el destino. En esta sección, se describe cómo crear un sumidero agregado. Para obtener información sobre cómo otorgar permisos al receptor, consulta la sección de esta página titulada Configura los permisos de destino.

Puedes crear hasta 200 receptores por carpeta o organización.

Console

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

  1. En la consola de Google Cloud , ve a la página Enrutador de registros:

    Ir a Enrutador de registros

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. Selecciona una organización o carpeta existente.

  3. Selecciona 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 crearlo, no podrás cambiarle el nombre, pero sí borrarlo y crear uno nuevo.

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

  5. En el menú Selecciona el servicio del receptor, selecciona el tipo de destino y, luego, completa el diálogo para especificarlo. Puedes seleccionar un destino existente o crear uno nuevo.

    • Para un sumidero de intercepción, selecciona Google Cloud project y, luego, ingresa el nombre completamente calificado del proyecto Google Cloud de destino:

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • Para un sumidero que no intercepta, selecciona el destino y, luego, ingresa el nombre completamente calificado del destino. Se admiten los siguientes destinos:

      • proyectoGoogle Cloud 

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Bucket de Cloud Logging

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME

      • Conjunto de datos de BigQuery

        Debes ingresar el nombre completamente calificado de un conjunto de datos habilitado para escritura. El conjunto de datos puede ser una tabla particionada o con particiones de fecha. No ingreses el nombre de un conjunto de datos vinculado. Los conjuntos de datos vinculados son de solo lectura.

        bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID

      • Bucket de Cloud Storage

        storage.googleapis.com/BUCKET_NAME

      • Tema de Pub/Sub

        pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

      • Splunk

        Ingresa el tema de Pub/Sub de tu servicio de Splunk.

  6. En el panel Elige registros para incluirlos en el receptor, selecciona los recursos que deseas incluir en el receptor.

    • Para un receptor de interceptación, selecciona Intercepta los registros transferidos por esta organización y todos los recursos secundarios.

    • Para un receptor que no intercepta, selecciona Incluir los registros transferidos por este recurso y todos los recursos secundarios.

  7. En el campo Crear filtro de inclusión, ingresa una expresión de filtro que coincida con las entradas de registro que deseas incluir. Si no configuras un filtro, todas las entradas de registro del recurso seleccionado se enrutan al destino.

    Por ejemplo, te recomendamos que compiles un filtro para enrutar todos los registros de auditoría de acceso a los datos a un solo bucket de registro. Este filtro se ve de la siguiente manera:

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

    Para ver ejemplos de filtros, consulta la sección Cómo crear filtros para sumideros agregados de esta página.

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

  8. Opcional: 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.

  9. Opcional: En el panel Elige registros para excluir del receptor, haz lo siguiente:

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

    2. En el campo Crea un filtro de exclusión, ingresa una expresión de filtro 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 deseas excluir.

      Por ejemplo, para excluir las entradas de registro de un proyecto específico de la planificación al destino, agrega el siguiente filtro de exclusión:

      logName:projects/PROJECT_ID

      Para excluir entradas de registro de varios proyectos, usa el operador lógico O para unir cláusulas logName.

    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.

  10. Selecciona Crear receptor.

  11. Para completar la configuración de tu receptor agregado, otorga a la cuenta de servicio del receptor el permiso para escribir entradas de registro en el destino del receptor. Para obtener más información, consulta Configura los permisos de destino.

gcloud

Para crear un receptor agregado, usa el comando logging sinks create:

  1. Para crear un receptor, llama al comando gcloud logging sinks create y asegúrate de incluir la opción --include-children.

    Antes de usar el siguiente comando, realiza los siguientes reemplazos:

    • SINK_NAME: Es el nombre del receptor de registros. No puedes cambiar el nombre de un sumidero después de crearlo.
    • SINK_DESTINATION: Es el servicio o proyecto al que deseas que se enruten tus entradas de registro. Para obtener información sobre el formato de estos destinos, consulta Formatos de ruta de destino.
    • INCLUSION_FILTER: Es el filtro de inclusión de un receptor. Para ver ejemplos de filtros, consulta Cómo crear filtros para sumideros agregados.
    • FOLDER_ID: Es el ID de la carpeta. Si quieres crear un receptor a nivel de la organización, reemplaza --folder=FOLDER_ID por -- organization=ORGANIZATION_ID.

    Ejecuta el comando gcloud logging sinks create:

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

    También puedes proporcionar las siguientes opciones:

    • Para crear un receptor de intercepción, incluye la opción --intercept-children.

    Por ejemplo, si creas un receptor agregado a nivel de la carpeta cuyo destino es un tema de Pub/Sub, tu comando podría verse de la siguiente manera:

    gcloud logging sinks create SINK_NAME \
  pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID --include-children \
  --folder=FOLDER_ID --log-filter="logName:activity"

  2. Otorga a la cuenta de servicio del receptor permiso para escribir en el destino del receptor. Para obtener más información, consulta Configura los permisos de destino.

REST

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

  1. Establece el campo parent para que sea la Google Cloud organización o la carpeta 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 LogSink del cuerpo de la solicitud del método, haz una de las siguientes acciones:

    • Establece includeChildren en True.

    • Para crear un receptor de intercepción, también establece el campo interceptChildren en True.

  3. Establece el campo filter para que coincida con las entradas de registro que deseas incluir.

    Para ver ejemplos de filtros, consulta Cómo crear filtros para sumideros agregados.

    La longitud de un filtro no puede superar los 20,000 caracteres.

  4. Establece los campos LogSink restantes como lo harías para cualquier otro receptor. Para obtener más información, consulta Enruta registros a destinos compatibles.

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

  6. Otorga a la cuenta de servicio del receptor permiso para escribir en el destino del receptor. Para obtener más información, consulta Configura los permisos de destino.

Los cambios que se realicen en un sumidero pueden tardar unos minutos en aplicarse.

Filtros para receptores agregados

En esta sección, se proporcionan ejemplos de filtros que puedes usar en un receptor agregado. Para ver más ejemplos, consulta Consultas de muestra con el Explorador de registros.

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ázalos por valores válidos.

La longitud de un filtro se limita a 20,000 caracteres.

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

Selecciona la fuente del archivo de registro

Para enrutar las entradas de registro de todos los recursos secundarios, no especifiques un proyecto, una carpeta ni una organización en los filtros de inclusión y exclusión de tu receptor. Por ejemplo, supongamos que configuras un receptor agregado para una organización con el siguiente filtro:

resource.type="gce_instance"

Con el filtro anterior, el sumidero agregado enruta las entradas de registro con un tipo de recurso de instancias de Compute Engine que se escriben en cualquier elemento secundario de esa organización al destino.

Sin embargo, puede haber situaciones en las que quieras usar un receptor agregado para enrutar entradas de registro solo desde recursos secundarios específicos. Por ejemplo, por motivos de cumplimiento, es posible que desees almacenar los registros de auditoría de carpetas o proyectos específicos en su propio bucket de Cloud Storage. En estas situaciones, configura tu filtro de inclusión para especificar cada recurso secundario cuyas entradas de registro deseas enrutar. Si deseas enrutar entradas de registro de una carpeta y todos los proyectos dentro de esta, el filtro debe enumerar la carpeta y cada uno de los proyectos que contiene esta, y también unir las sentencias con una cláusula OR.

Los siguientes filtros restringen las entradas de registro a proyectos, carpetas o organizaciones Google Cloud específicos:

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

Por ejemplo, para enrutar solo las entradas de registro escritas en instancias de Compute Engine que se escribieron en la carpeta my-folder, usa el siguiente filtro:

logName:"folders/my-folder/logs/" AND resource.type="gce_instance"

Con el filtro anterior, las entradas de registro escritas en cualquier recurso que no sea my-folder, incluidas las entradas de registro escritas en proyectos Google Cloud que son hijos de my-folder, no se enrutan al destino.

Selecciona el recurso supervisado

Para enrutar entradas de registro de solo un recurso supervisado específico en un proyectoGoogle Cloud , usa varias comparaciones para especificar el recurso de manera exacta:

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 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 Identity and Access Management para escribir entradas de registro 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 o actualizas un receptor que enruta entradas de registro a cualquier destino que no sea un bucket de registros en el proyecto actual, se requiere una cuenta de servicio para ese receptor. El registro crea y administra automáticamente la cuenta de servicio por ti:

  • A partir del 22 de mayo de 2023, cuando crees un receptor y no exista una cuenta de servicio para el recurso subyacente, Logging creará la cuenta de servicio. El registro usa la misma cuenta de servicio para todos los destinos en el recurso subyacente. Los recursos pueden ser un Google Cloud proyecto, una organización, una carpeta o una cuenta de facturación.
  • Antes del 22 de mayo de 2023, Logging creaba una cuenta de servicio para cada receptor. A partir del 22 de mayo de 2023, el registro usa una cuenta de servicio compartida para todos los sumideros en el recurso subyacente.

La identidad del escritor de un sumidero es el identificador de la cuenta de servicio asociada con ese sumidero. Todos los receptores tienen una identidad de escritor, a menos que escriban en un bucket de registros en el proyecto Google Cloud actual. La dirección de correo electrónico en la identidad de escritor identifica al principal que debe tener acceso para escribir datos en el destino.

Para enrutar entradas de registro 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.

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

Console

  1. Para obtener información sobre la cuenta de servicio de tu sink, haz lo siguiente:

    1. En la consola de Google Cloud , ve a la página Enrutador de registros:

      Ir a Enrutador de registros

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

    2. Selecciona Menú y, luego, Ver detalles del receptor. La identidad de escritor aparece en el panel Detalles del receptor.

    3. Si el valor del campo writerIdentity contiene una dirección de correo electrónico, continúa con el siguiente paso. Cuando el valor es None, no necesitas configurar los permisos de destino.

    4. Copia la identidad de escritor del receptor en el portapapeles. A continuación, se ilustra una identidad de escritor:

      serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  2. Otorga al principal especificado por la identidad de escritor del receptor el permiso para escribir datos de registro en el destino:

    1. En la Google Cloud consola, ve a la página IAM:

      Ir a IAM

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es IAM y administrador.

    2. En la barra de herramientas de la consola de Google Cloud , selecciona el proyecto que almacena el destino del sumidero agregado. Cuando el destino sea un proyecto, selecciónalo.

    3. Haz clic en Grant access.

    4. Ingresa el principal especificado por la identidad de escritor del receptor y, luego, otorga un rol de IAM:

gcloud

  1. Asegúrate de tener acceso de propietario en el proyectoGoogle Cloud que contiene el destino. Si no tienes acceso de Propietario al destino del sumidero, pídele al propietario del proyecto que agregue la identidad del escritor como principal.

  2. Para obtener información sobre la cuenta de servicio de tu sink, llama al método gcloud logging sinks describe.

    Antes de usar el siguiente comando, realiza los siguientes reemplazos:

    • SINK_NAME: Es el nombre del receptor de registros. No puedes cambiar el nombre de un sumidero después de crearlo.

    Ejecuta el comando gcloud logging sinks describe:

    gcloud logging sinks describe SINK_NAME

  3. Si los detalles del sumidero contienen un campo etiquetado como writerIdentity, continúa con el siguiente paso. Cuando los detalles no incluyen un campo writerIdentity, no es necesario que configures los permisos de destino para el receptor.

  4. Copia la identidad de escritor del receptor en el portapapeles. A continuación, se ilustra una identidad de escritor:

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  5. Para otorgarle a la identidad de escritor del receptor el permiso para escribir datos de registro en el destino, llama al comando gcloud projects add-iam-policy-binding.

    Antes de usar el siguiente comando, realiza los siguientes reemplazos:

    • PROJECT_ID: Es el identificador del proyecto. Selecciona el proyecto que almacena el destino del sink agregado. Cuando el destino sea un proyecto, selecciónalo.
    • PRINCIPAL: Es un identificador para la principal a la que deseas otorgar el rol. Los identificadores principales suelen tener el siguiente formato: PRINCIPAL-TYPE:ID. Por ejemplo, user:my-user@example.com. Para obtener una lista completa de los formatos que puede tener PRINCIPAL, consulta Identificadores de principal.

    • ROLE: Es un rol de IAM. Otorga a la identidad de escritor del receptor un rol de IAM según el destino del receptor de registros:

    Ejecuta el comando gcloud projects add-iam-policy-binding:

    gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE

REST

Te recomendamos que uses la Google Cloud consola o Google Cloud CLI para otorgar un rol a la cuenta de servicio.

¿Qué sigue?