Conceder acceso a Config Sync a tu repositorio de Git

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

Elegir un método de autenticación

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

En la siguiente tabla se resumen los métodos de autenticación que puedes usar con Config Sync:

Método Fuentes admitidas Descripción Limitaciones
Sin autenticación Git, OCI y Helm No es necesario configurar nada más. Solo funciona si tu fuente de información es pública.
Par de claves SSH Git Compatible con la mayoría de los proveedores de Git. Requiere gestión de claves. No se admite en OCI ni en Helm.
token Git y Helm Compatible con la mayoría de los proveedores de Git. Es una buena alternativa si tu organización no permite usar claves SSH. Admite nombres de usuario y contraseñas para Helm. Requiere gestión de tokens. Los tokens pueden caducar. No se admite en OCI.
Cuenta de servicio de Kubernetes OCI, Helm Usa IAM para conceder acceso a Artifact Registry directamente a una cuenta de servicio de Kubernetes. Requiere que Workload Identity Federation para GKE esté habilitado en tu clúster. No se admite en Git.
Cuenta de servicio de Google Git Usa IAM, lo que evita almacenar credenciales en secretos de Kubernetes. Se recomienda para Secure Source Manager y Cloud Source Repositories. Requiere que Workload Identity Federation para GKE esté habilitado en tu clúster. Requiere configuración antes y después de instalar Config Sync en tus clústeres. No se admite en repositorios alojados fuera de Secure Source Manager o Cloud Source Repositories.
Aplicación de GitHub Git Integración directa con GitHub. Permite permisos pormenorizados. Solo se admite en repositorios alojados en GitHub. Solo se admite en Config Sync 1.19.1 y versiones posteriores.

Config Sync 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:

  • Es posible que cookiefile: no sea compatible con todos los proveedores de Git. No se admite en OCI ni en Helm.
  • Cuenta de servicio predeterminada de Compute Engine (gcenode): no se recomienda porque este método solo funciona si Workload Identity Federation para GKE está inhabilitado. 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 cuenta de servicio de Kubernetes requiere menos configuración.

Autenticación con paquetes de flota

Si usas paquetes de flota, no tienes que seguir 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 tengas que conceder acceso cada vez que instales Config Sync en un clúster.

Antes de empezar

Antes de conceder acceso de solo lectura a tu repositorio de Git a Config Sync, completa las siguientes tareas:

Usar un par de claves SSH

Un par de claves SSH consta de dos archivos: una clave pública y una clave privada. Config Sync no admite la creación de contraseñas. En función de 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 conceder a Config Sync acceso de solo lectura a tu repositorio de Git mediante un par de claves SSH, sigue estos pasos:

  1. Crea un par de claves SSH o pide a tu administrador de seguridad que te lo proporcione. Si necesitas crear un par de claves SSH, crea una clave RSA de 4096 bits ejecutando el siguiente comando:

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

    Haz los cambios siguientes:

    • GIT_REPOSITORY_USERNAME: el nombre de usuario que quieres que use Config Sync para autenticarse en el repositorio. Si utilizas un host de repositorios Git de terceros, como GitHub, o quieres usar una cuenta de servicio con Gestor de fuentes seguras, te recomendamos que uses una cuenta independiente para la autenticación.
    • /path/to/KEYPAIR_FILENAME: la ruta al archivo del par de claves.

  2. Configura el repositorio para que reconozca la clave pública recién creada. Consulta la documentación de tu proveedor de alojamiento de Git. En la siguiente lista, encontrará instrucciones para algunos proveedores de alojamiento de Git habituales:

  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

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

  4. Opcional, pero recomendable: para configurar la comprobación de hosts conocidos al usar la autenticación SSH, añade la clave de hosts conocidos al campo data.known_hosts del secreto git_creds.

    1. Para añadir la clave de hosts conocidos, ejecuta el siguiente comando:

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

    2. Para añadir la entrada known_hosts en data, ejecuta el siguiente comando:

        known_hosts: KNOWN_HOSTS_KEY

      Sustituye KNOWN_HOSTS_KEY por la clave de hosts conocidos.

    Para inhabilitar la comprobación de known_hosts, quita el campo known_hosts de Secret.

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

Cuando introduzcas la URL de tu repositorio de Git, esta debe usar el formato del protocolo SSH. El formato de la URL varía en función del proveedor de Git.

Usar un archivo de cookies

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

Para conceder a Config Sync acceso de solo lectura a tu repositorio de Git mediante un cookiefile, sigue estos pasos:

Después de crear u obtener el cookiefile, añádelo a un nuevo secreto 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

Sustituye /path/to/COOKIEFILE por la ruta y el nombre de archivo.

Cuando instales Config Sync, usa cookiefile (cookiefile) como tipo de autenticación.

Usar un token

Si tu organización no permite usar claves SSH, puedes utilizar un token.

