Administrar objetos de clúster existentes

Cuando el Sincronizador de configuración administra un objeto de clúster, detecta el objeto y el conjunto de archivos de configuración en el repositorio que lo afectan, y se asegura de que estén sincronizados. En este tema, se describe cómo comenzar a administrar un objeto existente y cómo dejar de administrar un objeto que ya se administra sin borrarlo.

El Sincronizador de configuración administra un objeto en un clúster si tiene la anotación configmanagement.gke.io/managed: enabled y si su anotación configsync.gke.io/resource-id, que realiza un seguimiento de la información de grupo, tipo, espacio de nombres y nombre del objeto, es correcta.

El formato de la anotación configsync.gke.io/resource-id es GROUP_KIND_NAMESPACE_NAME para un objeto con permisos de espacio de nombres y GROUP_KIND_NAME para un objeto con permiso de clúster.

En el siguiente gráfico, se describen algunas situaciones que hacen que un objeto sea administrado o no administrado:

El gráfico contiene tres flujos separados: 1) comienza a administrar un objeto, 2) deja de administrar un objeto y 3) borra un objeto administrado.

1. Quiero comenzar a administrar un objeto. ¿El objeto tiene un manifiesto? En otras palabras, ¿el objeto tiene un archivo de configuración en el repositorio?
   • Si la respuesta es No, crea una configuración para el objeto. El Sincronizador de configuración establece la anotación configmanagement.gke.io/managed: enabled, establece la anotación configsync.gke.io/resource-id para que coincida con el objeto y comienza a administrarlo.
   • Si la respuesta es Sí, ¿el archivo de configuración establece la anotación configmanagement.gke.io/managed: disabled?
     • Si la respuesta es No, el objeto se administra de forma predeterminada.
     • Si la respuesta es Sí, edita el archivo de configuración para quitar la anotación configmanagement.gke.io/managed: disabled. Cuando el cambio se envía al repositorio de origen, el Sincronizador de configuración lo detecta, aplica la anotación configmanagement.gke.io/managed: enabled y la anotación configsync.gke.io/resource-id, y aplica el archivo de configuración.
2. Quiero dejar de administrar un objeto, pero no borrarlo.
   • Edita el archivo de configuración del objeto en el repositorio y configura la anotación configmanagement.gke.io/managed: disabled. Cuando se detecta el cambio del archivo de configuración, el Sincronizador de configuración deja de administrar el objeto.
3. Quiero dejar de administrar un objeto y borrarlo.
   • Borra el archivo de configuración del objeto del repositorio. Cuando borras un archivo de configuración de un objeto que antes se administraba, el Sincronizador de configuración borra el objeto de todos los clústeres o espacios de nombres a los que se aplica el archivo.

Además de la anotación configmanagement.gke.io/managed: enabled y la anotación configsync.gke.io/resource-id, el Sincronizador de configuración aplica la etiqueta app.kubernetes.io/managed-by: configmanagement.gke.io a todos los objetos que administra. Esta etiqueta te permite enumerar con facilidad todos los objetos mediante el Sincronizador de configuración.

¿Por qué no aplicas la anotación de forma manual?

El Sincronizador de configuración usa un modelo declarativo para aplicar los cambios de configuración a los clústeres mediante la lectura de la configuración deseada de tu repositorio. Si intentas aplicar la anotación de forma manual (ya sea con el comando de kubectl o la API de Kubernetes), el Sincronizador de configuración anula de forma automática el manual con el contenido de tu repositorio.

Antes de comenzar

Los siguientes ejemplos se basan en Comienza a usar el Sincronizador de configuración. Antes de continuar con los siguientes pasos, sigue la guía de inicio rápido y completa todos los pasos antes de explorar y probar la instalación del Sincronizador de configuración.

Enumera todos los objetos administrados

Para enumerar todos los objetos que administra el Sincronizador de configuración en un clúster o espacio de nombres determinados, usa un selector de etiquetas como el que se muestra a continuación:

kubectl get object-type -n namespace -l "app.kubernetes.io/managed-by=configmanagement.gke.io"

Para enumerar todos los objetos que no administra el Sincronizador de configuración, usa un selector de etiquetas como el que se muestra a continuación:

kubectl get object-type -n namespace -l "app.kubernetes.io/managed-by!=configmanagement.gke.io"

Por ejemplo, este comando enumera los RoleBindings en el espacio de nombres gamestore que administra el Sincronizador de configuración:

kubectl get rolebindings -n gamestore \
    -l "app.kubernetes.io/managed-by=configmanagement.gke.io"

El resultado es similar a este:

NAME                              ROLE                                          AGE
configsync.gke.io:ns-reconciler   ClusterRole/configsync.gke.io:ns-reconciler   34h
gamestore-admin                   ClusterRole/admin                             34h
gamestore-webstore-admin          ClusterRole/webstore-admin                    34h

