Documentação do Oracle Cloud Infrastructure

Migrando Segredos do Kubernetes para o KMS v2

Descubra como recriptografar objetos secretos existentes do Kubernetes usando o provedor de KMS (Key Management Service) versão 2 em um cluster que você criou usando o OKE (Kubernetes Engine).

O plano de controle de cluster do Kubernetes armazena dados de configuração confidenciais (como tokens de autenticação, certificados e credenciais) como objetos secretos do Kubernetes no etcd. Ao criar um cluster usando o Kubernetes Engine, você pode especificar uma chave de criptografia mestra no serviço Oracle Cloud Infrastructure Vault para criptografar as chaves de criptografia de dados que protegem os segredos do Kubernetes em repouso. Para obter mais informações, consulte Criptografando Segredos do Kubernetes em Repouso no Etcd.

O Kubernetes usa um provedor de KMS para se comunicar entre o servidor de API do Kubernetes e o plug-in KMS do Kubernetes Engine. A versão do provedor KMS é separada da versão da chave de criptografia mestra no Vault. A migração do provedor de KMS versão 1 para o provedor de KMS versão 2 não exige que você crie uma nova chave de criptografia mestra ou altere a chave associada ao cluster. Para obter mais informações sobre provedores do Kubernetes KMS, consulte Usando um provedor de KMS para criptografia de dados na documentação do Kubernetes.

A versão do provedor KMS usada para criptografar objetos secretos do Kubernetes depende da versão do Kubernetes em execução no plano de controle do cluster:

  • Os clusters que usam uma chave de criptografia mestra que você gerencia e executa versões do Kubernetes anteriores à 1.36.1 usam o provedor de KMS versão 1 para criptografar objetos secretos do Kubernetes.
  • Novos clusters criados com o Kubernetes versão 1.36.1 ou posterior e uma chave de criptografia mestra que você gerencia usam o provedor de KMS versão 2 desde o momento em que o cluster é criado.
  • Quando você faz upgrade de um cluster existente para o Kubernetes versão 1.36.1 ou posterior, o Kubernetes Engine começa a usar o provedor de KMS versão 2. Os novos objetos secretos do Kubernetes usam o provedor KMS versão 2, assim como os objetos secretos existentes que são atualizados posteriormente.

O upgrade do plano de controle do cluster não reescreve automaticamente todos os objetos secretos existentes do Kubernetes. Os objetos secretos que foram criptografados usando o provedor de KMS versão 1 antes do upgrade podem permanecer criptografados usando a versão 1 do provedor de KMS até que o Kubernetes os grave novamente.

O Kubernetes Engine retém a versão 1 do provedor KMS como fallback de leitura; portanto, os objetos secretos existentes permanecem legíveis após o upgrade do plano de controle e durante a migração. Não é necessário migrar objetos secretos existentes imediatamente para manter os aplicativos em execução.

Use o procedimento neste tópico para reescrever todos os objetos secretos existentes do Kubernetes em uma operação. Quando o Kubernetes reescreve cada objeto secreto, o servidor de API do Kubernetes o criptografa usando o provedor de KMS versão 2. Após a migração ser bem-sucedida, os objetos secretos que foram criptografados anteriormente usando o provedor de KMS versão 1 foram recriptografados usando o provedor de KMS versão 2.

Observe o seguinte:

  • Normalmente, você não precisa executar essa migração para um novo cluster criado com o Kubernetes versão 1.36.1 ou posterior, porque o cluster usa a versão 2 do provedor KMS desde o momento em que o cluster é criado.
  • Não é possível executar a migração enquanto o plano de controle do cluster estiver executando uma versão do Kubernetes anterior à versão 1.36.1.
  • O Kubernetes Engine não inicia automaticamente uma migração em massa quando você faz upgrade do plano de controle do cluster. Você decide quando iniciar a migração.
  • Uma migração manual só é necessária quando você deseja criptografar novamente todos os objetos secretos do Kubernetes existentes e inalterados em uma operação.
Observação

Este procedimento só se aplica a clusters que usam uma chave de criptografia mestra que você gerencia para criptografar objetos secretos do Kubernetes em repouso no etcd. Não se aplica a clusters que usam apenas a criptografia padrão dos volumes de armazenamento em blocos que contêm etcd.

Antes de Começar

