Adicionar criptografia etcd do Key Management Service (KMS) a um cluster do Azure Kubernetes Service (AKS) (legado)

Importante

Este artigo descreve a experiência do KMS herdada para o AKS. Para novos clusters que executam o Kubernetes versão 1.33 ou posterior, recomendamos usar a nova experiência de criptografia de dados KMS , que oferece chaves gerenciadas pela plataforma, chaves gerenciadas pelo cliente com rotação automática de chaves e uma experiência de configuração simplificada.

Para obter informações conceituais sobre opções de criptografia de dados, consulte Os conceitos de criptografia de dados em repouso para o AKS.

Este artigo mostra como ativar a criptografia em repouso para um cofre de chaves público ou privado usando o Azure Key Vault e o plug-in KMS (Serviço de Gerenciamento de Chaves) no AKS. Você pode usar o plug-in do KMS para o seguinte:

Usar uma chave em um cofre de chaves para a criptografia etcd.
Trazer suas próprias chaves.
Forneça criptografia em repouso para segredos armazenados em etcd.
Fazer a rotação das chaves em um cofre de chaves.

Para obter mais informações sobre como usar KMS, consulte Usando um provedor KMS para criptografia de dados.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
CLI do Azure, versão 2.39.0 ou posterior. Localize sua versão usando o az --version comando. Se você precisar instalar ou atualizar, confira Instalar a CLI do Azure.

Aviso

A partir de 15 de setembro de 2024, a Konnectivity não tem mais suporte para cofres de chaves privados para novas assinaturas ou assinaturas que não usavam essa configuração anteriormente. Para assinaturas que atualmente usam essa configuração ou a usaram nos últimos 60 dias, o suporte continua até que a versão 1.30 do AKS atinja o fim da vida útil do suporte à comunidade.

O KMS dá suporte ao Konnectivity ou à Integração da VNet com o Servidor de API para cofres públicos.

O KMS dá suporte à Integração da VNet com o Servidor de API para cofres privados e públicos.

Você pode usar kubectl get pods -n kube-system para verificar os resultados e mostrar que um konnectivity-agent pod está em execução. Quando há um pod em execução, isso significa que o cluster do AKS está usando o Konnectivity. Ao usar a integração de VNet do servidor de API, é possível executar o comando az aks show --resource-group <resource-group-name> --name <cluster-name> para verificar se a configuração enableVnetIntegration está definida como true.

Limitações

As seguintes limitações se aplicam quando você integra a criptografia KMS etcd ao AKS:

Não há suporte à exclusão da chave, do cofre de chaves ou da identidade associada.
A criptografia etcd do KMS não funciona com a identidade gerenciada atribuída pelo sistema. A política de acesso ao cofre de chaves deve ser definida antes da ativação do recurso. A identidade gerenciada atribuída pelo sistema só estará disponível após a criação do cluster. Considere a dependência de ciclos.
Como o firewall bloqueia o tráfego do plug-in KMS para o Key Vault, não há suporte para dois cenários. Primeiro, o Azure Key Vault não pode ser configurado com a opção de firewall Permitir acesso público de redes virtuais específicas e endereços IP. Em segundo lugar, o Azure Key Vault não pode ser configurado com Desabilitar o acesso público , a menos que a Integração VNet do Servidor de API esteja habilitada.
O número máximo de segredos com suporte por um cluster com KMS ativado é de 2.000. No entanto, é importante observar que o KMS v2 não está limitado por essa restrição e pode lidar com um número maior de segredos.
Não há suporte para trazer seu próprio (BYO) cofre de chaves do Azure de outro locatário.
Com o KMS ativado, não é possível alterar o modo de cofre de chaves associado (entre público ou privado). Para atualizar um modo de cofre de chaves, primeiro desative o KMS e, em seguida, ative-o novamente.
Se um cluster tiver o KMS ativado e um cofre privado, ele deverá usar o túnel Integração da VNet com o Servidor de API. Não há suporte para o Konnectivity.
Usar a API de Conjuntos de Dimensionamento de Máquinas Virtuais para reduzir a escala dos nós no cluster até zero desaloca os nós. Assim, o cluster fica inativo e se torna irrecuperável.
Depois de desativar o KMS, você não poderá excluir ou expirar as chaves. Esses comportamentos fariam com que o servidor de API parasse de funcionar.
Para um cluster privado com KMS ativo e integração de rede virtual usando um cofre de chaves privado, o grupo de segurança de rede (NSG) deve permitir a porta TCP 443 do servidor de API para o endereço IP do ponto de extremidade privado do cofre de chaves. Essa limitação precisa ser considerada ao usar outras regras no NSG da sub-rede da API ou no NSG da sub-rede do cluster.

