Este documento ha sido traducido utilizando tecnología de traducción automática. Si bien nos esforzamos por proporcionar traducciones precisas, no ofrecemos garantías sobre la integridad, precisión o confiabilidad del contenido traducido. En caso de discrepancia, la versión original en inglés prevalecerá y constituirá el texto autorizado.

certificado k3s

Certificados de líder/seguidor

Los certificados de líder/seguidor de K3s son válidos durante 365 días a partir de su fecha de emisión. Cualquier certificado que esté caducado o que esté a 120 días de caducar se renueva automáticamente cada vez que K3s se inicia. Esta renovación reutiliza las claves existentes y extiende la duración de los certificados existentes. Si deseas generar nuevos certificados y claves, en lugar de extender la validez de los certificados existentes, utiliza el subcomando rotate documentado a continuación.

Cuando un certificado está a 120 días de caducar, se crea un Evento de Advertencia de Kubernetes con reason: CertificateExpirationWarning, relacionado con el Nodo que utiliza el certificado.

Antes de las versiones de mayo de 2025 (v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.30.13+k3s1), las alertas y la rotación se activaban a los 90 días, en lugar de a los 120 días.

Comprobando fechas de caducidad

Puerta de Versión

El formato de salida es configurable a partir de las versiones de enero de 2025: v1.32.0+k3s1, v1.31.5+k3s1, v1.30.9+k3s1, v1.30.13+k3s1.

Un nuevo formato con más información está disponible a partir de las versiones de mayo de 2025: v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.29.13+k3s1.

Para comprobar los certificados del nodo y su fecha de caducidad, utiliza el k3s certificate check --output table:

FILENAME                    SUBJECT                     USAGES       EXPIRES                  RESIDUAL TIME   STATUS
--------                    -------                     ------       -------                  -------------   ------
client-kube-proxy.crt       system:kube-proxy           ClientAuth   Jun 09, 2026 10:17 UTC   1 year          OK
client-kube-proxy.crt       k3s-client-ca@1749464211    CertSign     Jun 07, 2035 10:16 UTC   10 years        OK
client-kubelet.crt          system:node:ip-10-11-0-14   ClientAuth   Jun 09, 2026 10:17 UTC   1 year          OK
client-kubelet.crt          k3s-client-ca@1749464211    CertSign     Jun 07, 2035 10:16 UTC   10 years        OK
serving-kubelet.crt         ip-10-11-0-14               ServerAuth   Jun 09, 2026 10:17 UTC   1 year          OK
serving-kubelet.crt         k3s-server-ca@1749464211    CertSign     Jun 07, 2035 10:16 UTC   10 years        OK
client-k3s-controller.crt   system:k3s-controller       ClientAuth   Jun 09, 2026 10:17 UTC   1 year          OK
client-k3s-controller.crt   k3s-client-ca@1749464211    CertSign     Jun 07, 2035 10:16 UTC   10 years        OK
MISMO CERTIFICADO DOS VECES

Cada archivo de certificado (`FILENAME ` columna) contiene al menos dos certificados: el certificado de cliente/servidor (o entidad final), cualquier certificado de Autoridad de Certificación intermedia y el certificado de Autoridad de Certificación raíz.

En caso de salida inesperada, asegúrate de que estás especificando el directorio de datos correcto con la opción --data-dir (si utilizas un directorio de datos personalizado), o utiliza la opción --debug para obtener salida adicional del proceso de verificación.

Rotando Certificados de líder/seguidor

Para rotar certificados de líder/seguidor manualmente, utiliza el subcomando k3s certificate rotate:

# Stop K3s
systemctl stop k3s

# Rotate certificates
k3s certificate rotate

# Start K3s
systemctl start k3s

Los certificados individuales o las listas de certificados pueden ser rotados especificando el nombre del certificado:

k3s certificate rotate --service <SERVICE>,<SERVICE>

Los siguientes certificados pueden ser rotados: admin, api-server, controller-manager, scheduler, k3s-controller, k3s-server, cloud-controller, etcd, auth-proxy, kubelet, kube-proxy.

Certificados de Autoridad de Certificación (CA)

Kubernetes requiere varios certificados CA para un funcionamiento adecuado. Para más información sobre cómo Kubernetes utiliza los certificados CA, consulta la documentación de Kubernetes Certificados y Requisitos PKI.

Por defecto, K3s genera certificados CA autofirmados durante el inicio del primer nodo del servidor. Estos certificados CA son válidos durante 10 años a partir de la fecha de emisión y no se renuevan automáticamente.