Antes de migrar objetos secretos do Kubernetes para o provedor KMS versão 2:

  • Confirme se o cluster usa uma chave de criptografia mestra no serviço Oracle Cloud Infrastructure Vault que você gerencia para criptografar segredos do Kubernetes em repouso. Consulte Criptografando segredos do Kubernetes em repouso no Etcd.
  • Faça upgrade do plano de controle do cluster para o Kubernetes versão 1.36.1 ou posterior. Consulte Upgrade da Versão do Kubernetes nos Nós do Plano de Controle de um Cluster.
  • Configure kubectl para acessar o cluster. Consulte Configurando o Acesso ao Cluster.
  • Certifique-se de que sua identidade do Kubernetes tenha permissão para criar, obter, assistir e excluir o recurso storageversionmigrations.storagemigration.k8s.io com escopo no cluster. Um administrador de cluster geralmente tem essas permissões.
  • Se você usar uma solução de backup, como o Velero, faça um backup atual que inclua todos os objetos secretos do Kubernetes e confirme se o backup foi concluído com sucesso. Proteja o backup de acordo com os requisitos de segurança da sua organização porque ele contém dados confidenciais.
  • Planeje monitorar a migração até que ela seja bem-sucedida. A migração lê e reescreve cada objeto secreto do Kubernetes no cluster e pode gerar atividade adicional da API do Kubernetes. Clusters maiores podem levar mais tempo para migrar.

Confirmando se o Cluster está Pronto

Não é possível exibir a configuração interna do provedor KMS do Kubernetes Engine. Em vez disso, use a versão do plano de controle do Kubernetes e a descoberta da API do Kubernetes para confirmar se o cluster está pronto para migração:

  1. Verifique as versões do cliente e do servidor do Kubernetes digitando:

    kubectl version

    Confirme se o Server Version é v1.36.1 ou mais recente.

    A versão do servidor é a versão do Kubernetes em execução no plano de controle do cluster. As versões do Kubernetes em execução nos nós de trabalho não determinam se a migração da versão 2 do provedor KMS está disponível.

  2. Verifique se a API de Migração de Versão de Armazenamento está disponível, digitando:

    kubectl api-resources --api-group=storagemigration.k8s.io

    Verifique se a saída inclui o recurso storageversionmigrations, semelhante ao seguinte:

    
NAME                         SHORTNAMES   APIVERSION                         NAMESPACED   KIND
storageversionmigrations                  storagemigration.k8s.io/v1beta1    false        StorageVersionMigration

  3. Confirme se a sua identidade do Kubernetes pode criar, monitorar e excluir uma migração, digitando:

    kubectl auth can-i create storageversionmigrations.storagemigration.k8s.io
    kubectl auth can-i get storageversionmigrations.storagemigration.k8s.io
    kubectl auth can-i watch storageversionmigrations.storagemigration.k8s.io
    kubectl auth can-i delete storageversionmigrations.storagemigration.k8s.io

    Cada comando deve retornar yes.

    Se um comando retornar no, peça a um administrador de cluster para executar a migração ou conceder as permissões necessárias do Kubernetes RBAC.

Você pode iniciar a migração quando todas as seguintes afirmações forem verdadeiras:

  • O cluster usa uma chave de criptografia mestra que você gerencia para criptografar objetos secretos do Kubernetes.
  • O plano de controle do cluster está executando o Kubernetes versão 1.36.1 ou posterior.
  • A API de Migração de Versão de Armazenamento está disponível.
  • Sua identidade do Kubernetes tem as permissões necessárias.

Se a API de Migração da Versão de Armazenamento não estiver disponível, não tente usar outro procedimento de gravação em massa. Confirme se o kubectl está conectado ao cluster pretendido e se o upgrade do plano de controle foi concluído. Se a API permanecer indisponível, entre em contato com o Suporte Técnico da Oracle.

Migrando Objetos Segredos Existentes do Kubernetes

Para obter mais informações sobre como usar a API de Migração de Versão do Kubernetes Storage para migrar objetos armazenados, consulte Migrar Objetos do Kubernetes Usando a Migração de Versão do Armazenamento na documentação do Kubernetes.

Para recriptografar todos os objetos secretos existentes do Kubernetes usando o provedor KMS versão 2:

  1. Crie um arquivo chamado migrate-secrets-to-kms-v2.yaml com o seguinte conteúdo:

    apiVersion: storagemigration.k8s.io/v1beta1
kind: StorageVersionMigration
metadata:
  name: migrate-secrets-to-kms-v2