Para conceder acceso de solo lectura a tu repositorio de Git a Config Sync mediante un token, sigue estos pasos:

  1. Genera un token de tu proveedor de Git. Consulta las instrucciones en la documentación de tu proveedor de alojamiento de Git. En la siguiente lista, encontrará instrucciones para algunos proveedores de alojamiento de Git habituales:

  2. Después de crear u obtener un token, añádelo a un nuevo secreto 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

    Haz los cambios siguientes:

    • USERNAME: el nombre de usuario que quieras usar.
    • TOKEN: el token que has creado en el paso anterior.

Cuando instales Config Sync, usa el token (token) como tipo de autenticación.

Usar una cuenta de servicio de Google

Puedes conceder acceso a Config Sync a un repositorio que esté en el mismo proyecto que tu clúster gestionado mediante una cuenta de servicio de Google. Debes cumplir los siguientes requisitos:

Para conceder acceso de solo lectura a tu repositorio de Git a Config Sync mediante una cuenta de servicio de Google, sigue estos pasos:

  1. Para obtener los permisos que necesitas para crear un enlace de política, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin) en la cuenta de servicio. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

    También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

  2. Si aún no tienes una cuenta de servicio, crea una.

  3. Concede el rol de gestión de identidades y accesos a la cuenta de servicio de Google en función del tipo de repositorio que utilices:

    Secure Source Manager

    Concede los roles de gestión de identidades y accesos Accesor de instancia de Secure Source Manager (roles/securesourcemanager.instanceAccessor) y Lector de repositorio de Secure Source Manager (roles/securesourcemanager.repoReader) a la cuenta de servicio de Google:

    • Concede 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"

      Haz los cambios siguientes:

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

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

    Cuando instales Config Sync, usa Workload Identity (gcpserviceaccount) como tipo de autenticación. También debes añadir el correo 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

    Concede el rol Lector de Cloud Source Repositories (roles/source.reader) de gestión de identidades y accesos a la cuenta de servicio de Google:

    • Concede 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"

      Haz los cambios siguientes:

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

    • Concede permisos específicos de repositorio cuando quieras 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

      Haz los cambios siguientes:

      • PROJECT_ID: tu ID de proyecto.
      • REPOSITORY: el nombre del repositorio.
      • POLICY_FILE: el archivo JSON o YAML que contiene la política de gestión de identidades y accesos.

    Cuando instales Config Sync, usa Workload Identity (gcpserviceaccount) como tipo de autenticación. También debes añadir el correo de tu cuenta de servicio.

Este paso debe completarse después de configurar Config Sync, ya que la cuenta de servicio de Kubernetes no se crea hasta que configuras Config Sync por primera vez. Solo tienes que 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

Haz los cambios siguientes:

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

Si tienes problemas para conectarte a Config Sync con una cuenta de servicio de Google, consulta el artículo Solucionar problemas de permisos con una cuenta de servicio de Google.

Usar 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 de carga de trabajo para GKE, puedes usar una cuenta de servicio de Compute Engine para autenticarte. Este método solo se admite en repositorios de Secure Source Manager y Cloud Source Repositories.

Para conceder a Config Sync acceso de solo lectura a tu repositorio mediante una cuenta de servicio predeterminada de Compute Engine, concede 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"

Haz los cambios siguientes:

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

Cuando instales Config Sync, usa Google Cloud Repository (gcenode) como tipo de autenticación.

Usar una aplicación de GitHub

Si tu repositorio está en GitHub, puedes usar la aplicación GitHub para conectar tu repositorio con Config Sync:

  1. Sigue las instrucciones de GitHub para aprovisionar una aplicación de GitHub y darle permiso para leer tu repositorio.

  2. Añade la configuración de la aplicación de GitHub a un nuevo secreto en el clúster mediante el ID de cliente o de aplicación:

    ID de clie 

    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
    • Sustituye CLIENT_ID por el ID de cliente de la aplicación de GitHub.
    • Sustituye INSTALLATION_ID por el ID de instalación de la aplicación GitHub.
    • Sustituye /path/to/GITHUB_PRIVATE_KEY por el nombre del archivo que contiene la clave privada.
    • Sustituye BASE_URL por la URL base del endpoint de la 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 asigna el valor predeterminado https://api.github.com/.

    ID de la 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
    • Sustituye APPLICATION_ID por el ID de la aplicación de GitHub.
    • Sustituye INSTALLATION_ID por el ID de instalación de la aplicación GitHub.
    • Sustituye /path/to/GITHUB_PRIVATE_KEY por el nombre del archivo que contiene la clave privada.
    • Sustituye BASE_URL por la URL base del endpoint de la API de GitHub. Este valor solo es obligatorio si el repositorio no está alojado en www.github.com. De lo contrario, se puede omitir el argumento, que tiene el valor predeterminado https://api.github.com/.

Cuando instales Config Sync, usa la aplicación de GitHub (githubapp) como tipo de autenticación.

Solución de problemas

Para obtener ayuda sobre cómo solucionar problemas relacionados con la conexión de Config Sync a tu fuente de información veraz, consulta los siguientes temas:

Siguientes pasos