Instala el Sincronizador de configuración

El operador del Sincronizador de configuración es un controlador que administra el Sincronizador de configuración en un clúster de Kubernetes. Sigue estos pasos para instalar y configurar el operador en cada clúster que desees administrar mediante el Sincronizador de configuración.

Nota: En esta página, se muestra cómo instalar el Sincronizador de configuración como un producto independiente. Si tienes Anthos, obtén información sobre cómo instalar el Sincronizador de configuración con Anthos Config Management.

Solicitudes de recursos

En la siguiente tabla, se enumeran los requisitos de los recursos de Kubernetes para los componentes del Sincronizador de configuración. Si deseas obtener más información, consulta Administra los recursos para contenedores en la documentación de Kubernetes.

Componente	CPU	Memoria
Operador del Sincronizador de configuración	100m	20Mi
Sincronizador de configuración	360m	210Mi

Antes de comenzar

En esta sección, se describen los requisitos que debes cumplir antes de instalar el Sincronizador de configuración en GKE.

Prepara tu entorno local

Antes de instalar el operador, asegúrate de haber preparado tu entorno local. Para ello, completa las siguientes tareas:

• Instala y, luego, inicializa el SDK de Cloud, que proporciona los comandos gcloud, gsutil, kubectl y nomos que se usan en estas instrucciones. Si usas Cloud Shell, el SDK de Cloud viene preinstalado.

• El SDK de Cloud no instala kubectl de forma predeterminada. Para instalar kubectl, usa el siguiente comando:

  gcloud components install kubectl
  

• Autentícate en Google Cloud mediante el comando gcloud auth login para que puedas descargar componentes del Sincronizador de configuración.

Prepara los clústeres

Tus clústeres deben ejecutar la versión 1.14.x de GKE o una posterior.

Prepara permisos

El usuario de Google Cloud que instala el Sincronizador de configuración necesita permisos de administración de identidades y accesos (IAM) para crear funciones nuevas en el clúster.

Inscribe un clúster

Para inscribir un clúster en Sincronizador de configuración, completa los siguientes pasos:

1. Implementa el operador
2. Otorga al operador acceso de solo lectura a Git
3. Configura el operador

Implementa el operador

Después de asegurarte de cumplir con todos los requisitos previos, puedes implementar el operador mediante la descarga y aplicación de un manifiesto YAML.

1. Descarga la última versión de la CDR del operador mediante el siguiente comando. En cambio, si deseas descargar una versión específica, consulta Descargas.

   gsutil cp gs://config-management-release/released/latest/config-sync-operator.yaml config-sync-operator.yaml
   

2. Aplica la CRD:

   kubectl apply -f config-sync-operator.yaml

Si esto falla, consulta Solución de problemas.

Otorga al operador acceso de solo lectura a Git

El Sincronizador de configuración necesita acceso de solo lectura a tu repositorio de Git para que pueda leer las configuraciones confirmadas en el repositorio y aplicarlas a tus clústeres. Si se requieren credenciales, se almacenan en el secreto git-creds de cada clúster inscrito.

Si el repositorio no requiere autenticación para el acceso de solo lectura, puedes continuar con la configuración del Sincronizador de configuración y configurar secretType como none. Por ejemplo, si puedes explorar el repositorio mediante una interfaz web sin acceder a tu cuenta, o si puedes usar git clone para crear una clonación del repositorio de forma local sin proporcionar credenciales o usar credenciales guardadas, no es necesario que realices la autenticación. En este caso, no necesitas crear un Secret git-creds.

Sin embargo, la mayoría de los usuarios deben crear credenciales porque el acceso de lectura a su repositorio está restringido. El Sincronizador de configuración admite los siguientes mecanismos de autenticación:

• Par de claves SSH
• Archivo cookie
• Token
• Cuenta de servicio de Google (solo repositorios de Google Source Repository)

El mecanismo que elijas dependerá de lo que admita tu repositorio. Si todos los mecanismos están disponibles, te recomendamos usar un par de claves SSH. GitHub, Cloud Source Repositories y Bitbucket son compatibles con el uso de un par de claves SSH. Si tu organización aloja tu repositorio y no sabes qué métodos de autenticación se admiten, comunícate con tu administrador.

Par de claves SSH

Un par de claves SSH consta de dos archivos, una clave pública y una clave privada. Por lo general, la clave pública tiene una extensión .pub.

Advertencia: Protege los archivos que se crean con este comando. Ellos otorgan la capacidad de leer desde tu repositorio.

Para usar un par de claves SSH, completa los siguientes pasos:

