Instalar Anthos Config Management

El operador de Config Management es un controlador que administra Anthos Config Management en un clúster de Kubernetes. Sigue estos pasos para instalar y configurar el operador en cada clúster que desees administrar mediante Anthos Config Management.

Antes de comenzar

En esta sección, se describen los requisitos que debes cumplir antes de inscribir los clústeres compatibles en Anthos Config Management.

Prepara tu entorno local

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

  • Anthos Config Management requiere una autorización activa de Anthos. Para obtener más información, consulta los precios de Anthos.

  • Instala el SDK de Cloud, que proporciona los comandos de gcloudgsutil y kubectl que se usan en estas instrucciones.

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

    gcloud components install kubectl
    
  • Instala el comando nomos para poder usar el subcomando nomos status a fin de detectar cualquier problema durante la instalación y la configuración.

  • Para descargar componentes de Anthos Config Management, debes autenticarte en Google Cloud mediante el comando gcloud auth login.

  • Debes configurar el comando kubectl para conectarte a tus clústeres. Los pasos para hacerlo son diferentes para los clústeres de GKE y los clústeres de GKE On-prem.

  • La API de Anthos debe estar habilitada para tu proyecto:

gcloud

Para habilitar la API de Anthos, ejecuta el siguiente comando:

gcloud services enable anthos.googleapis.com

Console

Habilitar la API de Anthos

Clústeres

  • Tus clústeres deben estar en una plataforma y una versión compatibles con Anthos.

  • Tus clústeres se deben registrar en un entorno de Anthos mediante Connect. El entorno de tu proyecto proporciona una forma unificada de ver y administrar tus clústeres y sus cargas de trabajo como parte de Anthos, incluidos los clústeres fuera de Google Cloud. Los cargos de Anthos solo se aplican a tus clústeres registrados. Puedes averiguar cómo registrar un clúster en Registra un clúster.

Permisos

El usuario de Google Cloud que instala Anthos Config Management necesita permisos de administración de identidades y accesos (IAM) para crear funciones nuevas en tu clúster.

Inscribe un clúster

Para inscribir un clúster en Anthos Config Management, 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

Si instalas el operador de Config Management mediante Google Cloud Console, el operador se implementa de forma automática. Continúa con la creación del secreto git-creds.

Después de asegurarse de cumplir con todos los requisitos previos, puede implementar el Operador descargando y aplicando 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-management-operator.yaml config-management-operator.yaml
    
  2. Aplica la CRD:

    kubectl apply -f config-management-operator.yaml

Si esto falla, consulta Solución de problemas.

Otorga al operador acceso de solo lectura a Git

El operador necesita acceso de solo lectura al repositorio de Git (el repositorio) para poder leer los archivos de configuración confirmados en el repositorio y aplicarlos 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 ninguna autenticación o autorización para acceso de solo lectura, no necesitas crear un secreto git-creds. Puedes pasar a Configurar Anthos Config Management y configurar SecretType en none.

La mayoría de los usuarios deben crear credenciales porque el acceso de lectura a su repositorio está restringido. Anthos Config Management admite los siguientes mecanismos de autenticación:

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

Después de crear la credencial, agrégala al clúster como un secreto. La forma de crear el secreto depende del método de autenticación. Para obtener más información, consulta la sección sobre tu método de autenticación a continuación.

Elige el mejor método para autorizar el repositorio entre las siguientes opciones. El método que elijas también determinará el secretType que usarás cuando configures el operador.

Usa un par de llaves SSH

Si el repositorio admite el uso de un par de llaves SSH para la autorización, sigue los pasos de esta sección a fin de crear los materiales del secreto. De lo contrario, sigue las instrucciones que se indican en Usa un archivo cookie.

Un par de llaves 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.

  1. Crea un par de llaves SSH para permitir que el operador se autentique en el repositorio de Git. Esto es necesario si necesitas autenticarte en el repositorio para clonarlo o leerlo. 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.

    Con el siguiente comando, se crea una clave RSA de 4096 bits. No se recomiendan valores más bajos. Reemplaza [GIT REPOSITORY USERNAME] y /path/to/[KEYPAIR-FILENAME] por los valores que deseas que el operador use para autenticarse en el repositorio. Se recomienda usar una cuenta separada si usas un host de repositorio de Git de terceros, como GitHub, o usar una cuenta de servicio si usas un repositorio de Cloud Source Repositories.

    ssh-keygen -t rsa -b 4096 \
     -C "[GIT REPOSITORY USERNAME]" \
     -N '' \
     -f [/path/to/KEYPAIR-FILENAME]
    
  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:

  3. Agrega la clave privada a un Secreto nuevo del clúster. Sustituye el nombre de la clave privada (la que no tiene el sufijo .pub) en los casos en que veas /path/to/[KEYPAIR-PRIVATE-KEY-FILENAME].

    kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/[KEYPAIR-PRIVATE-KEY-FILENAME]
    
  4. Borra la clave privada del disco local o protégela.