Criar um cofre de chaves e uma chave para um cofre de chaves público

As seções a seguir descrevem como ativar o KMS em um cofre de chaves público. Você pode usar um cofre de chaves públicas com ou sem controle de acesso baseado em função (RBAC) do Azure.

Aviso

Não há suporte para a exclusão da chave ou do cofre de chaves e faz com que os segredos no cluster sejam irrecuperáveis.

Se for preciso recuperar o cofre de chaves ou a chave, confira Gerenciamento de recuperação do Azure Key Vault com exclusão temporária ou proteção contra limpeza.

Criar um cofre de chaves e uma chave com o RBAC do Azure
Criar um cofre de chaves e uma chave sem o RBAC do Azure

Crie um cofre de chaves com o RBAC do Azure usando o comando [az keyvault create][azure-keyvault-create]. Este comando de exemplo também exporta a ID do recurso do cofre de chaves para uma variável de ambiente.
```
export KEY_VAULT_RESOURCE_ID=$(az keyvault create --name $KEY_VAULT --resource-group $RESOURCE_GROUP  --enable-rbac-authorization true --query id -o tsv)
```
Conceda a si mesmo as permissões para criar uma chave usando o comando [az role assignment create][azure-role-assignment-create]. Este exemplo atribui a função de Key Vault Crypto Officer ao usuário conectado.
```
az role assignment create --role "Key Vault Crypto Officer" --assignee-object-id $(az ad signed-in-user show --query id -o tsv) --assignee-principal-type "User" --scope $KEY_VAULT_RESOURCE_ID
```
Crie uma chave usando o comando [az keyvault key create][azure-keyvault-key-create].
```
az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT
```
Obtenha a ID da chave e salve-a como uma variável de ambiente usando o comando [az keyvault key show][azure-keyvault-key-show].
```
export KEY_ID=$(az keyvault key show --name $KEY_NAME --vault-name $KEY_VAULT --query 'key.kid' -o tsv)
echo $KEY_ID
```

Crie um cofre de chaves sem o RBAC do Azure usando o comando [az keyvault create][azure-keyvault-create].
```
az keyvault create --name $KEY_VAULT --resource-group $RESOURCE_GROUP
```
Crie uma chave usando o comando [az keyvault key create][azure-keyvault-key-create].
```
az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT
```

Exporte a ID da chave para uma variável de ambiente usando o comando [az keyvault key show][azure-keyvault-key-show].

export KEY_ID=$(az keyvault key show --name $KEY_NAME --vault-name $KEY_VAULT --query 'key.kid' -o tsv)
echo $KEY_ID

Criar uma identidade gerenciada atribuída pelo usuário para um cofre de chaves público

Crie uma identidade gerenciada atribuída pelo usuário usando o comando [az identity create][azure-identity-create].
```
az identity create --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP
```

Obtenha a ID do objeto de identidade e salve-a como uma variável de ambiente usando o comando [az identity show][azure-identity-show].

export IDENTITY_OBJECT_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'principalId' -o tsv)
echo $IDENTITY_OBJECT_ID

Obtenha a ID do recurso de identidade e salve-a como uma variável de ambiente usando o comando [az identity show][azure-identity-show].

export IDENTITY_RESOURCE_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'id' -o tsv)
echo $IDENTITY_RESOURCE_ID

Atribuir permissões para descriptografar e criptografar um cofre de chaves público

As seções a seguir descrevem como atribuir permissões de descriptografar e criptografar para um cofre de chaves público com ou sem o RBAC do Azure.

Atribuir permissões para um cofre de chaves público com o RBAC do Azure
Atribuir permissões para um cofre de chaves público sem o RBAC do Azure

Permita que a função de usuário de criptografia do Key Vault conceda permissões de criptografia e descriptografia usando o comando [az role assignment create][azure-role-assignment-create].
```
az role assignment create --role "Key Vault Crypto User" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type "ServicePrincipal" --scope $KEY_VAULT_RESOURCE_ID
```

