Crear un repositorio

En este documento, se explica el concepto de repositorios en Dataform y cómo crear uno nuevo.

Acerca de los repositorios de Dataform

Cada repositorio de Dataform aloja una colección de archivos SQLX y JavaScript que conforman tu flujo de trabajo, así como archivos de configuración y paquetes de Dataform. Interactúas con el contenido de tu repositorio en un espacio de trabajo de desarrollo.

Dataform muestra tus repositorios en la página de Dataform en orden alfabético según los IDs de los repositorios. Puedes ordenarlos y filtrarlos.

• Para ver tus repositorios, en la consola de Google Cloud , ve a la página Dataform.

  Ir a Dataform

Cada repositorio de Dataform está conectado a un agente de servicio de Dataform predeterminado o a una cuenta de servicio personalizada. Solo puedes seleccionar una cuenta de servicio personalizada cuando creas un repositorio. Puedes editar la cuenta de servicio más adelante.

De forma predeterminada, Dataform usa un agente de servicio o una cuenta de servicio derivados de tu número de proyecto con el siguiente formato:

[e-mail]

Dataform usa Git para registrar cambios y administrar versiones de archivos. Cada repositorio de Dataform corresponde a un repositorio de Git. Después de crear un repositorio de Dataform, puedes conectarlo a un repositorio remoto de GitHub, GitLab o Bitbucket.

En un repositorio de Dataform, Dataform almacena el código del repositorio. En un repositorio conectado, el repositorio de terceros almacena el código del repositorio. Dataform interactúa con el repositorio de terceros para permitirte editar y ejecutar su contenido en un espacio de trabajo de desarrollo de Dataform.

La página del repositorio de Dataform consta de los siguientes componentes:

Pestaña Development Workspaces

Muestra los espacios de trabajo de desarrollo creados en el repositorio.

Pestaña Registros de ejecución del flujo de trabajo

Muestra los registros de ejecución del flujo de trabajo de Dataform.

Pestaña Lanzamientos y planificación

Te permite inspeccionar, crear, editar y borrar configuraciones de lanzamiento y configuraciones de flujo de trabajo.

Pestaña Configuración

Muestra el nombre y la ubicación del repositorio. En el caso de un repositorio conectado a un repositorio de Git externo, muestra la fuente del repositorio externo, el nombre de la rama predeterminada y el token secreto. Muestra los botones para conectar el repositorio a un repositorio de Git externo y para editar la conexión de Git.

Botón para crear un espacio de trabajo de desarrollo

Te permite crear un espacio de trabajo de desarrollo.

Después de crear e inicializar un espacio de trabajo de desarrollo, puedes editar el archivo de configuración del flujo de trabajo para configurar los siguientes parámetros de configuración de Dataform de tu repositorio:

• Es la base de datos predeterminada (ID del proyectoGoogle Cloud ).
• Es el esquema predeterminado (ID del conjunto de datos de BigQuery).
• Ubicación predeterminada de BigQuery.
• Es el esquema predeterminado (ID del conjunto de datos de BigQuery) para las aserciones.
• El almacén, que debe establecerse en bigquery.
• Son variables definidas por el usuario que están disponibles para el código del proyecto durante la compilación.

Importante: Los repositorios creados en Dataform no se ven en los repositorios de BigQuery.

Para obtener más información sobre la configuración del repositorio de Dataform, consulta IProjectConfig en la referencia principal de Dataform.

Configuración del repositorio

Cuando creas un repositorio de Dataform, debes establecer la siguiente configuración del repositorio:

ID del repositorio

Es un ID único del repositorio. Los IDs solo pueden incluir números, letras, guiones y guiones bajos.

Región

Es la región de Dataform para almacenar el repositorio y su contenido.

Esta región de almacenamiento puede ser diferente de la región de procesamiento en la que Dataform procesa tu código y almacena el resultado de las ejecuciones. De forma predeterminada, la región de procesamiento se establece en la región predeterminada del conjunto de datos de BigQuery. Puedes editar la región de procesamiento en el archivo de configuración del flujo de trabajo después de crear el repositorio. Para obtener más información, consulta Configura los parámetros del flujo de trabajo de Dataform.

