Otorga acceso al Sincronizador de configuración a tu repositorio de Git

En esta página, se describe cómo autenticar Sincronizador de configuración en tu repositorio de Git. El Sincronizador de configuración requiere acceso de solo lectura a tu fuente de información para que pueda leer tus configuraciones, aplicarlas a tus clústeres y mantenerlas sincronizadas.

Elige un método de autenticación

El método de autenticación que uses dependerá de lo que se admita para tu tipo de fuente.

En la siguiente tabla, se resumen los métodos de autenticación que puedes usar con Sincronizador de configuración:

Método Fuentes admitidas Descripción Limitaciones
Sin autenticación Git, OCI y Helm No se requiere ninguna configuración adicional. Solo funciona si tu fuente de referencia es pública.
Par de claves SSH Git Es compatible con la mayoría de los proveedores de Git. Requiere administración de claves. No es compatible con OCI ni Helm.
token Git y Helm Es compatible con la mayoría de los proveedores de Git. Es una buena alternativa si tu organización no permite el uso de claves SSH. Admite el nombre de usuario y la contraseña para Helm. Requiere administración de tokens. Los tokens pueden vencer. No es compatible con OCI.
Cuenta de servicio de Kubernetes OCI, Helm Usa IAM para otorgar acceso a Artifact Registry directamente a una cuenta de servicio de Kubernetes. Requiere que Workload Identity Federation for GKE esté habilitada en tu clúster. No es compatible con Git.
Cuenta de servicio de Google Git Usa IAM, lo que evita almacenar credenciales en Secrets de Kubernetes. Se recomienda para Secure Source Manager y Cloud Source Repositories. Requiere que Workload Identity Federation for GKE esté habilitada en tu clúster. Requiere configuración antes y después de instalar el Sincronizador de configuración en tus clústeres. No se admite para los repositorios alojados fuera de Secure Source Manager o Cloud Source Repositories.
App de GitHub Git Integración directa con GitHub Permite permisos detallados. Solo se admite para los repositorios alojados en GitHub. Solo se admite en la versión 1.19.1 y posteriores del Sincronizador de configuración.

El Sincronizador de configuración también admite los siguientes métodos de autenticación. Sin embargo, estos métodos solo se recomiendan si no puedes usar una de las opciones que se indican en la tabla anterior:

  • cookiefile: Es posible que no se admita para todos los proveedores de Git. No es compatible con OCI ni Helm.
  • Cuenta de servicio predeterminada de Compute Engine (gcenode): No se recomienda porque este método solo funciona si la federación de identidades para cargas de trabajo para GKE está inhabilitada. Compatible con Git, OCI y Helm.
  • Cuenta de servicio de Google para Helm y OCI: Se admite, pero no se recomienda porque el método de la cuenta de servicio de Kubernetes requiere menos configuración.

Autenticación con paquetes de la flota

Si usas paquetes de flota, no es necesario que completes las instrucciones de esta página. Los paquetes de flota usan Cloud Build para autenticarse en Git, lo que te permite autenticarte una vez por proyecto, de modo que no necesites otorgar acceso cada vez que instales Sincronizador de configuración en un clúster.

Antes de comenzar

Antes de otorgar acceso de solo lectura al Sincronizador de configuración a tu repositorio de Git, completa las siguientes tareas:

Usa un par de claves SSH

Un par de claves SSH consta de dos archivos, una clave pública y una clave privada. El Sincronizador de configuración no admite la creación de frases de contraseña. Según tus requisitos de seguridad y cumplimiento, puedes usar un solo par de claves para todos los clústeres o un par de claves por clúster.

Para otorgar acceso de solo lectura al Sincronizador de configuración a tu repositorio de Git con un par de claves SSH, completa los siguientes pasos:

  1. Crea un par de claves SSH o pídele a tu administrador de seguridad que te lo proporcione. Si necesitas crear un par de claves SSH, ejecuta el siguiente comando para crear una clave RSA de 4096 bits:

    ssh-keygen -t rsa -b 4096 \
  -C "GIT_REPOSITORY_USERNAME" \
  -N '' \
  -f /path/to/KEYPAIR_FILENAME

    Reemplaza lo siguiente:

    • GIT_REPOSITORY_USERNAME: El nombre de usuario que deseas que el Sincronizador de configuración use para autenticarse en el repositorio. Si usas un host de repositorio de Git de terceros, como GitHub, o deseas usar una cuenta de servicio con Secure Source Manager, te recomendamos que uses una cuenta separada para la autenticación.
    • /path/to/KEYPAIR_FILENAME: Es la ruta de acceso al archivo del par de claves.

  2. Configura el repositorio para que reconozca la clave pública que acabas de crear. Consulta la documentación de tu proveedor de hosting de Git. Puedes encontrar instrucciones para algunos proveedores de hosting de Git comunes en la siguiente lista:

  3. Crea el secreto git-creds con la clave privada:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    Reemplaza /path/to/KEYPAIR_PRIVATE_KEY_FILENAME por el nombre de la clave privada.

  4. Opcional, pero recomendado: Para configurar la verificación de hosts conocidos cuando se usa la autenticación SSH, agrega la clave de hosts conocidos al campo data.known_hosts en el secreto git_creds.

    1. Para agregar la clave de hosts conocidos, ejecuta el siguiente comando:

      kubectl edit secret git-creds --namespace=config-management-system

    2. Para agregar la entrada known_hosts en data, ejecuta el siguiente comando:

        known_hosts: KNOWN_HOSTS_KEY

      Reemplaza KNOWN_HOSTS_KEY por la clave de hosts conocidos.

    Para inhabilitar la verificación de known_hosts, quita el campo known_hosts del secreto.