Con este comando, se enumeran los RoleBindings en el espacio de nombres kube-system que no administra el Sincronizador de configuración:

kubectl get rolebindings -n kube-system \
    -l "app.kubernetes.io/managed-by!=configmanagement.gke.io"

El resultado es similar a este:

NAME                                             AGE
fluentd-gcp-scaler-binding                       2d21h
gce:cloud-provider                               2d21h
heapster-binding                                 2d21h
metrics-server-auth-reader                       2d21h
system::leader-locking-kube-controller-manager   2d21h
system::leader-locking-kube-scheduler            2d21h
system:controller:bootstrap-signer               2d21h
system:controller:cloud-provider                 2d21h
system:controller:token-cleaner                  2d21h

Comienza a administrar un objeto existente

Puedes crear un archivo de configuración para un objeto de Kubernetes existente, como un espacio de nombres que ya existe en el clúster antes de instalar el Sincronizador de configuración. Sin embargo, este archivo de configuración se ignora, a menos que el objeto tenga la anotación configmanagement.gke.io/managed: enabled y tenga la anotación configsync.gke.io/resource-id correcta. Para un objeto existente, debes aplicar la anotación de forma manual.

En el caso específico de espacios de nombres, el Sincronizador de configuración sí aplica archivos de configuración que crean objetos nuevos dentro de un espacio de nombres no anotado y aplica las anotaciones configmanagement.gke.io/managed: enabled y configsync.gke.io/resource-id a esos objetos. Sin embargo, el Sincronizador de configuración modificará o quitará del clúster a cualquier objeto con permisos de clúster no anotado. Esto se ilustra en el diagrama de Trabaja con archivos de configuración a lo largo del tiempo.

En el siguiente ejemplo, se muestra cómo administrar un objeto de función existente. Primero, crea una función de forma manual y, luego, comienza a administrarla con el Sincronizador de configuración.

1. Crea la función myrole en el espacio de nombres gamestore:

   kubectl create role -n gamestore myrole --verb=get --resource=pods

2. Observa los permisos otorgados por la función myrole:

   kubectl describe role -n gamestore myrole

   Name:         myrole
   Labels:       <none>
   Annotations:  <none>
   PolicyRule:
     Resources  Non-Resource URLs  Resource Names  Verbs
     ---------  -----------------  --------------  -----
     pods       []                 []              [get]
   

   La función solo tiene permiso para get pods.

3. En este punto, la función existe en el clúster, pero el Sincronizador de configuración no lo sabe.

   1. En una terminal, ve a la clonación local de tu repositorio.

   2. Usa el siguiente comando a fin de crear un manifiesto YAML para myrole y guárdalo en un archivo nuevo llamado gamestore-myrole.yaml.

      kubectl get role myrole -n gamestore -o yaml > gamestore-myrole.yaml
      

   3. Edita el archivo gamestore-myrole.yaml.

      1. Quita todos los campos debajo de la clave metadata, excepto name y namespace.
      2. Agrega el verbo list después de get en el campo de lista rules.verbs.

      Guarda los cambios. El archivo resultante tiene el siguiente contenido:

      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        name: myrole
        namespace: gamestore
      rules:
      - apiGroups:
        - ""
        resources:
        - pods
        verbs:
        - get
        - list
      

   4. Confirma el cambio en el repositorio.

   5. Espera unos minutos para que el operador de ConfigManagement detecte la confirmación. Para verificar que la función myrole ahora esté administrada por el Sincronizador de configuración, vuelve a ejecutar kubectl describe.

      kubectl describe role myrole -n gamestore
      

Observa la anotación configmanagement.gke.io/managed: enabled, que indica que el objeto es administrado por el Sincronizador de configuración, y la anotación configsync.gke.io/resource-id, que realiza un seguimiento de la información del grupo, el tipo, el espacio de nombres y el nombre. Observa también las anotaciones que muestran la ruta y el nombre del archivo en el repositorio que causó el cambio de configuración más reciente del objeto, y el hash de Git que representa la confirmación.

Name:         myrole
Labels:       app.kubernetes.io/managed-by=configmanagement.gke.io
              configsync.gke.io/declared-version=v1
Annotations:  config.k8s.io/owning-inventory: config-management-system_root-sync
              configmanagement.gke.io/cluster-name: my-cluster
              configmanagement.gke.io/managed: enabled
              configmanagement.gke.io/source-path: config-sync-quickstart/multirepo/root/gamestore-myrole.yaml
              configmanagement.gke.io/token: 747b843a7ddbd945c0616034a935cf648b58e7b5
              configsync.gke.io/declared-fields: {"f:rules":{}}
              configsync.gke.io/git-context: {"repo":"https://github.com/GoogleCloudPlatform/anthos-config-management-samples","branch":"main","rev":"HEAD"}
              configsync.gke.io/manager: :root
              configsync.gke.io/resource-id: rbac.authorization.k8s.io_role_gamestore_myrole