Agente de servicio o cuenta de servicio

Es el agente de servicio de Dataform o la cuenta de servicio personalizada asociada al repositorio. En el caso de los repositorios nuevos, debes proporcionar una cuenta de servicio personalizada. Puedes seleccionar una cuenta de servicio asociada a tu proyecto deGoogle Cloud o ingresar manualmente otra cuenta de servicio.

De forma predeterminada, Dataform usa un agente de servicio o una cuenta de servicio derivados de tu número de proyecto con el siguiente formato:

[e-mail]

Debes usar una cuenta de servicio personalizada para ejecutar flujos de trabajo en tu repositorio, pero el agente de servicio predeterminado de Dataform se sigue usando para todas las demás operaciones del repositorio.

Modo estricto de simulación de rol

Habilita una verificación de seguridad adicional que requiere el permiso iam.serviceAccounts.actAs en la cuenta de servicio. En el caso de los repositorios nuevos, se aplica el modo act-as estricto. En el caso de los repositorios existentes, recomendamos usar cuentas de servicio personalizadas y habilitar el modo act-as estricto para garantizar un modelo de permisos más seguro y predecible.

Encriptación

Es el método de encriptación del repositorio. Puedes usar la encriptación predeterminada, una clave de encriptación única de Cloud KMS administrada por el cliente o una clave de CMEK predeterminada de Dataform. Para obtener más información sobre el uso de claves de encriptación administradas por el cliente (CMEK) en Dataform, consulta Usa claves de encriptación administradas por el cliente.

Después de crear un repositorio, puedes conectarlo a GitHub o GitLab.

Importante: Para crear un repositorio de Dataform conectado a un repositorio de Git remoto que no esté en la lista de entidades permitidas de la política de dataform.restrictGitRemotes, primero agrega el repositorio de Git remoto a la lista de allowedValues en la política y, luego, crea un repositorio de Dataform nuevo y conéctalo al repositorio remoto. Para obtener más información, consulta Cómo restringir repositorios remotos.

Antes de comenzar

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Para usar la encriptación con CMEK en el repositorio, habilita la encriptación con CMEK de los repositorios de Dataform.

Importante: Antes de crear un repositorio de Dataform que quieras conectar a un repositorio de Git remoto, verifica si tu organización o proyecto restringen los repositorios de Git remotos con la política de la organización dataform.restrictGitRemotes. Si la política está vigente, asegúrate de que el repositorio remoto esté en la lista de entidades permitidas antes de crear el repositorio de Dataform y conectarlo al repositorio remoto. Para obtener más información, consulta Cómo restringir repositorios remotos

Roles obligatorios

Para obtener los permisos que necesitas para crear y borrar un repositorio, pídele a tu administrador que te otorgue los siguientes roles de IAM en los repositorios:

• Administrador de Dataform (roles/dataform.admin): El proyecto
• Usuario de cuenta de servicio (roles/iam.serviceAccountUser): Es la cuenta de servicio personalizada.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otorga roles necesarios

Para ejecutar flujos de trabajo en tu repositorio de Dataform y en BigQuery, puedes usar una cuenta de servicio personalizada o tu Cuenta de Google.

Tu cuenta de servicio personalizada debe tener los siguientes roles obligatorios:

• Editor de datos de BigQuery (roles/bigquery.dataEditor) en proyectos o conjuntos de datos específicos de BigQuery a los que Dataform necesita acceso de lectura y escritura. Por lo general, esto incluye el proyecto que aloja tu repositorio de Dataform.
• Visualizador de datos de BigQuery (roles/bigquery.dataViewer) en proyectos o conjuntos de datos específicos de BigQuery a los que Dataform necesita acceso de solo lectura
• Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en el proyecto que aloja tu repositorio de Dataform.

Para permitir que Dataform use tu cuenta de servicio personalizada, el agente de servicio predeterminado de Dataform debe tener los siguientes roles en el recurso de la cuenta de servicio personalizada:

• Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator)
• Usuario de cuenta de servicio (roles/iam.serviceAccountUser)

Para otorgar estos roles, sigue estos pasos:

1. En la consola de Google Cloud , dirígete a la página IAM.

   Ir a IAM

2. Haz clic en Otorgar acceso.

3. En el campo Principales nuevas, ingresa el ID de tu cuenta de servicio personalizada.

4. En el menú Seleccionar un rol, selecciona los siguientes roles uno por uno con la opción Agregar otro rol para cada rol adicional:

   • Editor de datos de BigQuery
   • Lector de datos de BigQuery
   • Usuario de trabajo de BigQuery

5. Haz clic en Guardar.

6. En la consola de Google Cloud , ve a la página Cuentas de servicio.

   Ir a Cuentas de servicio

7. Selecciona tu cuenta de servicio personalizada.

8. Ve a Principales con acceso y, luego, haz clic en Otorgar acceso.

9. En el campo Principales nuevas, ingresa el ID de tu agente de servicio predeterminado de Dataform.

   Tu ID del agente de servicio de Dataform predeterminado tiene el siguiente formato:

   [e-mail]
   

   Reemplaza PROJECT_NUMBER por el ID numérico de tu proyecto deGoogle Cloud . Puedes encontrar el ID de tu proyecto Google Cloud en elGoogle Cloud panel de la consola. Para obtener más información, consulta Identifica proyectos.

10. En la lista Seleccionar un rol, agrega los siguientes roles:

    • Service Account User
    • Creador de tokens de cuenta de servicio

11. Haz clic en Guardar.

Para obtener más información sobre cómo otorgar roles, consulta Otorga a Dataform el acceso requerido.

Crea un repositorio

Para crear un repositorio de Dataform, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Haz clic en Crear repositorio.

3. En el campo ID del repositorio de la página Crear repositorio, ingresa un ID único.

   Los IDs solo pueden incluir números, letras, guiones y guiones bajos.

4. En la lista desplegable Región, selecciona una región de Dataform para almacenar el repositorio y su contenido. Selecciona la región de Dataform más cercana a tu ubicación.

   Para obtener una lista de las regiones de Dataform disponibles, consulta Ubicaciones. La región del repositorio no tiene que coincidir con la ubicación de tus conjuntos de datos de BigQuery.

   En el archivo workflow_settings.yaml, puedes establecer la región de procesamiento en la que Dataform procesa tu código y almacena el resultado de las ejecuciones. La región de procesamiento debe coincidir con la ubicación de tus conjuntos de datos de BigQuery, pero no es necesario que coincida con la región del repositorio. Para obtener más información, consulta Configura los parámetros del flujo de trabajo de Dataform.

5. En el menú Cuenta de servicio, selecciona una cuenta de servicio personalizada para el repositorio.

   Importante: No puedes seleccionar el agente de servicio predeterminado de Dataform cuando creas un repositorio. Debes usar una cuenta de servicio personalizada para el repositorio.

   En el menú, puedes seleccionar una cuenta de servicio personalizada asociada con tu proyectoGoogle Cloud al que tienes acceso. Las cuentas de servicio personalizadas solo se usan para la ejecución del flujo de trabajo. Todas las demás operaciones del repositorio las realiza el agente de servicio predeterminado de Dataform.

   1. Opcional: Para seleccionar una cuenta de servicio que no se muestra en el menú (por ejemplo, si no tienes el permiso iam.serviceAccounts.list necesario para ver la lista de roles), haz clic en Ingresar manualmente y, luego, ingresa el ID de la cuenta de servicio.
   Nota: El permiso iam.serviceAccounts.list está disponible en el rol View Service Accounts (roles/iam.serviceAccountViewer).

6. En la sección Verificaciones de permisos de actAs, aplica las verificaciones de permisos en las acciones del usuario en el repositorio. Para obtener detalles sobre estas verificaciones, consulta Cómo usar el modo act-as estricto.

