|
Este documento foi traduzido usando tecnologia de tradução automática de máquina. Sempre trabalhamos para apresentar traduções precisas, mas não oferecemos nenhuma garantia em relação à integridade, precisão ou confiabilidade do conteúdo traduzido. Em caso de qualquer discrepância, a versão original em inglês prevalecerá e constituirá o texto official. |
certificado k3s
Certificados de Cliente e Servidor
Os certificados de cliente e servidor K3s são válidos por 365 dias a partir da data de emissão.
Quaisquer certificados que estejam expirados ou dentro de 120 dias de expiração são renovados automaticamente toda vez que o K3s é iniciado.
Essa renovação reutiliza as chaves existentes e estende a validade dos certificados existentes.
Se você deseja gerar novos certificados e chaves, em vez de estender a validade dos certificados existentes, use o subcomando rotate documentado abaixo.
Quando um certificado está dentro de 120 dias de expiração, um Evento de Aviso do Kubernetes com reason: CertificateExpirationWarning é criado, com relação ao Nó que usa o certificado.
Antes das versões de maio de 2025 (v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.30.13+k3s1), alertas e rotação eram acionados em 90 dias, em vez de 120 dias.
Verificando datas de expiração
|
Portão de Versão
O formato de saída é configurável a partir das versões de janeiro de 2025: v1.32.0+k3s1, v1.31.5+k3s1, v1.30.9+k3s1, v1.30.13+k3s1. Um novo formato com mais informações está disponível a partir das versões de maio de 2025: v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.29.13+k3s1. |
Para verificar os certificados do nó e sua data de expiração, use o 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|
MESMO CERTIFICADO DUAS VEZES
Cada arquivo de certificado (`NOME_DO_ARQUIVO ` coluna) contém pelo menos dois certificados – o certificado de entidade final do cliente/servidor, quaisquer certificados intermediários da Autoridade Certificadora e o certificado da Autoridade Certificadora raiz. |
Em caso de saída inesperada, certifique-se de que está especificando o diretório de dados correto com a flag --data-dir (se estiver usando um diretório de dados personalizado), ou use a flag --debug para obter saída adicional do processo de verificação.
Rotacionando Certificados de Cliente e Servidor
Para rotacionar certificados de cliente e servidor manualmente, use o subcomando k3s certificate rotate:
# Stop K3s
systemctl stop k3s
# Rotate certificates
k3s certificate rotate
# Start K3s
systemctl start k3sCertificados individuais ou listas de certificados podem ser rotacionados especificando o nome do certificado:
k3s certificate rotate --service <SERVICE>,<SERVICE>Os seguintes certificados podem ser rotacionados: admin, api-server, controller-manager, scheduler, k3s-controller, k3s-server, cloud-controller, etcd, auth-proxy, kubelet, kube-proxy.
Certificados da Autoridade de Certificação (CA)
O Kubernetes requer um número de certificados CA para operação adequada. Para mais informações sobre como o Kubernetes utiliza certificados CA, consulte a documentação do Kubernetes Certificados e Requisitos PKI.
Por padrão, o K3s gera certificados CA autoassinados durante a inicialização do primeiro nó servidor. Esses certificados CA são válidos por 10 anos a partir da data de emissão e não são renovados automaticamente.
Os certificados e chaves CA autoritativos são armazenados dentro da chave de inicialização do datastore, criptografados usando o token do servidor como a frase secreta PBKDF2 com AES256-GCM e HMAC-SHA1. Cópias dos certificados e chaves CA são extraídas para o disco durante a inicialização do servidor K3s. Qualquer servidor pode gerar certificados de entidade final para os nós à medida que se juntam ao cluster, e os controladores do Kubernetes API de Certificados podem emitir certificados adicionais em tempo de execução.
Para rotacionar certificados e chaves CA, use o comando k3s certificate rotate-ca.
O comando realiza verificações de integridade para confirmar que os certificados e chaves atualizados são utilizáveis.
Se os dados atualizados forem aceitáveis, a chave de inicialização criptografada do datastore é atualizada, e os novos certificados e chaves serão usados na próxima vez que o K3s iniciar.
Se problemas forem encontrados ao validar os certificados e chaves, um erro é relatado ao log do sistema e a operação é cancelada sem alterações.
|
Portão de Versão
O suporte para o comando |
Usando Certificados CA Personalizados
Cuidado com a Reutilização de CAs
|
Não é recomendado compartilhar CAs Raiz ou Intermediárias entre múltiplos clusters, ou usar uma CA privada existente como sua CA de cluster. |
Quando múltiplos clusters compartilham uma raiz de confiança comum, quaisquer certificados de cliente ou servidor emitidos por um cluster também serão confiáveis por todos os outros clusters, já que todos os certificados se encadeiam até a mesma âncora de confiança – a Autoridade de Certificação Raiz comum. Isso significa que qualquer usuário com um certificado de cliente válido (ou kubeconfig) para um cluster também pode se autenticar em outros clusters, e qualquer RBAC que corresponda ao usuário ou grupo de um cliente também é aplicado nesses outros clusters. Da mesma forma, os certificados de servidor emitidos por um cluster também são confiáveis em todos os outros clusters e por toda a infraestrutura ou clientes que confiam naquela CA raiz.
O Kubernetes não suporta o uso de lista de revogação de certificados. Se você precisar revogar um certificado por qualquer motivo (por exemplo, devido a um kubeconfig de administrador comprometido), deve realizar uma substituição completa da Autoridade Certificadora do cluster para invalidar a confiança no certificado.
Usando Certificados CA Personalizados
Se os certificados e chaves da CA forem encontrados no local correto durante a inicialização do primeiro servidor no cluster, a geração automática de certificados da CA será ignorada.
Um script de exemplo para pré-criar os certificados e chaves apropriados está disponível no repositório K3s em contrib/util/generate-custom-ca-certs.sh.
Este script deve ser executado antes de iniciar o K3s pela primeira vez e criará um conjunto completo de certificados CA de entidade final assinados por certificados CA raiz e intermediários comuns.
Se você tiver uma CA raiz ou intermediária existente, este script pode ser usado (ou usado como ponto de partida) para criar os certificados CA corretos para provisionar um cluster K3s com PKI enraizada em uma autoridade existente.
Os arquivos da Autoridade Certificadora personalizada devem ser colocados em /var/lib/rancher/k3s/server/tls. Os seguintes arquivos são necessários:
-
server-ca.crt -
server-ca.key -
client-ca.crt -
client-ca.key -
request-header-ca.crt -
request-header-ca.key
// nota: arquivos etcd são necessários mesmo que o etcd embutido não esteja em uso. -
etcd/peer-ca.crt -
etcd/peer-ca.key -
etcd/server-ca.crt -
etcd/server-ca.key
// nota: Esta é a chave privada usada para assinar tokens de conta de serviço. Não possui um certificado correspondente. -
service.key
Topologia da CA Personalizada
Os Certificados CA Personalizados gerados pelo script de exemplo têm a seguinte topologia:
(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 o Script de Exemplo
|
Importante
Se você quiser assinar os certificados CA do cluster com uma CA raiz existente usando o script de exemplo, deve colocar os arquivos raiz e intermediários no diretório de destino antes de executar o script. Se os arquivos não existirem, o script criará novos certificados CA raiz e intermediários. |
Se você quiser usar apenas um certificado CA raiz existente, forneça os seguintes arquivos:
-
root-ca.pem -
root-ca.key
Se você quiser usar certificados CA raiz e intermediários existentes, forneça os seguintes arquivos:
-
root-ca.pem -
intermediate-ca.pem -
intermediate-ca.key
O script de exemplo usa os CAs fornecidos como raiz para todos os pacotes CA do cluster - Servidor, Cliente, API de Agregação e etcd Peer/Servidor. Para casos de uso avançados, como usar os CAs fornecidos apenas para pacotes selecionados ou usar CAs diferentes para pacotes diferentes, o script de exemplo deve ser modificado para atender às necessidades específicas da sua organização.
Para usar o script de exemplo para gerar certificados e chaves personalizados antes de iniciar o K3s, execute os seguintes 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 -Se o comando for concluído com sucesso, você pode instalar e/ou iniciar o K3s pela primeira vez. Se o script gerou arquivos CA raiz e/ou intermediários, você deve fazer backup desses arquivos para que possam ser reutilizados caso seja necessário rotacionar os certificados CA em uma data posterior.
Rotação de Certificados CA Personalizados
Para rotacionar certificados CA personalizados, use o subcomando k3s certificate rotate-ca.
Os arquivos atualizados devem ser organizados em um diretório temporário, carregados no datastore e o K3s deve ser reiniciado em todos os nós para usar os certificados atualizados.
|
Você não deve sobrescrever os dados atualmente em uso em |
Um cluster que foi iniciado com certificados CA personalizados pode renovar ou rotacionar os certificados e chaves CA de forma não disruptiva, desde que o mesmo CA raiz seja usado.
Se um novo CA raiz for necessário, a rotação será disruptiva. A opção k3s certificate rotate-ca --force deve ser usada, todos os nós que foram adicionados com um token seguro (incluindo servidores) precisarão ser reconfigurados para usar o novo valor do token, e os pods precisarão ser reiniciados para confiar no novo CA raiz.
Usando o Script de Exemplo
O script de exemplo generate-custom-ca-certs.sh vinculado acima também pode ser usado para gerar certificados atualizados em um novo diretório temporário, copiando arquivos para o local correto e definindo a variável de ambiente DATA_DIR.
Para usar o script de exemplo para gerar certificados e chaves atualizados, execute os seguintes 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/serverSe o comando rotate-ca retornar um erro, verifique o log do serviço em busca de erros.
Se o comando for concluído com sucesso, reinicie o K3s em todos os nós do cluster - servidores primeiro, depois agentes.
Se você usou a opção --force ou alterou o CA raiz, certifique-se de que quaisquer nós que foram unidos com um token seguro sejam reconfigurados para usar o novo valor do token, antes de serem reiniciados.
O token pode ser armazenado em um .env arquivo, unidade systemd ou config.yaml, dependendo de como o nó foi configurado durante a instalação inicial.
Rotação de Certificados CA Autoassinados
Para rotacionar os certificados CA autoassinados gerados pelo K3s, use o subcomando k3s certificate rotate-ca.
Os arquivos atualizados devem ser preparados em um diretório temporário, carregados no datastore e o K3s deve ser reiniciado em todos os nós para usar os certificados atualizados.
|
Você não deve sobrescrever os dados atualmente em uso em |
Se o cluster foi iniciado com certificados CA autoassinados padrão, a rotação será disruptiva. Todos os nós que foram adicionados com um token seguro precisarão ser reconfigurados para confiar no novo hash CA.
Se os novos certificados CA não forem cruzados pelos antigos certificados CA, você precisará usar a opção --force para ignorar as verificações de integridade, e os pods precisarão ser reiniciados para confiar na nova CA raiz.
Topologia CA Padrão
Os certificados CA autoassinados padrão têm a seguinte topologia:
(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
Ao rotacionar os CAs autoassinados padrão, uma topologia de certificados modificada com CAs intermediárias e uma nova CA raiz cruzada pelo antigo CA pode ser usada para que haja uma cadeia contínua de confiança entre o antigo e o novo CA:
(antigo)") + client-ca-old("CA do Cliente
(antigo)") + request-header-ca-old("CA de Agregação de API
(antigo)") + etcd-peer-ca-old("CA de Par etcd
(antigo)") + etcd-server-ca-old("CA do Servidor etcd
(antigo)") root-hash>"Join token CA hash"] server-ca-xsigned("CA do Servidor
(cruzado)") + client-ca-xsigned("CA do Cliente
(cruzado)") + request-header-ca-xsigned("CA de Agregação de API
(cruzado)") + etcd-peer-ca-xsigned("CA de Par etcd
(cruzado)") + etcd-server-ca-xsigned("CA do Servidor etcd
(cruzado)") 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("Intermediário
CA do Servidor") + client-ca("Intermediário
CA do Cliente") + request-header-ca("Intermediário
CA de Agregação de API") + etcd-peer-ca("Intermediário
CA de Par etcd") + etcd-server-ca("Intermediário
CA do 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-raiz + 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
Usando o Script de Exemplo
Um script de exemplo para criar certificados CA e chaves atualizados cruzados pelos CAs existentes está disponível no repositório K3s em contrib/util/rotate-default-ca-certs.sh.
Para usar o script de exemplo para gerar certificados autoassinados atualizados que são cruzados pelos CAs existentes, execute os seguintes 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-caSe o comando rotate-ca retornar um erro, verifique o log do serviço em busca de erros.
Se o comando for concluído com sucesso, reinicie o K3s em todos os nós do cluster - servidores primeiro, depois agentes.
Certifique-se de que quaisquer nós que foram adicionados com um token seguro, incluindo outros nós de servidor, sejam reconfigurados para usar o novo valor do token antes de serem reiniciados.
O token pode ser armazenado em um .env arquivo, unidade systemd ou config.yaml, dependendo de como o nó foi configurado durante a instalação inicial.
Rotação da Chave do Emissor de Conta de Serviço
A chave do emissor da conta de serviço é uma chave privada RSA usada para assinar tokens de conta de serviço.
Ao rotacionar a chave do emissor da conta de serviço, pelo menos uma chave antiga deve ser mantida no arquivo para que os tokens de conta de serviço existentes não sejam invalidados.
Ela pode ser rotacionada independentemente das CAs do cluster usando o k3s certificate rotate-ca para instalar apenas um arquivo service.key atualizado que inclua tanto as chaves novas quanto as antigas.
|
Você não deve sobrescrever os dados atualmente em uso em |
Por exemplo, para girar apenas a chave do emissor da conta de serviço, execute os seguintes 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É normal ver avisos para arquivos que não estão sendo atualizados. Se o comando rotate-ca retornar um erro, verifique o log do serviço em busca de erros.
Se o comando for concluído com sucesso, reinicie o K3s em todos os servidores do cluster. Não é necessário reiniciar agentes ou reiniciar quaisquer pods.