PolicyRule:
  Resources  Non-Resource URLs  Resource Names  Verbs
  ---------  -----------------  --------------  -----
  pods       []                 []              [get list]

Deja de administrar un objeto administrado

En este ejemplo, se muestra cómo dejar de administrar un objeto que el Sincronizador de configuración administra en la actualidad, como la función myrole en Comienza a administrar un objeto existente.

1. Edita el archivo config-sync-quickstart/multirepo/root/rolebinding-gamestore-webstore-admin.yaml en el clon local de tu repositorio y agrega una sección annotations: que coincida con el texto en negrita que aparece a continuación:

    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      annotations:
        configmanagement.gke.io/managed: disabled
      name: gamestore-webstore-admin
      namespace: gamestore
    subjects:
    - kind: ServiceAccount
      name: ns-reconciler-gamestore
      namespace: config-management-system
    roleRef:
      kind: ClusterRole
      name: webstore-admin
      apiGroup: rbac.authorization.k8s.io
   

   Guarda el archivo.

2. Crea una confirmación de Git con los cambios y envíala al repositorio.

3. Espera unos minutos para que el Sincronizador de configuración detecte la confirmación nueva y la aplique.

4. Usa el siguiente comando para verificar que las anotaciones y etiquetas de RoleBinding gamestore-webstore-admin estén vacías. El Sincronizador de configuración no establece la anotación configmanagement.gke.io/managed en disabled, en el objeto.

   kubectl get rolebinding gamestore-webstore-admin -n gamestore -o yaml
   

   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
     annotations:
     name: gamestore-webstore-admin
     namespace: gamestore
   subjects:
   - kind: ServiceAccount
     name: ns-reconciler-gamestore
     namespace: config-management-system
   roleRef:
     kind: ClusterRole
     name: webstore-admin
     apiGroup: rbac.authorization.k8s.io
   

Después de comprobar que el objeto está inhabilitado, puedes quitar el archivo de configuración de tu repositorio y verificar que el objeto no administrado no se borre del espacio de nombres. Si deseas volver a administrar el objeto, debes volver a agregar su configuración al repositorio. Por esta razón, recomendamos que dejes de administrar los objetos y que dejes sus archivos de configuración en el repositorio.

Ahora que el objeto no está administrado, no se crea ni se vuelve a crear en clústeres nuevos o existentes, y no se quita incluso si existe. Para reanudar la administración de un objeto que dejaste de administrar, consulta el siguiente ejemplo, Reanuda la administración de un objeto que dejaste de administrar.

Reanuda la administración de un objeto que dejaste de administrar

En este ejemplo, se muestra cómo reanudar la administración de un objeto que quitaste de la administración, como en Deja de administrar un objeto existente. Se da por sentado que no quitaste el archivo de configuración para el RoleBinding gamestore-webstore-admin.

1. Si borraste el RoleBinding gamestore-webstore-admin de tu repositorio en la última confirmación, realiza los siguientes pasos.

   1. Usa git revert para revertir la última confirmación:

      git revert HEAD~1
      

      Se te solicitará que confirmes la operación de reversión.

   2. Envía la confirmación de reversión al repositorio.

      git push
      

2. Edita el archivo config-sync-quickstart/multirepo/root/rolebinding-gamestore-webstore-admin.yaml en la clonación local del repositorio y quita la anotación configmanagement.gke.io/managed: disabled. Guarda el archivo.

3. Confirma y envía el cambio. El Sincronizador de configuración hace lo siguiente:

   • Advierte el cambio.
   • Aplica la anotación configmanagement.gke.io/managed: enabled y la anotación configsync.gke.io/resource-id; ahora el objeto está administrado.
   • Aplica la configuración, como sucedería con cualquier objeto administrado.

4. Para verificar si el objeto está administrado, crea una lista de sus anotaciones:

   kubectl get rolebinding gamestore-webstore-admin -n gamestore -o yaml

   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     annotations:
       configmanagement.gke.io/cluster-name: my-cluster
       configmanagement.gke.io/managed: enabled
       configsync.gke.io/resource-id: rbac.authorization.k8s.io_rolebinding_gamestore_gamestore-webstore-admin
   ...
   

Deja de administrar un espacio de nombres

Puedes dejar de administrar un espacio de nombres de la misma manera en que dejas de administrar cualquier tipo de objeto. Si deseas dejar de administrar otros recursos dentro del espacio de nombres, sigue estos pasos:

1. Agrega la anotación configmanagement.gke.io/managed:disabled al archivo de configuración del espacio de nombres y a todos los archivos de configuración en el mismo espacio de nombres. Todos los objetos del espacio de nombres deben tener esta anotación.