7. Configura el mecanismo de encriptación seleccionado para el repositorio:

   Precaución: No puedes cambiar el mecanismo de encriptación de un repositorio de Dataform después de que se crea. Para obtener más información, consulta Restricciones de CMEK de Dataform.

   Clave CMEK predeterminada

   Dataform muestra la casilla de verificación Usar la clave de KMS predeterminada y la selecciona de forma predeterminada.

   • Para encriptar el repositorio con la clave de CMEK predeterminada de Dataform, deja seleccionada la casilla de verificación Usar la clave de KMS predeterminada.

   Precaución: Si seleccionas la casilla de verificación Usar la clave de KMS predeterminada, pero no se configuró ninguna clave de CMEK predeterminada de Dataform para tu proyecto, la app de Dataform aplica la encriptación en reposo al repositorio. Usa claves de encriptación administradas por el cliente.

   Clave CMEK única

   Para encriptar el repositorio con una clave CMEK única, haz lo siguiente:

   1. Si la casilla de verificación Usar la clave de KMS predeterminada está seleccionada de forma predeterminada, desmarca la casilla.
   2. En la sección Encryption, selecciona la opción Claves de encriptación administradas por el cliente (CMEK).
   3. En el menú desplegable Selecciona una clave administrada por el cliente, selecciona una clave CMEK única.

   Encriptación en reposo

   • Para usar la encriptación predeterminada, en la sección Encriptación, selecciona la opción Google-managed encryption key.

   Precaución: Si se establece una clave de CMEK predeterminada de Dataform para la región de tu repositorio, debes usar la encriptación con CMEK. No selecciones la opción Google-managed encryption key. Para obtener más información, consulta Restricciones de CMEK de Dataform.

8. Haz clic en Crear y, luego, en Ir a repositorios.

Edita la cuenta de servicio

Debes asociar una cuenta de servicio personalizada con un repositorio de Dataform para la ejecución del flujo de trabajo. El agente de servicio predeterminado de Dataform sigue realizando todas las demás operaciones del repositorio.

Para editar la cuenta de servicio de un repositorio de Dataform, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Selecciona un repositorio y, luego, haz clic en Configuración.

   Nota: La lista de repositorios de Dataform solo incluye los repositorios creados para el desarrollo de flujos de trabajo de Dataform. Los repositorios de los recursos de BigQuery Studio, como los notebooks o las consultas guardadas, se administran por separado y no aparecen en esta lista.

3. Junto al campo Cuenta de servicio, haz clic en Editar cuenta de servicio.

4. En el menú Cuenta de servicio, selecciona una cuenta de servicio para el repositorio.

   En el menú, puedes seleccionar una cuenta de servicio personalizada asociada con tu proyectoGoogle Cloud al que tienes acceso.

   1. Opcional: Para seleccionar una cuenta de servicio que no se muestra en el menú, haz clic en Ingresar manualmente y escribe un ID de cuenta de servicio.

5. Haz clic en Guardar.

Borra un repositorio

Para borrar un repositorio y todo su contenido, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Junto al repositorio que deseas borrar, haz clic en el menú Más y, luego, selecciona Borrar.

3. En la ventana Borrar repositorio, ingresa el nombre del repositorio para confirmar su eliminación.

4. Haz clic en Borrar.

¿Qué sigue?

• Para obtener información sobre cómo conectar un repositorio de Dataform a un repositorio de Git de terceros, consulta Conéctate a un repositorio de Git de terceros.
• Para obtener más información sobre cómo el tamaño del repositorio afecta el desarrollo en Dataform, consulta la Descripción general del tamaño del repositorio.
• Para obtener más información sobre cómo dividir un repositorio en Dataform, consulta Introducción a la división de repositorios.
• Para obtener información sobre cómo configurar los parámetros de procesamiento de Dataform, consulta Configura los parámetros del flujo de trabajo de Dataform.
• Para obtener información sobre cómo crear e inicializar un lugar de trabajo, consulta Crea un lugar de trabajo.