1. Crea un par de claves SSH para permitir que el Sincronizador de configuración se autentique en tu repositorio de Git. Este paso es necesario si necesitas autenticarte en el repositorio para clonarlo o leer de él. Omite este paso si un administrador de seguridad te proporciona un par de claves. Puedes usar un solo par de claves para todos los clústeres o un par de claves por clúster, según tus requisitos de seguridad y cumplimiento.

   El siguiente comando crea una clave RSA de 4096 bits. No se recomiendan valores más bajos:

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

   Reemplaza lo siguiente:

   • GIT_REPOSITORY_USERNAME: Agrega el nombre de usuario que deseas que el Sincronizador de configuración use para autenticarse en el repositorio.
   • /path/to/KEYPAIR_FILENAME: Agrega una ruta al par de claves.

   Si usas un host del repositorio de Git de terceros, como GitHub, o deseas usar una cuenta de servicio con Cloud Source Repositories, te recomendamos que uses una cuenta distinta.

   Nota: Debes crear la llave SSH sin una frase de contraseña. El Sincronizador de configuración no admite frases de contraseña de llaves SSH.

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. Se incluyen instrucciones para algunos proveedores de hosting de Git populares para mayor comodidad:

   • Cloud Source Repositories
   • Bitbucket
   • GitHub: Recomendamos que crees claves de implementación por separado para proporcionar acceso de solo lectura a un único repositorio de GitHub.
   • GitLab

3. Agrega la clave privada a un Secret nuevo del clúster:

   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 (la que no tiene el sufijo .pub).

4. Borra la clave privada del disco local o protégela.

Archivo cookie

Nota: El uso de credenciales cookiefile solo es compatible con Cloud Source Repositories. Si deseas usar GitHub con autenticación de archivos cookie, puedes usar Cloud Source Repositories para duplicar el repositorio de GitHub.

El proceso de adquisición de un archivo cookie depende de la configuración del repositorio. Para ver un ejemplo, consulta Genera credenciales estáticas en la documentación de Cloud Source Repositories. Por lo general, las credenciales se almacenan en el archivo .gitcookies en el directorio de tu página principal, o las puede proporcionar un administrador de seguridad.

Para usar un archivo cookie, completa los siguientes pasos:

1. Después de crear y obtener el archivo cookie, agrégalo a un Secreto nuevo en el clúster.

   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 la ruta de acceso y el nombre de archivo adecuados.

2. Protege el contenido del archivo cookie, si aún lo necesitas usar de forma local. De lo contrario, bórralo.

Token

Si tu organización no permite el uso de claves SSH, se recomienda usar un token. Con Sincronizador de configuración, puedes usar los tokens de acceso personal (PAT) de GitHub o la contraseña de la aplicación de Bitbucket como tu token.

Para crear un secreto mediante el uso de tu token, completa los siguientes pasos:

1. Crea un token mediante GitHub o Bitbucket.

   • GitHub: Crea un PAT. Otorga el permiso repo al token para que pueda leer de repositorios privados. Debido a que vinculas un PAT a una cuenta de GitHub, también te recomendamos crear un usuario de máquina y vincular tu PAT a este usuario.

   • Bitbucket: Crea una contraseña para la app.

2. Después de crear y obtener el token, agrégalo a un Secret nuevo en el clúster:

   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: Agrega el nombre de usuario que deseas usar.
   • TOKEN: Agrega el token que creaste en el paso anterior.

3. Protege el token si lo necesitas de forma local. De lo contrario, bórralo.

Cuenta de servicio de Google

Nota: El gcenode secretType solo funciona en GKE en Google Cloud.

Si tu repositorio se encuentra en un repositorio de Cloud Source Repositories, puedes usar secretType: gcenode para otorgar al Sincronizador de configuración acceso a un repositorio en el mismo proyecto que tu clúster administrado.

Requisitos previos

Antes de comenzar, asegúrate de que se cumplan los siguientes requisitos:

• Los permisos de acceso para los nodos del clúster deben incluir cloud-source-repos-ro. De forma predeterminada, la cuenta de servicio predeterminada de Compute Engine [e-mail] tiene acceso source.reader al repositorio del mismo proyecto pero, si es necesario, puedes agregar la función mediante el siguiente comando:

  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member serviceAccount:[e-mail] \
    --role roles/source.reader
  

  Reemplaza lo siguiente:

  • PROJECT_ID: Agrega el ID del proyecto de tu organización.
  • PROJECT_NUMBER: Agrega el número de proyecto de tu organización.

• Los permisos de acceso para los nodos del clúster deben incluir cloud-source-repos-ro. Puedes agregar este permiso si incluyes cloud-source-repos-ro en la lista --scopes especificada en el momento de la creación del clúster o si usas el permiso cloud-platform en el momento de la creación del clúster:

  gcloud container clusters create example-cluster --scopes=cloud-platform
  