Cuando instales Sincronizador de configuración, usa el par de claves SSH (ssh) como el tipo de autenticación.

Cuando ingreses la URL de tu repositorio de Git, esta debe usar el formato del protocolo SSH. El formato de la URL difiere según el proveedor de Git.

Usa un archivo cookie

El proceso de adquisición de un cookiefile depende de la configuración del repositorio. Por lo general, las credenciales se almacenan en un archivo .gitcookies en un directorio principal, o las proporciona un administrador de seguridad.

Para otorgar acceso de solo lectura al Sincronizador de configuración a tu repositorio de Git con un cookiefile, completa los siguientes pasos:

Después de crear u obtener el cookiefile, agrégalo a un Secret nuevo en el clúster. Te recomendamos que uses HTTPS por motivos de seguridad:

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-file=cookie_file=/path/to/COOKIEFILE

Reemplaza /path/to/COOKIEFILE por tu ruta de acceso y nombre de archivo.

Cuando instales el Sincronizador de configuración, usa cookiefile (cookiefile) como el tipo de autenticación.

Cómo usar un token

Si tu organización no permite el uso de claves SSH, se recomienda usar un token.

Para otorgar acceso de solo lectura al Sincronizador de configuración a tu repositorio de Git con un token, completa los siguientes pasos:

  1. Genera un token desde tu proveedor de Git. Consulta la documentación de tu proveedor de hosting de Git para obtener instrucciones. Puedes encontrar instrucciones para algunos proveedores de hosting de Git comunes en la siguiente lista:

  2. Después de crear u obtener un token, agrégalo a un Secret nuevo en el clúster. Te recomendamos que uses HTTPS por motivos de seguridad:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

    Reemplaza lo siguiente:

    • USERNAME: El nombre de usuario que deseas usar
    • TOKEN: El token que creaste en el paso anterior

Cuando instales el Sincronizador de configuración, usa el token (token) como el tipo de autenticación.

Usa una cuenta de servicio de Google

Puedes otorgar al Sincronizador de configuración acceso a un repositorio en el mismo proyecto que tu clúster administrado con una cuenta de servicio de Google. Debes cumplir con los siguientes requisitos:

Para otorgar acceso de solo lectura al Sincronizador de configuración a tu repositorio de Git con una cuenta de servicio de Google, completa los siguientes pasos:

  1. Para obtener los permisos que necesitas para crear una vinculación de política, pídele a tu administrador que te otorgue el rol de IAM de administrador de cuentas de servicio (roles/iam.serviceAccountAdmin) en la cuenta de servicio. 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.

  2. Si no tienes una cuenta de servicio, crea una cuenta de servicio.

  3. Otorga el rol de IAM a la cuenta de servicio de Google según el tipo de repositorio que uses:

    Secure Source Manager

    Otorga los roles de IAM de Accesor de instancias de Secure Source Manager (roles/securesourcemanager.instanceAccessor) y Lector de repositorios de Secure Source Manager (roles/securesourcemanager.repoReader) a la cuenta de servicio de Google:

    • Otorga permisos en todo el proyecto si los mismos permisos se aplican a todos los repositorios del proyecto:

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.instanceAccessor \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.repoReader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Reemplaza lo siguiente:

      • PROJECT_ID: el ID de tu proyecto
      • GSA_NAME: Es el nombre de la cuenta de servicio de Google que deseas conectar a Secure Source Manager.

    • Para otorgar permisos específicos del repositorio, consulta la documentación de Secure Source Manager sobre cómo otorgar roles a nivel del repositorio a los usuarios.

    Cuando instales el Sincronizador de configuración, usa Workload Identity (gcpserviceaccount) como el tipo de autenticación. También debes agregar el correo electrónico de tu cuenta de servicio.

    Secure Source Manager requiere un formato específico para la URL del repositorio: https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git.

    Cloud Source Repositories

    Otorga el rol de IAM de lector de Cloud Source Repositories (roles/source.reader) a la cuenta de servicio de Google:

    • Otorga permisos en todo el proyecto si los mismos permisos se aplican a todos los repositorios del proyecto:

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Reemplaza lo siguiente:

      • PROJECT_ID: el ID de tu proyecto
      • GSA_NAME: Es el nombre de la cuenta de servicio de Google que deseas conectar a Cloud Source Repositories.

    • Otorga permisos específicos del repositorio cuando desees que las cuentas de servicio tengan diferentes niveles de acceso para cada repositorio de tu proyecto:

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

      Reemplaza lo siguiente:

      • PROJECT_ID: el ID de tu proyecto
      • REPOSITORY: es el nombre del repositorio,
      • POLICY_FILE: Es el archivo JSON o YAML que contiene la política de Identity and Access Management.

    Cuando instales el Sincronizador de configuración, usa Workload Identity (gcpserviceaccount) como el tipo de autenticación. También debes agregar el correo electrónico de tu cuenta de servicio.

