Cómo autenticar un paquete privado en Dataform

En este documento, se muestra cómo autenticar un paquete de NPM privado en Dataform para habilitar su instalación en un repositorio de Dataform.

Para instalar un paquete de NPM privado en un repositorio de Dataform y usarlo para desarrollar tu flujo de trabajo de SQL, primero debes autenticar el paquete en Dataform. El proceso de autenticación es diferente para el primer paquete privado en un repositorio y un paquete privado posterior en un repositorio.

Antes de comenzar

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

    Ve a la página Dataform

  2. Selecciona o crea un repositorio.

  3. Selecciona o crea un lugar de trabajo de desarrollo.

Roles obligatorios

Para obtener los permisos que necesitas para autenticar paquetes NPM privados en Dataform, pídele a tu administrador que te otorgue el rol de IAM Editor de Dataform (roles/dataform.editor) en repositorios y espacios de trabajo. 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 mediante roles personalizados o cualquier otro rol predefinido.

Cómo autenticar el primer paquete privado en un repositorio de Dataform

Para autenticar paquetes privados de NPM en Dataform, debes hacer lo siguiente antes de instalar el primer paquete privado de NPM en un repositorio de Dataform:

  1. Crea un secreto de Secret Manager dedicado a almacenar tokens de autenticación de paquetes privados de NPM en el repositorio de Dataform.

    1. Agrega el token de autenticación del paquete, obtenido de tu registro de NPM, al secreto.

    Debes almacenar todos los tokens de autenticación de los paquetes privados de NPM en un solo Secret de tu repositorio. Debes crear un secreto dedicado por repositorio de Dataform. El Secret debe estar en formato JSON.

  2. Sube el secreto al repositorio de Dataform.

  3. Crea un archivo .npmrc y agrega el token de autenticación del paquete al archivo.

    El token de autenticación en el archivo .npmrc debe coincidir con el token de autenticación en el secreto subido.

Después de autenticar el paquete privado de NPM, puedes instalarlo en el repositorio de Dataform.

Crea un secreto para la autenticación de paquetes privados

Para autenticar paquetes privados de NPM en un repositorio de Dataform, debes crear un secreto de Secret Manager y definir tokens de autenticación para todos los paquetes privados que deseas instalar en el repositorio de Dataform dentro del secreto. Define un token de autenticación por paquete privado de NPM y almacena todos los tokens de autenticación en un solo secreto por repositorio. El Secret debe estar en formato JSON.

Para crear un secreto con tokens de autenticación para paquetes privados de NPM, sigue estos pasos:

  1. En Secret Manager, crea un secreto.

    1. En el campo Valor del secreto, ingresa uno o varios tokens de autenticación en el siguiente formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Reemplaza lo siguiente:

    • AUTHENTICATION_TOKEN_NAME: Es un nombre único para el token que identifica el paquete que autentica.
    • TOKEN_VALUE: Es el valor del token de autenticación, que se obtiene de tu registro de NPM.

  2. Otorga acceso al secreto a tu cuenta de servicio de Dataform.

    Tu cuenta de servicio de Dataform tiene el siguiente formato:

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Cuando otorgues acceso, asegúrate de otorgar el rol roles/secretmanager.secretAccessor a tu cuenta de servicio de Dataform.

Sube el secreto para la autenticación de paquetes privados a un repositorio de Dataform

Antes de instalar un paquete NPM privado en un repositorio de Dataform por primera vez, sube el Secret que contiene el token de autenticación del paquete al repositorio.

Para subir el Secret con tokens de autenticación de paquetes privados de NPM a 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 el repositorio en el que deseas instalar paquetes privados de NPM.

  3. En la página del repositorio, haz clic en Configuración > Configurar paquetes NPM privados.

  4. En el panel Agregar token para secreto del paquete de npm, en el menú desplegable Secreto, selecciona el secreto que contiene los tokens de autenticación para los paquetes privados de NPM.

  5. Haz clic en Guardar.

Crea un archivo .npmrc para la autenticación de paquetes privados