Nota: No puedes modificar los permisos de acceso luego de crear un grupo de nodos. Sin embargo, puedes crear un grupo de nodos nuevo con el permiso de acceso adecuado mientras usas el mismo clúster. El permiso gke-default predeterminado no incluye cloud-source-repos-ro.

Usa un repositorio de Cloud Source Repositories como tu SyncRepo

Una vez que se cumplan estos requisitos previos, configura spec.git.syncRepo para la URL de los Cloud Source Repositories deseados cuando configures el operador.

Para usar un repositorio de Cloud Source Repositories como tu SyncRepo, completa los siguientes pasos:

1. Enumera todos los repositorios:

   gcloud source repos list
   

2. Copia del resultado la URL del repositorio que deseas usar:

   REPO_NAME  PROJECT_ID  URL
   my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr
   

3. Agrega la URL como tu syncRepo. Por ejemplo:

   spec.git.syncRepo: https://source.developers.google.com/p/my-project/r/my-repo-csr
   

Usa un repositorio de Cloud Source Repositories con Workload Identity

Si Workload Identity está habilitado en el clúster, se requieren pasos adicionales para usar secretType: gcenode. Después de completar los pasos anteriores y configurar el Sincronizador de configuración (lo cual harás en la siguiente sección), crea una vinculación de políticas de IAM entre la cuenta de servicio de Kubernetes y la cuenta de servicio de Google. La cuenta de servicio de Kubernetes no se creará hasta que configures el Sincronizador de configuración por primera vez.

Esta vinculación permite que la cuenta de servicio del Sincronizador de configuración de Kubernetes funcione como la cuenta de servicio predeterminada de Compute Engine:

gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/importer]" \
  [e-mail]

Reemplaza lo siguiente: * PROJECT_ID: El ID del proyecto de tu organización * PROJECT_NUMBER: El número de proyecto de tu organización

Nota: Para crear esta vinculación de política se requiere el permiso iam.serviceAccounts.setIamPolicy.

Después de crear la vinculación, agrega una annotation a la cuenta de servicio de Kubernetes del Sincronizador de configuración mediante la dirección de correo electrónico de la cuenta de servicio predeterminada de Compute Engine:

kubectl annotate serviceaccount -n config-management-system importer \
  iam.gke.io/gcp-service-account=[e-mail]

Reemplaza PROJECT_NUMBER por el número de proyecto de la organización.

Configura el operador

Para configurar el comportamiento del Sincronizador de configuración, debes crear un archivo de configuración para el CustomResource de ConfigManagement y, luego, aplicarlo mediante el comando kubectl apply:

1. Crea un archivo config-management.yaml y copia el siguiente archivo YAML en él.

   # config-management.yaml
   
   apiVersion: configmanagement.gke.io/v1
   kind: ConfigManagement
   metadata:
     name: config-management
   spec:
     # clusterName is required and must be unique among all managed clusters
     clusterName: CLUSTER_NAME
     git:
       syncRepo: REPO
       syncBranch: BRANCH
       secretType: TYPE
       policyDir: "DIRECTORY"
   

   Reemplaza lo siguiente:

   • CLUSTER_NAME: Agrega el nombre del clúster registrado al que quieres aplicar esta configuración.
   • REPO: Agrega la URL del repositorio de Git que se usará como fuente de información. Este campo es obligatorio.
   • BRANCH: Agrega la rama del repositorio desde la que se realiza la sincronización. El valor predeterminado es la rama principal (instancia principal).

   • TYPE: Agrega uno de los siguientes SecretTypes:

     • none
     • ssh
     • cookiefile
     • token
     • gcenode

   • DIRECTORY: Agrega la ruta de acceso en el repositorio de la parte superior de la jerarquía de políticas que se sincronizará. La opción predeterminada es el directorio raíz del repositorio.

   Nota: Si deseas almacenar config-management.yaml en tu repositorio de Git, debes configurar policyDir en un subdirectorio y colocar todos tus archivos de configuración dentro de ese subdirectorio. No coloques el archivo config-management.yaml en el subdirectorio policyDir.

   Para obtener una lista completa de los campos que puedes agregar al campo spec, consulta la siguiente sección Configuración del repositorio de Git. No cambies los valores de configuración fuera del campo de especificación.

2. Aplica la configuración mediante el comando kubectl apply:

   kubectl apply -f config-management.yaml
   

   Es posible que debas crear archivos de configuración separados para cada clúster o tipo de clúster. Puedes especificar el clúster mediante la opción --context:

   kubectl apply -f config-management1.yaml --context=CLUSTER_NAME
   

   Reemplaza CLUSTER_NAME por el nombre del clúster que deseas usar.