Crie uma política do Cofre de Chaves do Azure para conceder permissões de criptografar e descriptografar usando o comando [az keyvault set-policy][azure-keyvault-set-policy].
```
az keyvault set-policy --name $KEY_VAULT --key-permissions decrypt encrypt --object-id $IDENTITY_OBJECT_ID
```

Habilitar o KMS para um cofre de chaves pública em um cluster do AKS

As seções a seguir descrevem como ativar o KMS para um cofre de chaves público em um cluster AKS novo ou existente.

Criar um cluster do AKS com um cofre de chaves público e KMS

Crie um cluster do AKS com um cofre de chaves público e o KMS usando o comando az aks create com os parâmetros --enable-azure-keyvault-kms, --azure-keyvault-kms-key-vault-network-access e --azure-keyvault-kms-key-id.

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --assign-identity $IDENTITY_RESOURCE_ID \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-vault-network-access "Public" \
    --azure-keyvault-kms-key-id $KEY_ID \
    --generate-ssh-keys

Habilitar um cofre de chaves público e KMS em um cluster do AKS existente

Habilite KMS em um cofre de chaves público em um cluster existente usando o comando az aks update com os parâmetros --enable-azure-keyvault-kms, --azure-keyvault-kms-key-vault-network-access e --azure-keyvault-kms-key-id.

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-vault-network-access "Public" \
    --azure-keyvault-kms-key-id $KEY_ID

Atualize todos os segredos usando o kubectl get secrets comando para garantir que os segredos criados anteriormente não sejam mais criptografados. Para clusters maiores, pode ser melhor subdividir os segredos por namespace ou criar um script de atualização. Se o comando anterior para atualizar o KMS falhar, ainda execute o comando a seguir para evitar um estado inesperado para o plug-in KMS.
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```

Rotacionar chaves existentes em um cofre de chaves público

Depois de alterar a ID da chave (incluindo alterar o nome da chave ou a versão da chave), você pode girar as chaves existentes no cofre de chaves público.

Aviso

Lembre-se de atualizar todos os segredos após a rotação de chaves. Se você não atualizar todos os segredos, eles ficarão inacessíveis se as chaves criadas anteriormente não existirem ou não funcionarem mais.

O KMS usa duas chaves ao mesmo tempo. Após a primeira rotação de chave, você precisará garantir que as chaves antigas e novas sejam válidas (não expiradas) até a próxima rotação de chave. Após a segunda rotação de chave, a chave mais antiga pode ser removida/expirada com segurança.

Depois de girar a versão da chave KMS com o novo keyId, verifique o securityProfile.azureKeyVaultKms.keyId no JSON do recurso do AKS. Verifique se a nova versão da chave está em uso.

Gire as chaves existentes usando o comando az aks update com os parâmetros --enable-azure-keyvault-kms, --azure-keyvault-kms-key-vault-network-access e --azure-keyvault-kms-key-id.

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-vault-network-access "Public" \
    --azure-keyvault-kms-key-id $NEW_KEY_ID

Atualize todos os segredos usando o kubectl get secrets comando para garantir que os segredos criados anteriormente não sejam mais criptografados. Para clusters maiores, pode ser melhor subdividir os segredos por namespace ou criar um script de atualização. Se o comando anterior para atualizar o KMS falhar, ainda execute o comando a seguir para evitar um estado inesperado para o plug-in KMS.
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```

Criar um cofre de chaves e uma chave para um cofre de chaves privado

Se você ativar o KMS em um cofre de chaves privado, o AKS criará automaticamente um ponto de extremidade privado e um link privado no grupo de recursos do nó. O cofre de chaves tem uma conexão de ponto de extremidade privado com o cluster do AKS.

Aviso

Tenha as seguintes informações em mente ao usar um cofre de chaves privado:

O KMS dá suporte apenas à Integração da VNet com o Servidor de API para cofre privado.
Não é possível criar ou atualizar chaves em um cofre de chaves privado que não possua um ponto de extremidade privado. Para saber como gerenciar cofres de chaves privados, confira Integrar um cofre de chaves usando o Link Privado do Azure.
Não há suporte para a exclusão da chave ou do cofre de chaves e faz com que os segredos no cluster sejam irrecuperáveis. Se for preciso recuperar o cofre de chaves ou a chave, confira Gerenciamento de recuperação do Azure Key Vault com exclusão temporária ou proteção contra limpeza.