Usa archivos cookie

Si el repositorio no admite el uso de un par de llaves SSH para la autorización, puedes usar un archivo cookie o un token de acceso personal.

Sigue los pasos de esta sección para crear los materiales del secreto del archivo cookie.

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

  1. Después de crear y obtener el archivo cookie, agrégalo a un Secreto nuevo en el clúster. Reemplaza /path/to/[COOKIEFILE] por la ruta de acceso y el nombre de archivo adecuados.

    kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=cookie_file=/path/to/[COOKIEFILE]
    
  2. Asegúrate de proteger los contenidos del archivo cookie si aún lo necesitas de forma local. De lo contrario, bórralo.

Usa un token

Si tu organización no permite el uso de claves SSH, se recomienda usar un token. Mediante Anthos Config Management, puedes usar los tokens de acceso personal (PAT) de GitHub o la contraseña de la aplicación de Bitbucket como 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 al token el permiso repo para que pueda leer desde 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.

    Bitbucket

    Crea una contraseña de la aplicación.

  2. Después de crear y obtener el token, agrégalo a un Secreto nuevo en el clúster. Reemplaza [USERNAME] por el nombre de usuario deseado y [TOKEN] por el token que creaste en el paso anterior.

    kubectl create secret generic git-creds \
        --namespace="config-management-system" \
        --from-literal=username=[USERNAME] \
        --from-literal=token=[TOKEN]
    
  3. Protege el token si lo necesitas de forma local. De lo contrario, bórralo.

Usa una cuenta de servicio de Google con un Google Source Repository

Si tu repositorio se encuentra en Google Source Repository, puedes usar secretType: gcenode para otorgar a Anthos Config Management acceso a un repositorio en el mismo proyecto que tu clúster administrado.

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

  • La cuenta de servicio predeterminada de Compute Engine PROJECT_NUMBER-compute@developer.gserviceaccount.com para el clúster debe tener acceso source.reader al repositorio:

    gcloud projects add-iam-policy-binding [PROJECT_ID] \
    --member serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role roles/source.reader
    
  • Los permisos de acceso para los nodos del clúster deben incluir cloud-source-repos-ro. Esto se logra si usas el permiso cloud-platform o si incluyes cloud-source-repos-ro en la lista --scopes especificada cuando creas el clúster:

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

Una vez que se cumplan estos requisitos, configura spec.git.syncRepo como la URL del repositorio de Google Source Repository deseado cuando configures el operador. Por ejemplo:

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

En el ejemplo anterior, se requiere lo siguiente:

spec.git.syncRepo: https://source.developers.google.com/p/my-project/r/my-repo-csr
Usa un repositorio de Google Source Repository 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 operador en la siguiente sección, crea una vinculación de políticas de IAM entre la cuenta de servicio de Kubernetes y la de Google. No se creará la cuenta de servicio de Kubernetes hasta que configures el operador para habilitar Anthos Config Management por primera vez.

Esta vinculación permite que la cuenta de servicio de Anthos Config Management 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]" \
  [PROJECT_NUMBER]-compute@developer.gserviceaccount.com

Por último, agrega annotation a la cuenta de servicio de Anthos Config Management Kubernetes mediante el uso de 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=[PROJECT_NUMBER]-compute@developer.gserviceaccount.com

Sin autenticación

Si el repositorio no necesita autenticación para el acceso de solo lectura, puedes continuar a fin de configurar el operador y establecer spec.git.secretType en none.

Configura el operador

Puedes configurar el operador para tu clúster mediante kubectl o Google Cloud Console.

kubectl

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

Por ejemplo, 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: my-cluster
  git:
    syncRepo: git@github.com:my-github-username/csp-config-management.git
    syncBranch: 1.0.0
    secretType: ssh
    policyDir: "foo-corp"

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.

Para aplicar la configuración, usa 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-1
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. Obligatoria.
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, se 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 Anthos Config Management 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. Es único dentro de la instalación de Anthos Config Management.
Configuración para integraciones

Estos campos permiten la integración con el conector de configuración y el controlador de políticas.