Configuración del repositorio de Git

Clave	Descripción
spec.git.syncRepo	La URL del repositorio de Git que se usará como fuente de información. Obligatorio.
spec.git.syncBranch	La rama del repositorio desde la que se realiza la sincronización. Valor predeterminado: master.
spec.git.policyDir	La ruta de acceso dentro del repositorio de Git que representa el nivel superior del repositorio que se sincronizará. Opción predeterminada: el directorio raíz del repositorio.
spec.git.syncWait	Período en segundos entre sincronizaciones consecutivas. Valor predeterminado: 15.
spec.git.syncRev	Revisión de Git (etiqueta o hash) que puedes consultar. Opción predeterminada: HEAD.
spec.git.secretType	El tipo de secreto configurado para acceder al repositorio de Git: ssh, cookiefile, token, gcenode o none. Obligatorio
spec.sourceFormat	Cuando se establece en unstructured, configura un repositorio no jerárquico. Valor predeterminado: hierarchy.

Configuración del proxy para el repositorio de Git

Si las políticas de seguridad de la organización requieren que enrutes el tráfico a través de un proxy HTTP(S), puedes configurar el Sincronizador de configuración para que se comunique con tu host de Git mediante el URI del proxy.

Clave	Descripción
spec.git.proxy.httpProxy	httpProxy define una variable de entorno HTTP_PROXY que se usa para acceder al repositorio de Git.
spec.git.proxy.httpsProxy	httpsProxy define una variable de entorno HTTPS_PROXY que se usa para acceder al repositorio de Git.

Si se especifican los campos httpProxy y httpsProxy, se ignorará httpProxy.

Configuración del comportamiento del objeto ConfigManagement

Clave	Descripción
spec.clusterName	El nombre definido por el usuario para el clúster que ClusterSelector usa a fin de agrupar clústeres. Único dentro de una instalación del Sincronizador de configuración.

Revisa la instalación

Puedes usar el comando nomos status para verificar si el operador está instalado de forma correcta. Una instalación válida sin problemas tiene el estado PENDING o SYNCED. Una instalación no válida o incompleta tiene el estado NOT INSTALLED o NOT CONFIGURED. El resultado también incluye cualquier error informado.

Cuando el operador se implementa de forma correcta, se ejecuta en un Pod cuyo nombre comienza con config-management-operator, en el espacio de nombres kube-system. La inicialización del Pod puede llevar unos minutos. Verifica que el pod esté en ejecución:

kubectl -n kube-system get pods | grep config-management

Si el Pod está en ejecución, la respuesta del comando es similar (pero no idéntica) a la siguiente:

config-management-operator-6f988f5fdd-4r7tr 1/1 Running 0 26s

También puedes verificar que el espacio de nombres config-management-system exista:

kubectl get ns | grep 'config-management-system'

El resultado del comando es similar al siguiente:

config-management-system Active 1m

Si los comandos no muestran una salida similar al que se muestra aquí, consulta los registros para ver qué salió mal:

kubectl -n kube-system logs -l k8s-app=config-management-operator

También puedes usar kubectl get events para verificar si el Sincronizador de configuración creó algún evento.

kubectl get events -n kube-system

Es posible tener una configuración no válida que no se detecte de inmediato, como un secreto git-creds no especificado o no válido. Para ver los pasos de solución de problemas, consulta Objeto ConfigManagement válido pero incorrecto en la sección Soluciona problemas de este tema.

Actualiza las versiones del Sincronizador de configuración

En esta sección, se proporcionan instrucciones generales para actualizar a la versión actual. Antes de realizar la actualización, consulta las notas de la versión para obtener instrucciones específicas.

Nota: No omitas versiones secundarias cuando realices la actualización.

Ejecuta estos comandos para cada clúster inscrito:

1. Descarga el manifiesto del operador y los comandos nomos para la versión nueva.

2. Aplica el manifiesto del operador:

   kubectl apply -f config-sync-operator.yaml
   

   Con este comando, se actualiza la imagen del operador. Kubernetes recupera la versión nueva y reinicia el pod del operador con la versión nueva. Cuando se inicia el operador, se ejecuta un bucle de conciliación que aplica el conjunto de manifiestos agrupados en la imagen nueva. Esto actualiza y reinicia cada pod componente.

3. Reemplaza el comando nomos o nomos.exe en todos los clientes con la versión nueva. Esto garantiza que el comando nomos siempre pueda obtener el estado de todos los clústeres inscritos y validar los archivos de configuración para ellos.