spec:
  resource:
    group: ""
    resource: secrets

    O valor group vazio identifica o grupo de APIs principais do Kubernetes. O valor resource: secrets limita a migração para objetos secretos do Kubernetes.

    Um recurso StorageVersionMigration tem o escopo do cluster. Portanto, a migração inclui objetos secretos do Kubernetes em todos os namespaces.

  2. Crie a migração:

    kubectl create -f migrate-secrets-to-kms-v2.yaml

    A criação do recurso instrui o migrador da versão de armazenamento do Kubernetes a ler e reescrever os objetos secretos do Kubernetes. A operação não altera intencionalmente valores de segredo. Quando cada objeto é gravado, o servidor de API do Kubernetes o criptografa usando a configuração ativa da versão 2 do provedor KMS.

  3. Monitore a migração e aguarde o sucesso:

    kubectl wait \
  --for=condition=Succeeded \
  storageversionmigration.storagemigration.k8s.io/migrate-secrets-to-kms-v2 \
  --timeout=24h

    Um comando bem-sucedido retorna uma saída semelhante à seguinte:

    storageversionmigration.storagemigration.k8s.io/migrate-secrets-to-kms-v2 condition met

    O timeout controla por quanto tempo kubectl aguarda a condição. Atingir o timeout não cancela uma migração que ainda está em execução.

Verificando a Migração

Para confirmar se a migração foi concluída com sucesso:

  1. Obter o status da migração:

    kubectl get \
  storageversionmigration.storagemigration.k8s.io/migrate-secrets-to-kms-v2 \
  -o yaml

  2. Na lista status.conditions, confirme se a condição Succeeded tem um valor True, semelhante ao seguinte:

    status:
  conditions:
  - type: Succeeded
    status: "True"
    reason: StorageVersionMigrationSucceeded

O status bem-sucedido confirma que o Kubernetes reescreveu os objetos secretos. Para um cluster que usa uma chave de criptografia mestra que você gerencia e está executando o Kubernetes versão 1.36.1 ou posterior, os objetos reescritos são criptografados usando o provedor KMS versão 2.

Após confirmar que a migração foi bem-sucedida, você poderá excluir o recurso de migração concluído:

kubectl delete \
  storageversionmigration.storagemigration.k8s.io/migrate-secrets-to-kms-v2

Você também pode excluir o arquivo migrate-secrets-to-kms-v2.yaml local.

A exclusão do recurso StorageVersionMigration não desfaz a migração e não exclui nenhum objeto secreto do Kubernetes.

Diagnosticando e Solucionando Problemas da Migração do KMS v2

A API de Migração da Versão de Armazenamento Não Está Listada

Se o comando kubectl api-resources não listar o recurso storageversionmigrations, confirme se:

  • kubectl está usando o contexto do cluster pretendido.
  • O Server Version reportado pelo kubectl version é v1.36.1 ou mais recente.
  • O upgrade do plano de controle foi concluído com sucesso.

As versões do Kubernetes em execução nos nós de trabalho não determinam se a API de migração está disponível.

Se todas essas condições forem atendidas e a API permanecer indisponível, entre em contato com o Suporte Técnico da Oracle. Não tente usar um procedimento de regravação em massa diferente.

A Migração Não Pode Ser Criada

Se o comando kubectl create retornar um erro Forbidden, confirme se sua identidade do Kubernetes pode criar o recurso de migração:

kubectl auth can-i create storageversionmigrations.storagemigration.k8s.io

Se o comando retornar no, peça a um administrador de cluster para executar a migração ou conceder as permissões necessárias do Kubernetes RBAC.

Se o comando kubectl create retornar um erro AlreadyExists, inspecione a migração existente:

kubectl get \
  storageversionmigration.storagemigration.k8s.io/migrate-secrets-to-kms-v2 \
  -o yaml

Se a migração existente for concluída com sucesso e você quiser executar uma nova migração, exclua o recurso StorageVersionMigration concluído antes de criá-la novamente.

A Migração Não Tem Sucesso

Inspecione o status da migração e os eventos associados:

kubectl describe \
  storageversionmigration.storagemigration.k8s.io/migrate-secrets-to-kms-v2

Se a condição Failed for True ou se a migração permanecer incompleta, mantenha a saída do comando e entre em contato com o Suporte Técnico da Oracle.

Os objetos secretos do Kubernetes que não foram reescritos permanecem legíveis usando o fallback da versão 1 do provedor KMS. Novos objetos secretos e objetos secretos existentes atualizados por meio de operações normais do Kubernetes continuam sendo criptografados usando o provedor de KMS versão 2.