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

En esta página, se describe cómo autenticar el 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 depende 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 el Sincronizador de configuración:

Método Fuentes admitidas Descripción Limitaciones
Sin autenticación Git, OCI, Helm No se requiere configuración adicional. Solo funciona si tu fuente de información 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, OCI, 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 nombre de usuario y contraseña para OCI y Helm. Requiere administración de tokens. Los tokens pueden vencer.
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é habilitado 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é habilitado en tu clúster. Requiere configuración antes y después de instalar el Sincronizador de configuración en tus clústeres. No es compatible con 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 es compatible con los repositorios alojados en GitHub.

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 enumeran en la tabla anterior:

  • cookiefile: Es posible que no sea compatible con 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 Workload Identity Federation for GKE está inhabilitado. Es compatible con Git, OCI y Helm.
  • Cuenta de servicio de Google para Helm y OCI: Es compatible, pero no se recomienda porque el método de cuenta de servicio de Kubernetes requiere menos configuración.

Autenticación con paquetes de 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 para que no necesites otorgar acceso cada vez que instales el 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 del repositorio de Git de terceros, como GitHub, o deseas usar una cuenta de servicio con Secure Source Manager, te recomendamos que uses una cuenta distinta para la autenticación.
    • /path/to/KEYPAIR_FILENAME: 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 el 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, la URL debe usar el formato del protocolo SSH. El formato de la URL difiere según el proveedor de Git.

Usa archivos 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 un administrador de seguridad las proporciona.

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

Usa 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. Si deseas obtener instrucciones, consulta la documentación del proveedor de hosting de Git. Puedes encontrar instrucciones para algunos proveedores de hosting de Git comunes en la siguiente lista:

  2. Después de crear o 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 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íticas, 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 Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) y Secure Source Manager Repo Reader (roles/securesourcemanager.repoReader) a la cuenta de servicio de Google:

    • Otorga permiso 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: Es el ID del proyecto.
      • GSA_NAME: Es el nombre de la cuenta de servicio de Google a la que deseas conectarte a Secure Source Manager.

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

    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 permiso 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: Es el ID del proyecto.
      • GSA_NAME: Es el nombre de la cuenta de servicio de Google a la que deseas conectarte a Cloud Source Repositories.

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

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

      Reemplaza lo siguiente:

      • PROJECT_ID: Es el ID del 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 para GKE de la flota, usa el ID del proyecto de la flota en la que está registrado tu clúster como el valor.
  • GSA_NAME: Es la cuenta de servicio de Google personalizada 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 Google Cloud consola o la Google Cloud CLI. De lo contrario, usa root-reconciler-ROOT_SYNC_NAME como el valor.

Si tienes problemas para conectarte al Sincronizador de configuración con una cuenta de servicio de Google, consulta Soluciona 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 identidades para cargas de trabajo para GKE, puedes usar una cuenta de servicio de Compute Engine para autenticarte. Este método solo es compatible con los repositorios en 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: Es el ID del proyecto.
  • PROJECT_NUMBER: Es 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 conectar tu repositorio al Sincronizador de configuración:

  1. Sigue las instrucciones de GitHub para aprovisionar una app de GitHub y otorgarle permiso para leer desde 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 app de GitHub.
    • 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, se puede omitir el argumento 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 aplicación de la app de GitHub.
    • Reemplaza INSTALLATION_ID por el ID de instalación de la app de GitHub.
    • 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 si el repositorio no está alojado en www.github.com. De lo contrario, se puede omitir el argumento y se establece de forma predeterminada en https://api.github.com/.

Cuando instales el 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, revisa los siguientes temas de solución de problemas:

¿Qué sigue?