Para autenticar paquetes privados de NPM en un repositorio de Dataform, debes crear un archivo .npmrc de nivel superior en el repositorio. Debes almacenar los tokens de autenticación para que todos los paquetes privados de NPM se instalen en el repositorio dentro del archivo .npmrc. Los tokens de autenticación del archivo .npmrc deben coincidir con los tokens de autenticación del secreto subido al repositorio. Para obtener más información sobre los archivos .npmrc, consulta la documentación de npmrc.

Para crear un archivo .npmrc de nivel superior en tu repositorio, sigue estos pasos:

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

    Ir a Dataform

  2. Selecciona el repositorio en el que deseas instalar paquetes privados de NPM y, luego, selecciona un lugar de trabajo.

  3. En el panel Archivos, haz clic en el menú Más y, luego, en Crear archivo.

  4. En el panel Crear un archivo nuevo, haz lo siguiente:

    1. En el campo Agregar una ruta de acceso al archivo, ingresa .npmrc.

    2. Haz clic en Crear archivo.

Agrega un token de autenticación al archivo .npmrc en un repositorio de Dataform

Para autenticar un paquete privado de NPM en un repositorio de Dataform que ya contiene un Secret con tokens de autenticación de paquetes y un archivo .npmrc, debes agregar el token de autenticación del paquete privado al archivo .npmrc del repositorio.

En el archivo .npmrc, debes definir el alcance de tu registro de NPM y agregar el token de autenticación para el paquete privado al que se accede en ese alcance. Para obtener más información sobre los archivos .npmrc, consulta la documentación de npmrc.

El token de autenticación en el archivo .npmrc debe coincidir con el token de autenticación en el secreto subido al repositorio.

Para agregar un token de autenticación al archivo .npmrc en 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 el repositorio en el que deseas instalar paquetes privados de NPM y, luego, selecciona un lugar de trabajo.

  3. En el panel Files, selecciona el archivo .npmrc.

  4. En el archivo .npmrc, define el alcance del registro de NPM y el token de autenticación para el paquete privado en el siguiente formato:

   @REGISTRY-SCOPE:registry=NPM-REGISTRY-URL
   NPM-REGISTRY-URL:_authToken=$AUTHENTICATION-TOKEN

Reemplaza lo siguiente:

  • REGISTRY-SCOPE: Es el alcance del registro de NPM al que deseas aplicar el token de autenticación.
  • NPM-REGISTRY-URL: Es la URL de tu registro de NPM, por ejemplo, https://npm.pkg.github.com.

  • AUTHENTICATION-TOKEN: Es el token de autenticación del paquete NPM privado. El token de autenticación del archivo .npmrc debe coincidir con el token de autenticación del secreto subido. El token de autenticación se proporciona como una variable de entorno en el archivo .npmrc, así que asegúrate de agregar los paréntesis de apertura ${ y cierre }.

    Puedes ingresar varios tokens de autenticación.

En la siguiente muestra de código, se muestra un token de autenticación para un paquete NPM privado que se agregó al archivo .npmrc en un repositorio de Dataform:

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${AUTHENTICATION_TOKEN}

Cómo autenticar un paquete privado posterior en un repositorio de Dataform

Para autenticar un paquete NPM privado en un repositorio de Dataform que ya contiene un Secret con tokens de autenticación de paquetes y un archivo .npmrc, sigue estos pasos:

  1. En Secret Manager, muestra los secretos y selecciona el secreto que almacena los tokens de autenticación de los paquetes NPM privados de tu repositorio.

  2. Agrega una versión nueva al secreto.

    Dataform usa la versión más reciente del secreto de forma predeterminada.

    1. Agrega el token de autenticación del paquete privado al valor secreto en el siguiente formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Reemplaza lo siguiente:

    • AUTHENTICATION_TOKEN_NAME: Es un nombre único para el token que identifica el paquete que autentica.
    • TOKEN_VALUE: Es el valor del token de autenticación, que se obtiene de tu registro de NPM.

    Puedes agregar varios tokens de autenticación a la vez.

  3. En Dataform, agrega el token de autenticación al archivo .npmrc en tu repositorio.

Después de autenticar el paquete privado de NPM, puedes instalarlo en el repositorio de Dataform.

¿Qué sigue?