Los certificados y claves CA autorizados se almacenan dentro de la clave de inicio del datastore, cifrados utilizando el token del servidor como la frase de paso de PBKDF2 con AES256-GCM y HMAC-SHA1. Copias de los certificados y claves CA se extraen al disco durante el inicio del servidor K3s. Cualquier servidor puede generar certificados de entidad final para los nodos a medida que se unen al clúster, y los controladores de Kubernetes API de Certificados pueden emitir certificados adicionales en tiempo de ejecución.

Para rotar los certificados y claves CA, utiliza el comando k3s certificate rotate-ca. El comando realiza comprobaciones de integridad para confirmar que los certificados y claves actualizados son utilizables. Si los datos actualizados son aceptables, se actualiza la clave de iniciar cifrada del datastore, y los nuevos certificados y claves se utilizarán la próxima vez que K3s se inicie. Si se encuentran problemas al validar los certificados y claves, se informa de un error al registro del sistema y la operación se cancela sin cambios.

Puerta de Versión

El soporte para el comando k3s certificate rotate-ca y la capacidad de utilizar certificados CA firmados por una CA externa está disponible a partir de las versiones de 2023-02 (v1.26.2+k3s1, v1.25.7+k3s1, v1.24.11+k3s1, v1.23.17+k3s1).

Uso de Certificados CA Personalizados

Precauciones Contra la Reutilización de CA

No se recomienda compartir CAs Raíz o Intermedias entre múltiples clústeres, ni utilizar una CA privada existente como tu CA de clúster.

Cuando múltiples clústeres comparten una raíz de confianza común, cualquier certificado de cliente o servidor emitido por un clúster también será confiable por todos los demás clústeres, ya que todos los certificados se encadenan hasta el mismo ancla de confianza: la Autoridad de Certificación Raíz común. Esto significa que cualquier usuario con un certificado de cliente válido (o kubeconfig) para un clúster también puede autenticarse en otros clústeres, y cualquier RBAC que coincida con el usuario o grupo de un cliente también se aplica en esos otros clústeres. De manera similar, los certificados de servidor emitidos por un clúster también son de confianza en todos los demás clústeres, y por toda otra infraestructura o clientes que confíen en esa CA raíz.

Kubernetes no admite el uso de Listas de Revocación de Certificados. Si alguna vez necesitas revocar un certificado por cualquier motivo (por ejemplo, debido a un kubeconfig de administrador comprometido), debes realizar un reemplazo completo de la Autoridad de Certificación del clúster para invalidar la confianza del certificado.

Uso de Certificados CA Personalizados

Si se encuentran certificados y claves de CA en la ubicación correcta durante el primer inicio del servidor en el clúster, se omite la generación automática de certificados CA.

Un script de ejemplo para pre-crear los certificados y claves apropiados está disponible en el repositorio de K3s en contrib/util/generate-custom-ca-certs.sh. Este script debe ejecutarse antes de iniciar K3s por primera vez, y creará un conjunto completo de certificados de CA de entidad final firmados por certificados CA raíz e intermedios comunes. Si tienes una CA raíz o intermedia existente, este script puede ser utilizado (o usado como punto de partida) para crear los certificados de CA correctos para aprovisionar un clúster de K3s con PKI enraizado en una autoridad existente.

Los archivos de Autoridad de Certificación personalizados deben colocarse en /var/lib/rancher/k3s/server/tls. Los siguientes archivos son requeridos:

  • server-ca.crt

  • server-ca.key

  • client-ca.crt

  • client-ca.key

  • request-header-ca.crt

  • request-header-ca.key
    // nota: los archivos etcd son requeridos incluso si etcd embebido no está en uso.

  • etcd/peer-ca.crt

  • etcd/peer-ca.key

  • etcd/server-ca.crt

  • etcd/server-ca.key
    // nota: Esta es la clave privada utilizada para firmar los tokens de cuenta de servicio. No tiene un certificado correspondiente.

  • service.key

Topología de CA Personalizada

Los certificados de CA personalizados generados por el script de ejemplo tienen la siguiente topología:

graph TD root("CA Raíz") intermediate("CA Intermedia") server-ca("CA de Servidor") client-ca("CA de Cliente") request-header-ca("CA de Agregación de API") etcd-peer-ca("CA de Pares de etcd") etcd-server-ca("CA de Servidor de etcd") root-hash>"Join token CA hash"] kube-server-certs[["Kubernetes servers
(control-plane and kubelet listeners)"]] kube-client-certs[["Kubernetes clients
(apiserver and kubelet clients)"]] request-header-certs[["Kubernetes API aggregation
(apiserver proxy client)"]] etcd-peer-certs[["etcd peer client/server
(etcd replication)"]] etcd-server-certs[["etcd client/server certificates
(Kubernetes <-> etcd)"]] root -.-|SHA256| root-hash root ---> intermediate intermediate --> server-ca ==> kube-server-certs intermediate --> client-ca ==> kube-client-certs intermediate --> request-header-ca ==> request-header-certs intermediate --> etcd-peer-ca ==> etcd-peer-certs intermediate --> etcd-server-ca ==> etcd-server-certs

Usando el script de ejemplo

Importante

Si deseas firmar los certificados de CA del clúster con una CA raíz existente utilizando el script de ejemplo, debes colocar los archivos raíz e intermedios en el directorio de destino antes de ejecutar el script. Si los archivos no existen, el script creará nuevos certificados de CA raíz e intermedios.

Si deseas utilizar únicamente un certificado CA raíz existente, proporciona los siguientes archivos:

  • root-ca.pem

  • root-ca.key

Si deseas utilizar certificados CA raíz e intermedios existentes, proporciona los siguientes archivos:

  • root-ca.pem

  • intermediate-ca.pem

  • intermediate-ca.key

El script de ejemplo utiliza las CAs proporcionadas como raíz para todos los paquetes CA del clúster: Servidor, Cliente, Agregación de API y etcd Peer/Servidor. Para casos de uso avanzados, como utilizar las CAs proporcionadas solo para paquetes seleccionados, o utilizar diferentes CAs para diferentes paquetes, el script de ejemplo debe ser modificado para satisfacer las necesidades específicas de tu organización.

Para utilizar el script de ejemplo para generar certificados y claves personalizados antes de iniciar K3s, ejecuta los siguientes comandos:

# Create the target directory for cert generation.
mkdir -p /var/lib/rancher/k3s/server/tls

# Copy your root CA cert and intermediate CA cert+key into the correct location for the script.
# For the purposes of this example, we assume you have existing root and intermediate CA files in /etc/ssl.
# If you do not have an existing root and/or intermediate CA, the script will generate them for you.
cp /etc/ssl/certs/root-ca.pem /etc/ssl/certs/intermediate-ca.pem /etc/ssl/private/intermediate-ca.key /var/lib/rancher/k3s/server/tls

# Generate custom CA certs and keys.
curl -sL https://github.com/k3s-io/k3s/raw/main/contrib/util/generate-custom-ca-certs.sh | bash -

Si el comando se completa con éxito, puedes instalar y/o iniciar K3s por primera vez. Si el script generó archivos CA raíz y/o intermedios, debes hacer una copia de seguridad de estos archivos para que puedan ser reutilizados si es necesario rotar los certificados CA en una fecha posterior.

Rotación de Certificados CA Personalizados

Para rotar certificados CA personalizados, utiliza el subcomando k3s certificate rotate-ca. Los archivos actualizados deben ser ubicados en un directorio temporal, cargados en el datastore, y K3s debe reiniciarse en todos los nodos para utilizar los certificados actualizados.

No debes sobrescribir los datos actualmente en uso en /var/lib/rancher/k3s/server/tls.
Prepara los certificados y claves actualizados en un directorio separado.

Un clúster que ha sido iniciado con certificados CA personalizados puede renovar o rotar los certificados y claves CA de manera no disruptiva, siempre que se utilice la misma CA raíz.

Si se requiere una nueva CA raíz, la rotación será disruptiva. La opción k3s certificate rotate-ca --force debe ser utilizada, todos los nodos que se unieron con un token seguro (incluidos los servidores) deberán ser reconfigurados para utilizar el nuevo valor del token, y los pods deberán ser reiniciados para confiar en la nueva CA raíz.

Usando el script de ejemplo

El script de ejemplo generate-custom-ca-certs.sh vinculado arriba también puede ser utilizado para generar certificados actualizados en un nuevo directorio temporal, copiando archivos en la ubicación correcta y configurando la variable de entorno DATA_DIR. Para utilizar el script de ejemplo para generar certificados y claves actualizados, ejecuta los siguientes comandos:

# Create a temporary directory for cert generation.
mkdir -p /opt/k3s/server/tls

# Copy your root CA cert and intermediate CA cert+key into the correct location for the script.
# Non-disruptive rotation requires the same root CA that was used to generate the original certificates.
# If the original files are still in the data directory, you can just run:
cp /var/lib/rancher/k3s/server/tls/root-ca.* /var/lib/rancher/k3s/server/tls/intermediate-ca.* /opt/k3s/server/tls

# Copy the current service-account signing key, so that existing service-account tokens are not invalidated.
cp /var/lib/rancher/k3s/server/tls/service.key /opt/k3s/server/tls

# Generate updated custom CA certs and keys.
curl -sL https://github.com/k3s-io/k3s/raw/main/contrib/util/generate-custom-ca-certs.sh | DATA_DIR=/opt/k3s bash -

# Load the updated CA certs and keys into the datastore.
k3s certificate rotate-ca --path=/opt/k3s/server

Si el comando rotate-ca devuelve un error, revisa el registro del servicio en busca de errores. Si el comando se completa con éxito, reinicia K3s en todos los nodos del clúster: primero los servidores, luego los agentes.

Si utilizaste la opción --force o cambiaste la CA raíz, asegúrate de que cualquier nodo que se unió con un token seguro sea reconfigurado para utilizar el nuevo valor del token, antes de ser reiniciado. El token puede ser almacenado en un .env archivo, unidad de systemd o config.yaml, dependiendo de cómo se configuró el nodo durante la instalación inicial.

Rotación de Certificados CA Autofirmados

Para rotar los certificados CA autofirmados generados por K3s, utiliza el subcomando k3s certificate rotate-ca. Los archivos actualizados deben ser preparados en un directorio temporal, cargados en el almacén de datos, y K3s debe ser reiniciado en todos los nodos para utilizar los certificados actualizados.

No debes sobrescribir los datos actualmente en uso en /var/lib/rancher/k3s/server/tls.
Prepara los certificados y claves actualizados en un directorio separado.

Si el clúster se ha iniciado con certificados CA autofirmados por defecto, la rotación será disruptiva. Todos los nodos que se unieron con un token seguro necesitarán ser reconfigurados para confiar en el nuevo hash CA. Si los nuevos certificados CA no están firmados cruzadamente por los antiguos certificados CA, necesitarás usar la opción --force para omitir las comprobaciones de integridad, y los pods deberán ser reiniciados para confiar en la nueva CA raíz.

Topología CA por defecto

Los certificados CA autofirmados por defecto tienen la siguiente topología:

graph TD + server-ca("CA del Servidor") + client-ca("CA del Cliente") + request-header-ca("CA de Agregación de API") + etcd-peer-ca("CA de Pares de etcd") + etcd-server-ca("CA del Servidor etcd") root-hash>"Join token CA hash"] kube-server-certs[["Kubernetes servers
(control-plane and kubelet listeners)"]] kube-client-certs[["Kubernetes clients
(apiserver and kubelet clients)"]] request-header-certs[["Kubernetes API aggregation
(apiserver proxy client)"]] etcd-peer-certs[["etcd peer client/server
(etcd replication)"]] etcd-server-certs[["etcd client/server certificates
(Kubernetes <-> etcd)"]] server-ca -.-|SHA256| root-hash server-ca ===> kube-server-certs client-ca ===> kube-client-certs request-header-ca ===> request-header-certs etcd-peer-ca ===> etcd-peer-certs etcd-server-ca ===> etcd-server-certs

Al rotar las CAs autofirmadas por defecto, se puede utilizar una topología de certificado modificada con CAs intermedias y una nueva CA raíz firmada cruzadamente por la antigua CA para que haya una cadena de confianza continua entre las CAs antiguas y nuevas:

graph TD + server-ca-old("CA del Servidor
(antigua)") + client-ca-old("CA del Cliente
(antigua)") + request-header-ca-old("CA de Agregación de API
(antigua)") + etcd-peer-ca-old("CA de Pares de etcd
(antigua)") + etcd-server-ca-old("CA del Servidor etcd
(antigua)") root-hash>"Join token CA hash"] server-ca-xsigned("CA del Servidor
(firmada cruzadamente)") + client-ca-xsigned("CA del Cliente
(firmada cruzadamente)") + request-header-ca-xsigned("CA de Agregación de API
(firmada cruzadamente)") + etcd-peer-ca-xsigned("CA de Pares de etcd
(firmada cruzadamente)") + etcd-server-ca-xsigned("CA del Servidor etcd
(firmada cruzadamente)") server-ca-ssigned("Server CA
(self-signed)") client-ca-ssigned("Client CA
(self-signed)") request-header-ca-ssigned("API Aggregation CA
(self-signed)") etcd-peer-ca-ssigned("etcd Peer CA
(self-signed)") etcd-server-ca-ssigned("etcd Server CA
(self-signed)") server-ca("Intermedia
CA del Servidor") + client-ca("Intermedia
CA del Cliente") + request-header-ca("Intermedia
CA de Agregación de API") + etcd-peer-ca("Intermedia
CA de Pares de etcd") + etcd-server-ca("Intermedia
CA del Servidor etcd") kube-server-certs[["Kubernetes servers
(control-plane and kubelet listeners)"]] kube-client-certs[["Kubernetes clients
(apiserver and kubelet clients)"]] request-header-certs[["Kubernetes API aggregation
(apiserver proxy client)"]] etcd-peer-certs[["etcd peer client/server
(etcd replication)"]] etcd-server-certs[["etcd client/server certificates
(Kubernetes <-> etcd)"]] server-ca-ssigned -.-|SHA256| hash-raíz + server-ca-ssigned --> server-ca ==> kube-server-certs + server-ca-old --> server-ca-xsigned --> server-ca + client-ca-ssigned --> client-ca ==> kube-client-certs + client-ca-old --> client-ca-xsigned --> client-ca + request-header-ca-ssigned --> request-header-ca ==> request-header-certs + request-header-ca-old --> request-header-ca-xsigned --> request-header-ca + etcd-peer-ca-ssigned --> etcd-peer-ca ==> etcd-peer-certs + etcd-peer-ca-old --> etcd-peer-ca-xsigned --> etcd-peer-ca + etcd-server-ca-ssigned --> etcd-server-ca ==> etcd-server-certs + etcd-server-ca-old --> etcd-server-ca-xsigned --> etcd-server-ca

Uso del script de ejemplo

Un script de ejemplo para crear certificados CA y claves actualizadas firmadas cruzadamente por las CAs existentes está disponible en el repositorio de K3s en contrib/util/rotate-default-ca-certs.sh.

Para usar el script de ejemplo para generar certificados autofirmados actualizados que estén firmados cruzadamente por las CAs existentes, ejecuta los siguientes comandos:

# Create updated CA certs and keys, cross-signed by the current CAs.
# This script will create a new temporary directory containing the updated certs, and output the new token values.
curl -sL https://github.com/k3s-io/k3s/raw/main/contrib/util/rotate-default-ca-certs.sh | bash -

# Load the updated certs into the datastore; see the script output for the updated token values.
k3s certificate rotate-ca --path=/var/lib/rancher/k3s/server/rotate-ca

Si el comando rotate-ca devuelve un error, revisa el registro del servicio en busca de errores. Si el comando se completa con éxito, reinicia K3s en todos los nodos del clúster: primero los servidores, luego los agentes.

Asegúrate de que cualquier nodo que se unió con un token seguro, incluidos otros nodos de servidor, esté reconfigurado para usar el nuevo valor del token antes de ser reiniciado. El token puede ser almacenado en un .env archivo, una unidad de systemd o config.yaml, dependiendo de cómo se configuró el nodo durante la instalación inicial.

Rotación de la Clave del Emisor de la Cuenta de Servicio

La clave del emisor de la cuenta de servicio es una clave privada RSA utilizada para firmar tokens de cuenta de servicio. Al rotar la clave del emisor de la cuenta de servicio, al menos una clave antigua debe ser retenida en el archivo para que los tokens de cuenta de servicio existentes no se invaliden. Se puede rotar de forma independiente de las CAs del clúster utilizando el k3s certificate rotate-ca para instalar solo un archivo service.key actualizado que incluya tanto las claves nuevas como las antiguas.

No debes sobrescribir los datos actualmente en uso en /var/lib/rancher/k3s/server/tls.
Prepara la clave actualizada en un directorio separado.

Por ejemplo, para rotar solo la clave del emisor de la cuenta de servicio, ejecuta los siguientes comandos:

# Create a temporary directory for cert generation
mkdir -p /opt/k3s/server/tls

# Check OpenSSL version
openssl version | grep -qF 'OpenSSL 3' && OPENSSL_GENRSA_FLAGS=-traditional

# Generate a new key
openssl genrsa ${OPENSSL_GENRSA_FLAGS:-} -out /opt/k3s/server/tls/service.key 2048

# Append the existing key to avoid invalidating current tokens
cat /var/lib/rancher/k3s/server/tls/service.key >> /opt/k3s/server/tls/service.key

# Load the updated key into the datastore
k3s certificate rotate-ca --path=/opt/k3s/server

Es normal ver advertencias para archivos que no se están actualizando. Si el comando rotate-ca devuelve un error, revisa el registro del servicio en busca de errores. Si el comando se completa con éxito, reinicia K3s en todos los servidores del clúster. No es necesario reiniciar agentes ni reiniciar ningún pod.