El siguiente paso se debe completar después de configurar el Sincronizador de configuración, ya que la cuenta de servicio de Kubernetes no se crea hasta que configures el Sincronizador de configuración por primera vez. Solo debes hacerlo una vez por flota. Para crear la vinculación que permite que la cuenta de servicio de Kubernetes actúe como la cuenta de servicio de Google, ejecuta el siguiente comando:

gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

Reemplaza lo siguiente:

  • FLEET_HOST_PROJECT_ID: Si usas Workload Identity Federation for GKE, el valor es el mismo que PROJECT_ID. Si usas Workload Identity Federation for GKE para flota, usa el ID del proyecto de la flota en la que está registrado tu clúster como valor.
  • GSA_NAME: Es la cuenta de servicio personalizada de Google que deseas usar para conectarte a Secure Source Manager o Cloud Source Repositories.
  • KSA_NAME: Es la cuenta de servicio de Kubernetes para el conciliador. En la mayoría de los casos, el valor es root-sync porque el Sincronizador de configuración crea automáticamente un objeto RootSync llamado root-sync cuando se instala con la consola de Google Cloud o Google Cloud CLI. De lo contrario, usa root-reconciler-ROOT_SYNC_NAME como valor.

Si tienes problemas para conectarte a Sincronizador de configuración con una cuenta de servicio de Google, consulta Cómo solucionar problemas de permisos con una cuenta de servicio de Google.

Usa una cuenta de servicio predeterminada de Compute Engine

Como alternativa a una cuenta de servicio de Google, si no tienes habilitada la federación de Workload Identity para GKE, puedes usar una cuenta de servicio de Compute Engine para la autenticación. Este método solo se admite para los repositorios de Secure Source Manager y Cloud Source Repositories.

Para otorgar acceso de solo lectura al Sincronizador de configuración a tu repositorio con una cuenta de servicio predeterminada de Compute Engine, otorga a la cuenta de servicio predeterminada el rol roles/source.reader:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

Reemplaza lo siguiente:

  • PROJECT_ID: El ID de tu proyecto
  • PROJECT_NUMBER: con el número de tu proyecto.

Cuando instales el Sincronizador de configuración, usa Google Cloud Repository (gcenode) como el tipo de autenticación.

Usa una app de GitHub

Si tu repositorio está en GitHub, puedes usar la app de GitHub para conectarlo a Sincronizador de configuración:

  1. Sigue las instrucciones de GitHub para aprovisionar una app de GitHub y otorgarle permiso para leer tu repositorio.

  2. Agrega la configuración de la app de GitHub a un Secret nuevo en el clúster con el ID de cliente o de aplicación:

    ID de cliente 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=github-app-client-id=CLIENT_ID \
  --from-literal=github-app-installation-id=INSTALLATION_ID \
  --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
  --from-literal=github-app-base-url=BASE_URL
    • Reemplaza CLIENT_ID por el ID de cliente de la app de GitHub.
    • Reemplaza INSTALLATION_ID por el ID de instalación de la GitHub App.
    • Reemplaza /path/to/GITHUB_PRIVATE_KEY por el nombre del archivo que contiene la clave privada.
    • Reemplaza BASE_URL por la URL base del extremo de API de GitHub. Este valor solo es necesario cuando el repositorio no está alojado en www.github.com. De lo contrario, el argumento se puede omitir y se establece de forma predeterminada en https://api.github.com/.

    ID de aplicación 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-literal=github-app-application-id=APPLICATION_ID \
    --from-literal=github-app-installation-id=INSTALLATION_ID \
    --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
    --from-literal=github-app-base-url=BASE_URL
    • Reemplaza APPLICATION_ID por el ID de la aplicación de GitHub App.
    • Reemplaza INSTALLATION_ID por el ID de instalación de la GitHub App.
    • Reemplaza /path/to/GITHUB_PRIVATE_KEY por el nombre del archivo que contiene la clave privada.
    • Reemplaza BASE_URL por la URL base del extremo de API de GitHub. Este valor solo es obligatorio si el repositorio no está alojado en www.github.com. De lo contrario, el argumento se puede omitir y se establece de forma predeterminada en https://api.github.com/.

Cuando instales Sincronizador de configuración, usa la app de GitHub (githubapp) como el tipo de autenticación.

Soluciona problemas

Para obtener ayuda para solucionar problemas relacionados con la conexión del Sincronizador de configuración a tu fuente de información, consulta los siguientes temas de solución de problemas:

¿Qué sigue?