Crie um cofre de chaves privado usando o comando [az keyvault create][azure-keyvault-create] com o --public-network-access Disabled parâmetro.
```
az keyvault create --name $KEY_VAULT --resource-group $RESOURCE_GROUP --public-network-access Disabled
```
Crie uma chave usando o comando [az keyvault key create][azure-keyvault-key-create].
```
az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT
```

Criar uma identidade gerenciada atribuída a um usuário para um cofre de chaves dedicado

Crie uma identidade gerenciada atribuída pelo usuário usando o comando [az identity create][azure-identity-create].
```
az identity create --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP
```

Obtenha a ID do objeto de identidade e salve-a como uma variável de ambiente usando o comando [az identity show][azure-identity-show].

export IDENTITY_OBJECT_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'principalId' -o tsv)
echo $IDENTITY_OBJECT_ID

Obtenha a ID do recurso de identidade e salve-a como uma variável de ambiente usando o comando [az identity show][azure-identity-show].

export IDENTITY_RESOURCE_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'id' -o tsv)
echo $IDENTITY_RESOURCE_ID

Atribuir permissões para descriptografar e criptografar um cofre de chaves privado

As seções a seguir descrevem como atribuir permissões de criptografia e descriptografia a um cofre de chaves privado, com ou sem o RBAC do Azure.

Atribuir permissões para um cofre de chaves privado com o RBAC do Azure
Atribuir permissões para um cofre de chaves privado sem o RBAC do Azure

Permita que a função de usuário de criptografia do Key Vault conceda permissões de criptografia e descriptografia usando o comando [az role assignment create][azure-role-assignment-create].
```
az role assignment create --role "Key Vault Crypto User" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type "ServicePrincipal" --scope $KEY_VAULT_RESOURCE_ID
```

Observação

Com um cofre de chaves privado, o AKS não pode validar as permissões da identidade. Verifique se a identidade tem permissão para acessar o cofre de chaves antes de habilitar o KMS.

Crie uma política do Cofre de Chaves do Azure para conceder permissões de criptografar e descriptografar usando o comando [az keyvault set-policy][azure-keyvault-set-policy].
```
az keyvault set-policy --name $KEY_VAULT --key-permissions decrypt encrypt --object-id $IDENTITY_OBJECT_ID
```

Atribuir permissões para criar um link privado

No caso dos cofres de chaves privados, a função Contribuidor do Key Vault é necessária para criar um link privado entre o cofre de chaves privado e o cluster.

Atribua a função Colaborador do Key Vault usando o comando [az role assignment create][azure-role-assignment-create].

az role assignment create --role "Key Vault Contributor" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type "ServicePrincipal" --scope $KEY_VAULT_RESOURCE_ID

Habilitar KMS para um cofre de chaves privado em um cluster do AKS

As seções a seguir descrevem como ativar o KMS para um cofre de chaves privado em um cluster AKS novo ou existente.

Criar um cluster do AKS com um cofre de chaves privado e KMS

Crie um cluster AKS com um cofre de chaves privado e KMS usando o comando az aks create com os parâmetros --enable-azure-keyvault-kms, --azure-keyvault-kms-key-id, --azure-keyvault-kms-key-vault-network-access, e --azure-keyvault-kms-key-vault-resource-id.

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --assign-identity $IDENTITY_RESOURCE_ID \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID \
    --azure-keyvault-kms-key-vault-network-access "Private" \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID \
    --generate-ssh-keys

Atualizar um cluster existente do AKS para ativar a criptografia etcd do KMS em um cofre de chaves privado

Habilite o KMS em um cofre de chaves privado em um cluster existente usando o comando az aks update com os parâmetros --enable-azure-keyvault-kms, --azure-keyvault-kms-key-id, --azure-keyvault-kms-key-vault-network-access e --azure-keyvault-kms-key-vault-resource-id.

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID \
    --azure-keyvault-kms-key-vault-network-access "Private" \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID

Atualize todos os segredos usando o kubectl get secrets comando para garantir que os segredos criados anteriormente não sejam mais criptografados. Para clusters maiores, pode ser melhor subdividir os segredos por namespace ou criar um script de atualização. Se o comando anterior para atualizar o KMS falhar, ainda execute o comando a seguir para evitar um estado inesperado para o plug-in KMS.
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```

Fazer a rotação das chaves existentes em um cofre de chaves privado

Depois de alterar a ID da chave (incluindo alterar o nome da chave ou a versão da chave), você pode girar as chaves existentes no cofre de chaves privado.

Aviso

Depois da rotação da chave, a chave anterior (key1) ainda ficará armazenada em cache e não deverá ser excluída. Para excluir a chave anterior (key1) imediatamente, será preciso realizar a rotação duas vezes. Assim, key2 e key3 são armazenadas em cache e key1 pode ser excluída sem afetar o cluster existente.

Depois de girar a versão da chave KMS com o novo keyId, verifique o securityProfile.azureKeyVaultKms.keyId no JSON do recurso do AKS. Verifique se a nova versão da chave está em uso.

Rotacione as chaves existentes em um cofre de chaves privado usando o comando az aks update com os parâmetros --enable-azure-keyvault-kms, --azure-keyvault-kms-key-id, --azure-keyvault-kms-key-vault-network-access e --azure-keyvault-kms-key-vault-resource-id.

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP  \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $NEW_KEY_ID \
    --azure-keyvault-kms-key-vault-network-access "Private" \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID

Atualize todos os segredos usando o kubectl get secrets comando para garantir que os segredos criados anteriormente não sejam mais criptografados. Para clusters maiores, pode ser melhor subdividir os segredos por namespace ou criar um script de atualização. Se o comando anterior para atualizar o KMS falhar, ainda execute o comando a seguir para evitar um estado inesperado para o plug-in KMS.
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```

Desabilitar KMS em um cluster do AKS

Antes de desativar o KMS, verifique se o KMS está habilitado no cluster usando o comando [az aks list][az-aks-list].

az aks list --query "[].{Name:name, KmsEnabled:securityProfile.azureKeyVaultKms.enabled, KeyId:securityProfile.azureKeyVaultKms.keyId}" -o table

Depois de confirmado, você pode desabilitar KMS usando o az aks update comando com o --disable-azure-keyvault-kms parâmetro.
```
az aks update --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --disable-azure-keyvault-kms
```
Atualize todos os segredos usando o kubectl get secrets comando para garantir que os segredos criados anteriormente não sejam mais criptografados. Para clusters maiores, pode ser melhor subdividir os segredos por namespace ou criar um script de atualização. Se o comando anterior para atualizar o KMS falhar, ainda execute o comando a seguir para evitar um estado inesperado para o plug-in KMS.
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```

Próximas etapas

Para obter mais informações sobre como usar KMS com AKS, consulte os seguintes artigos:

Habilitar a criptografia de dados KMS no AKS – A nova experiência KMS com chaves gerenciadas pela plataforma e rotação automática de chaves
Conceitos de criptografia de dados em repouso para o AKS
Atualizar o modo de cofre de chaves para um cluster do Serviço de Kubernetes do Azure (AKS) com criptografia etcd KMS
Migrar para KMS v2 para criptografia etcd no AKS (Serviço de Kubernetes do Azure)
Observabilidade para criptografia KMS etcd no AKS (Serviço de Kubernetes do Azure)

Comentários

Esta página foi útil?

Last updated on 2025-12-23

Compartilhar via

Adicionar criptografia etcd do Key Management Service (KMS) a um cluster do Azure Kubernetes Service (AKS) (legado)

Pré-requisitos

Limitações

Criar um cofre de chaves e uma chave para um cofre de chaves público

Criar uma identidade gerenciada atribuída pelo usuário para um cofre de chaves público

Atribuir permissões para descriptografar e criptografar um cofre de chaves público

Habilitar o KMS para um cofre de chaves pública em um cluster do AKS

Criar um cluster do AKS com um cofre de chaves público e KMS

Habilitar um cofre de chaves público e KMS em um cluster do AKS existente

Rotacionar chaves existentes em um cofre de chaves público

Criar um cofre de chaves e uma chave para um cofre de chaves privado

Criar uma identidade gerenciada atribuída a um usuário para um cofre de chaves dedicado

Atribuir permissões para descriptografar e criptografar um cofre de chaves privado

Atribuir permissões para criar um link privado

Habilitar KMS para um cofre de chaves privado em um cluster do AKS

Criar um cluster do AKS com um cofre de chaves privado e KMS

Atualizar um cluster existente do AKS para ativar a criptografia etcd do KMS em um cofre de chaves privado

Fazer a rotação das chaves existentes em um cofre de chaves privado

Desabilitar KMS em um cluster do AKS

Próximas etapas

Comentários

Recursos adicionais