Desinstala el operador de un clúster

Sigue estas instrucciones para desinstalar el operador de un clúster. Debes seguir estos pasos para cada clúster que ya no desees administrar mediante el Sincronizador de configuración.

Notas sobre la desinstalación del Sincronizador de configuración

• Desinstalar el Sincronizador de configuración no afecta la configuración del repositorio ni quita los archivos de configuración de los clústeres.
• Para poder desinstalar el Sincronizador de configuración de un clúster, el operador debe estar en ejecución.

1. Borra el objeto ConfigManagement del clúster:

   kubectl delete configmanagement --all

   Sucederá lo siguiente:

   • Se borrarán del clúster todos los ClusterRoles y ClusterRoleBindings que creó el Sincronizador de configuración.
   • Se borrarán todas las opciones de configuración del controlador de admisión que instaló el Sincronizador de configuración.
   • Se borrarán los contenidos del espacio de nombres config-management-system, a excepción del Secret git-creds. El Sincronizador de configuración no puede funcionar sin el espacio de nombres config-management-system. Se quitarán las CustomResourceDefinitions que el Sincronizador de configuración creó o modificó de los clústeres en los que se crearon o modificaron. Las CustomResourceDefinitions (CRD) necesarias para ejecutar el operador aún existen porque, desde el punto de vista de Kubernetes, los agregó el usuario que instaló el operador. En el siguiente paso, se explica cómo quitarlos.

2. En este punto, el Operador todavía existe en tu clúster, pero no hace nada.

   Si usas GKE y decides que ya no quieres el Sincronizador de configuración, puedes desinstalar el operador mediante estos pasos:

   1. Verifica que el espacio de nombres config-management-system esté vacío después de borrar el objeto ConfigManagement en el paso anterior. Espera hasta que el comando kubectl -n config-management-system get all muestre No resources found..

   2. Borra el espacio de nombres config-management-system:

      kubectl delete ns config-management-system
      

   3. Borra la CustomResourceDefinition de ConfigManagement:

      kubectl delete crd configmanagements.configmanagement.gke.io
      

   4. Borra todos los objetos del Sincronizador de configuración del espacio de nombres kube-system:

      kubectl -n kube-system delete all -l k8s-app=config-management-operator
      

Soluciona problemas

En las siguientes secciones, encontrarás ayuda para solucionar problemas de instalación de Sincronizador de configuración.

CPU insuficiente

La salida de kubectl get events podría incluir un evento con el tipo FailedScheduling. El evento se ve como en el siguiente ejemplo:

LAST SEEN   TYPE      REASON              OBJECT                                             MESSAGE
9s          Warning   FailedScheduling    pod/config-management-operator-74594dc8f6    0/1 nodes are available: 1 Insufficient cpu.

Para corregir este error, elige una de las siguientes opciones:

• agregar un nodo a un grupo de nodos de GKE existente, o
• crear un grupo de nodos con nodos más grandes

Error: intenta otorgar privilegios adicionales

Si recibes el siguiente error, haz lo siguiente:

Error from server (Forbidden): error when creating "config-sync-operator.yaml": clusterroles.rbac.authorization.k8s.io "config-management-operator" is forbidden: attempt to grant extra privileges: [...] ruleResolutionErrors=[]

Cuando intentes aplicar el archivo config-management-operator.yaml, tendrás menos permisos que los necesarios para la instalación. Revisa Prepara permisos para asegurarte de que tienes los permisos necesarios.

Objeto ConfigManagement válido pero incorrecto

Si la instalación falla debido a un problema con el objeto ConfigManagement que no se debe a un error de sintaxis de YAML o JSON, es posible que se cree una instancia del objeto ConfigManagement en el clúster, pero que no funcione de manera correcta. En este caso, puedes usar el comando nomos status para verificar si hay errores en el objeto ConfigManagement.

Una instalación válida sin problemas tiene el estado PENDING o SYNCED.

Una instalación no válida tiene un estado de NOT CONFIGURED y enumera uno de los siguientes errores:

• missing git-creds Secret
• missing required syncRepo field
• git-creds Secret is missing the key specified by secretType

Para solucionar el problema, corrige el error de configuración. Según el tipo de error, es posible que debas volver a aplicar el manifiesto de ConfigManagement al clúster.

Si el problema es que te olvidaste de crear el Secret git-creds, el Sincronizador de configuración lo detecta tan pronto como lo creas y no es necesario que vuelvas a aplicar la configuración.

¿Qué sigue?

• Prueba la guía de inicio rápido.
• Obtén más información sobre cómo crear archivos de configuración.
• Usa el comando nomos.