Actualizar y copias de seguridad¶

Cómo desplegar una versión nueva sin sorpresas, cuándo usar dos réplicas y qué copiar para poder restaurar kubelatch. También cubre la clave de cifrado y cómo desinstalar.

Saber cuándo hay una versión nueva¶

En los 30 segundos siguientes al arranque y luego una vez al día, kubelatch lee https://docs.kubelatch.com/releases/latest.json, que dice cuál es la última versión publicada; un intento fallido se repite una hora después. La petición no lleva identificador, ni versión, ni nada de tu instancia (A qué nos comprometemos). Cuando esa versión es más nueva que la tuya, los administradores ven:

• un aviso en la campana, «Hay una versión nueva de kubelatch: 0.31.0.», con el enlace «Cómo actualizar»;
• en «Inicio», una recomendación de la instalación más en la línea bajo el título, que lleva a la lista de salud de «Edición»;
• la fila «Versión» en «Edición»: 0.30.0 · hay 0.31.0 publicada, con «Novedades», que abre las notas de esa versión en Novedades, y el mismo «Cómo actualizar».

«Cómo actualizar» abre esta página. El aviso no lleva contador ni se puede descartar: desaparece al actualizar. Una compilación sin versión (dev) nunca comprueba.

Para comprobar sin esperar al día siguiente, pulsa «Comprobar ahora» en la fila «Versión». Con dos réplicas, solo comprueba en ese momento la que responde; la otra sigue con su comprobación diaria.

KUBELATCH_UPDATE_CHECK=false desactiva la comprobación, y «Versión» pasa a decir comprobación desactivada. En una instalación aislada de internet, KUBELATCH_UPDATE_CHECK_URL la apunta a un espejo interno del documento (Configuración).

Actualizar kubelatch¶

Los comandos usan $MGMT_KUBECONFIG y $KUBELATCH_VERSION, como en Instalar, y el values.yaml con el que instalaste.

1. Lee las notas de la versión nueva y pon esa versión en KUBELATCH_VERSION. La versión del chart es la de kubelatch: el chart trae su imagen.
2. Avisa a los equipos si es horario de trabajo: el rollout corta los exec y port-forward abiertos.

3. Actualiza con los mismos values:

   helm --kubeconfig "$MGMT_KUBECONFIG" upgrade kubelatch oci://ghcr.io/picaportelabs/charts/kubelatch \
     --version "$KUBELATCH_VERSION" -n kubelatch -f values.yaml
   kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch rollout status deploy/kubelatch
   

4. Comprueba la versión en el log (la línea listening lleva version) o con /kubelatch-server version:

   kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec deploy/kubelatch -- /kubelatch-server version
   

5. Si las notas de la versión dicen que cambió el manifiesto de bootstrap, actualízalo en cada cluster: Actualizar el bootstrap. Mientras no lo hagas, el cluster sigue funcionando con lo que su manifiesto permite.

Un cambio de configuración es el mismo helm upgrade con el values.yaml editado. Qué reinicia los pods y qué no:

Qué pasa durante un rollout¶

Con maxSurge: 1 y maxUnavailable: 0, el pod nuevo está Ready (migraciones aplicadas, Postgres accesible) antes de que el viejo empiece a terminar. El pod viejo sigue sirviendo durante shutdownDelaySeconds (5 s por defecto, un preStop que espera) antes de recibir SIGTERM: es lo que tardan kube-proxy y el balanceador en dejar de mandarle conexiones nuevas. Las peticiones nuevas nunca encuentran a nadie escuchando. Si tu balanceador tarda más en dejar de enviar tráfico a un destino, sube shutdownDelaySeconds (como mucho 25).

Pero un rollout corta las conexiones largas en curso. Al recibir SIGTERM, kubelatch:

1. Deja de aceptar conexiones.
2. Da 3 s a las peticiones normales para terminar.
3. Cierra todo exec, attach, port-forward, watch y logs -f abierto, y completa sus filas de auditoría con kubelatch restarting.

terminationGracePeriodSeconds: 60 deja margen para la espera y todo ello. kubectl reintenta solo los watch; un exec o un port-forward hay que relanzarlo.

Volver a iniciar sesión tras la 0.19.0¶