2. Confirma y envía tus cambios al repositorio. Espera a que el operador se sincronice con el repositorio.

3. Borra los recursos no administrados del repositorio.

Si hay archivos de configuración administrados dentro de un directorio de espacio de nombres no administrado, el conciliador registra errores, pero la sincronización de los otros archivos continúa con normalidad.

Borra recursos administrados

Cuando quitas un recurso individual de una fuente de información, ese objeto se borra del clúster cuando el Sincronizador de configuración realiza la próxima sincronización desde la fuente de información. Como alternativa, puedes habilitar la propagación de eliminación, que te permite borrar objetos de forma masiva.

Cómo borrar objetos individuales

Con el comportamiento predeterminado del Sincronizador de configuración, cuando quitas un objeto de una fuente de información, ese objeto se borra del clúster cuando el Sincronizador de configuración se sincroniza desde la fuente de información.

Existen varias formas de verificar el estado del Sincronizador de configuración o el estado de objetos específicos:

• Usa nomos status.
• Usa kubectl para examinar los recursos.
• Usa el comando gcloud alpha anthos config sync resources.
• Usa el panel del Sincronizador de configuración.

Borra objetos de forma masiva

De forma predeterminada, borrar un RootSync o RepoSync hace que el Sincronizador de configuración abandone los objetos que se aplicaron anteriormente desde la fuente de información. Como alternativa, puedes habilitar la propagación de eliminación para borrar todos los objetos aplicados anteriormente.

Cuando habilitas la propagación de eliminación en un objeto RootSync o RepoSync y, luego, borras ese objeto, el Sincronizador de configuración borra automáticamente todos los objetos que administraba ese RootSync o RepoSync.

La propagación de eliminación puede facilitar la limpieza de recursos, por ejemplo, si migras a un espacio de nombres o clúster nuevo, realizas una limpieza después de una demo o experimento, o desinstalas una aplicación.

Opciones de propagación de eliminación

La propagación de eliminación está inhabilitada de forma predeterminada. Para habilitar la propagación de la eliminación, debes agregar la anotación configsync.gke.io/deletion-propagation-policy: Foreground a tu objeto RootSync o RepoSync, como en el siguiente ejemplo:

# example-rootsync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: example-rootsync
  namespace: config-management-system
  annotations:
    configsync.gke.io/deletion-propagation-policy: Foreground
spec:
  sourceType: git
  sourceFormat: unstructured
  git:
    repo: https://github.com/GoogleCloudPlatform/anthos-config-management-samples
    branch: init
    dir: config-sync-quickstart/multirepo/root
    auth: none
    period: 30s

Como alternativa, puedes actualizar un RootSync o RepoSync existente para usar la propagación de borrados. Para ello, ejecuta el siguiente comando:

kubectl patch RootSync ROOTSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Foreground"}}}'

kubectl patch RepoSync REPOSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Foreground"}}}'

Para inhabilitar la propagación de la eliminación, quita la anotación o cambia el valor a configsync.gke.io/deletion-propagation-policy: Orphan:

kubectl patch RootSync ROOTSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Orphan"}}}'

kubectl patch RepoSync REPOSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Orphan"}}}'

Cómo propagar la eliminación de objetos

En este ejemplo, se muestra cómo aplicar la propagación de eliminación a un objeto RootSync o RepoSync y, luego, borrar el RootSync o RepoSync para borrar todos los objetos que administraba.

Evita la eliminación de los objetos de Kubernetes

Después de quitar un objeto de Kubernetes de un repositorio de Git administrado por el Sincronizador de configuración, este objeto también se borra del clúster cuando la confirmación nueva se sincroniza con el clúster.

Si deseas evitar que el Sincronizador de configuración borre el objeto cuando se quita su configuración del repositorio de Git, puedes seguir estos pasos:

1. Agrega la anotación client.lifecycle.config.k8s.io/deletion: detach a la configuración del objeto en el repositorio de Git.

2. Confirma y envía el cambio en el repositorio de Git.

3. Espera a que el cambio se sincronice con el clúster.

Después de completar estos pasos, el Sincronizador de configuración no borrará este objeto del clúster cuando se quite su configuración del repositorio de Git, pero otros clientes aún pueden borrarlo.

Ignora un objeto en la fuente de información

Es posible que desees que el Sincronizador de configuración ignore un objeto en tu fuente de información. Por ejemplo, una configuración de función kpt nunca se debe aplicar al clúster.

Para los objetos que deseas que el Sincronizador de configuración ignore, agrega la anotación config.kubernetes.io/local-config: "true" al objeto. Después de agregar esta anotación, el Sincronizador de configuración ignora este objeto como si se quitara de la fuente de información. Los recursos con la anotación local-config establecida en cualquier valor que no sea "false" se tratan como si se estableciera en "true" y se ignoran.