Key Descripción
spec.configConnector.enabled Si es true, se instala Config Connector. La configuración predeterminada es false.
spec.policyController.enabled Si es true, se habilita Policy Controller. La configuración predeterminada es false.
spec.policyController.templateLibraryInstalled Si es true, se instala la biblioteca de plantillas de restricciones. La configuración predeterminada es true.

Console

Limitaciones

La configuración de Anthos Config Management en Google Cloud Console tiene las siguientes limitaciones:

  • No puedes instalar ni configurar los siguientes elementos:
    • Controlador de políticas
    • Config Connector
    • Controlador de jerarquía
  • Solo se admite un subconjunto de opciones de configuración del Sincronizador de configuración. Entre las opciones de configuración del Sincronizador de configuración no compatibles, se incluyen las siguientes:
    • spec.git.proxy
    • spec.git.secretType: gcenode
    • spec.git.secretType: token
    • spec.sourceFormat

Si deseas usar alguna de estas opciones, no debes usar Cloud Console.

Configura el operador

Para configurar el operador en Cloud Console, completa estos pasos:

  1. Visita el menú de Anthos Config Management en Google Cloud Console.

    Visitar el menú de Anthos Config Management

  2. Selecciona tus clústeres registrados y haz clic en Configurar.

  3. En la sección Autenticación del repositorio de Git para ACM, completa lo siguiente:

    1. En Tipo de secreto, selecciona una de las siguientes opciones:

      • Ninguno (selecciona esta opción si el repositorio no requiere autenticación para el acceso de solo lectura)
      • SSH
      • cookiefile

      Si deseas seleccionar token o gcenode, configura el operador mediante kubectl.

    2. Haga clic en Continuar.

  4. En la sección Configuración de ACM para tus clústeres, completa los siguientes pasos:

    1. En el campo URL, agrega la URL del repositorio de Git para usarla como fuente de verdad. Este campo es obligatorio.
    2. En el campo Rama, agrega la rama del repositorio desde la que deseas realizar la sincronización. El valor predeterminado es la instancia principal. Este campo es obligatorio.
    3. En el campo Etiqueta/Confirmación, agrega la revisión de Git (etiqueta o hash) que se debe pagar. El valor predeterminado es HEAD.
    4. Haz clic en Show advanced options.
    5. En el campo Directorio de políticas, agrega la ruta dentro del repositorio en la parte superior de la jerarquía de políticas que deseas sincronizar. La opción predeterminada es el directorio raíz del repositorio.
    6. En el campo Tiempo de espera de la sincronización, agrega el período en segundos entre las sincronizaciones consecutivas. El tiempo predeterminado es de 15 segundos.
  5. Haga clic en Listo. Volverás al menú de Anthos Config Management. Después de unos minutos, actualiza la página y deberías ver Synced en la columna de estado junto a los clústeres que configuraste.

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 resultados similares a los que se muestran aquí, vea 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 Anthos Config Management creó eventos.

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.

Soluciona problemas

Las siguientes secciones te ayudarán a solucionar los problemas de la instalación de Anthos Config Management.

CPU insuficiente

La salida de kubectl get events podría incluir un evento con el tipo FailedScheduling. El evento tiene el siguiente aspecto:

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, debes hacer lo siguiente:

  • 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 (“attempt to grant extra privileges”)

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

Este error indica que el usuario actual tiene menos permisos que los necesarios para la instalación. Consulta la sección Requisitos para el control de acceso basado en funciones en GKE.

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

Es posible que se agreguen otros errores en el futuro.

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 olvidaste crear el secreto git-creds, el operador lo detecta en cuanto lo creas y no necesitas volver a aplicar la configuración.

Actualiza

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.

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-management-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 quieras administrar mediante Anthos Config Management.

  1. Borra el objeto ConfigManagement del clúster:

    kubectl delete configmanagement --all

    Sucederá lo siguiente:

    • Todos los ClusterRoles y los ClusterRoleBindings creados por Anthos Config Management en el clúster se borran del clúster.
    • Se borran todas las configuraciones del controlador de admisión instaladas por Anthos Config Management.
    • Se borrarán los contenidos del espacio de nombres config-management-system, a excepción del Secreto git-creds. Anthos Config Management no puede funcionar sin el espacio de nombres config-management-system. Cualquier CustomResourceDefinitions creado o modificado por Anthos Config Management se quitará 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 estás utilizando GKE on-prem, no puedes eliminar el operador manualmente.

    Si estás utilizando GKE y decides que ya no deseas utilizar Anthos Config Management, puedes desinstalar el operador siguiendo 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 de Anthos Config Management del espacio de nombres kube-system:

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

¿Qué sigue?