Actualizar a la 0.19.0 o posterior desde una versión anterior cierra una vez la sesión web de todo el mundo: la cookie de sesión cambió de nombre (ahora lleva el prefijo __Host-). Las credenciales, las sesiones de la CLI y los kubeconfigs no se ven afectados.

La política de endurecimiento y CloudNativePG¶

Hasta la 0.59.0, la política de endurecimiento rechaza también los bindings a Roles de namespace cuyo nombre empieza por kubelatch-, y CloudNativePG llama kubelatch-db al Role de la base de datos del chart. Con hardening.enabled: true y postgres.mode: cnpg, la base de datos sigue funcionando, pero el operador deja de gestionarla: ni cambios en el Cluster, ni actualizaciones, ni failover.

La política actual reserva solo los ClusterRoles. Un helm upgrade la instala en el cluster de gestión. En un cluster donde la aplicaste a mano, vuelve a aplicar el fichero del chart nuevo.

El operador retoma el Cluster en su siguiente reintento, hasta unos 17 minutos después, y aplica todos los cambios pendientes. Un imageName nuevo, por ejemplo, reinicia los pods de la base de datos; con una sola instancia, kubelatch no está disponible hasta que el pod vuelve. Para saber si hay una imagen pendiente antes de actualizar, compara estas dos:

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch get cluster kubelatch-db -o jsonpath='{.spec.imageName}{"\n"}'
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch get pods -l cnpg.io/cluster=kubelatch-db -o jsonpath='{.items[*].spec.containers[0].image}{"\n"}'

Para elegir el momento en vez de esperar al reintento, anota el Cluster cuando la política ya esté aplicada, y el operador lo retoma al momento:

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch annotate cluster kubelatch-db kubelatch.io/reconcile="$(date +%s)" --overwrite

Migraciones¶

Las migraciones se aplican al arrancar, con un lock de Postgres: con dos réplicas, una migra y la otra espera. Son solo hacia delante. Para volver a una versión anterior del binario, restaura la base de datos de la copia previa a la actualización (helm rollback solo devuelve los manifiestos).

Dos réplicas¶

replicas: 2

Con dos réplicas o más, el chart añade un PodDisruptionBudget con minAvailable: 1: un drenado de nodo deja siempre un pod sirviendo. Cómo repartir los pods, qué comparten las réplicas y qué se guarda cada una (los límites de peticiones, una clave pegada en «Edición», la última sincronización que se muestra, el documento de descubrimiento del proveedor OIDC) está en Varias réplicas.

Con la base de datos en CloudNativePG, su alta disponibilidad va aparte: De una instancia a tres.

Copias de seguridad¶

Necesitas dos cosas, y por separado:

1. Haz un pg_dump diario, o usa los snapshots de tu servicio gestionado. Con CloudNativePG, activa sus copias: Copias de seguridad.
2. Guarda la clave en el gestor de secretos, aparte de las copias.
3. Prueba una restauración antes de necesitarla: restaura en otro Postgres y arranca un kubelatch apuntando a él con la misma clave.

Ajustes de Postgres¶

• idle_in_transaction_session_timeout: el reconciliador mantiene una transacción abierta durante toda una pasada (hasta 2 minutos de llamadas al cluster, más la escritura). Si tu Postgres tiene ese timeout, debe superar los 3 minutos. Si no, las pasadas largas fallan con terminating connection y el cluster queda en «Error» hasta la siguiente.
• Roles: un único rol hace las migraciones y el tráfico, y es el dueño de las tablas. No reutilices el rol de kubelatch para nada más.
• Tamaño: ver Auditoría y retención.

Si se pierde o se cambia la clave de cifrado¶

KUBELATCH_ENCRYPTION_KEY firma las sesiones y cifra los tokens de las ServiceAccounts de cada cluster. kubelatch solo admite una clave a la vez: no hay rotación con dos claves. Cambiarla (o perderla) tiene estos efectos:

• Todo el mundo vuelve a iniciar sesión: las cookies anteriores no valen.
• Ningún cluster puede usarse hasta renovar sus tokens. En «Clusters» aparecen en «Error» con could not prepare the reconciler client: rotate the cluster's tokens, la tarjeta «Namespaces» y conceder un permiso responden 409 pidiendo rotar los tokens, y «Reconciliar» responde 502 con el mismo motivo, que se ve en la página del cluster. kubectl recibe un 503 con kubelatch cannot query its database; el log dice proxy: load cluster.
• Una clave de licencia pegada en «Edición» no se puede abrir: kubelatch funciona como Free, con un aviso en «Edición», hasta que vuelvas a instalar la clave. La auditoría ya recogida se conserva, con la retención que configuraste; solo deja de servirse lo anterior a 24 horas hasta que una clave vuelva a verificar. Una clave en KUBELATCH_LICENSE no se ve afectada.
• No cambian: contraseñas (argon2id), credenciales klt_ (SHA-256), permisos y auditoría.

Si solo la perdiste del gestor de secretos, recupérala del Secret que carga el pod y no hace falta rotar. De tu Secret, o del que generó el chart (secrets.generateEncryptionKey):

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch get secret kubelatch-secrets -o jsonpath='{.data.KUBELATCH_ENCRYPTION_KEY}' | base64 -d
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch get secret kubelatch-encryption-key -o jsonpath='{.data.encryption-key}' | base64 -d

Para cambiarla a propósito, o si ya no está en ninguna parte:

1. Genera una clave nueva: head -c32 /dev/urandom | base64.

2. Pon la clave nueva en su sitio y guárdala en el gestor de secretos:

   • Con tu propio Secret, actualiza KUBELATCH_ENCRYPTION_KEY en kubelatch-secrets.
   • Con la clave generada, borra el Secret kubelatch-encryption-key y ejecuta helm upgrade con los mismos values: el chart genera una nueva, que copias al gestor de secretos.

   En los dos casos, reinicia los pods: el cambio de un Secret no redespliega solo. Espera a que termine el rollout antes de seguir. Mientras dura, conviven pods con la clave vieja y la nueva, y unos tokens guardados a mitad podrían no descifrarse en el otro pod.

   kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch rollout restart deploy/kubelatch
   kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch rollout status deploy/kubelatch
   

3. Para cada cluster, abre su página en «Clusters» y elige «Reenrolar» en su menú: genera el comando de enrolamiento y ejecútalo con el kubeconfig de ese cluster. Volver a aplicar el bootstrap va incluido. Ver Registrar un cluster.

4. Comprueba que cada cluster vuelve a «Listo».

Desinstalar¶

1. Borra cada cluster desde «Clusters», que limpia su RBAC, y quita después su bootstrap (Eliminar un cluster). Si kubelatch ya no llega a él, límpialo todo en el propio cluster:

   kubectl --kubeconfig <kubeconfig-del-cluster> delete -l app.kubernetes.io/managed-by=kubelatch clusterroles,clusterrolebindings,rolebindings -A
   kubectl --kubeconfig <kubeconfig-del-cluster> delete namespace kubelatch-system
   kubectl --kubeconfig <kubeconfig-del-cluster> delete validatingadmissionpolicybinding,validatingadmissionpolicy kubelatch-reconciler-jail
   

   En los dos casos, si aplicaste a mano la política de endurecimiento, bórrala también: no lleva las etiquetas de kubelatch. En el cluster de gestión, hardening.enabled la quita con la release.

   kubectl --kubeconfig <kubeconfig-del-cluster> delete validatingadmissionpolicybinding,validatingadmissionpolicy kubelatch-bindings
   

2. Desinstala la release:

   helm --kubeconfig "$MGMT_KUBECONFIG" uninstall kubelatch -n kubelatch
   

   Borra todo lo que creó el chart salvo lo que guarda datos o no se puede volver a crear, que se queda en su sitio:

   Se queda	Bórralo con
   La clave de cifrado generada (kubelatch-encryption-key)	kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch delete secret kubelatch-encryption-key
   La base de datos de CloudNativePG (Cluster kubelatch-db, sus volúmenes y, con las copias activadas, su ObjectStore y su ScheduledBackup)	Desinstalar y los datos
   Tus Secrets y el namespace	kubectl --kubeconfig "$MGMT_KUBECONFIG" delete namespace kubelatch (borra también todo lo anterior: el Cluster, sus volúmenes y la clave generada, así que exporta antes lo que necesites)

3. Borra tu propia base de datos de Postgres, si era externa, después de exportar la auditoría si la necesitas.