Usar a extensão do Repositório de Segredos para buscar segredos para acesso offline em clusters do Kubernetes habilitados para Azure Arc

A extensão do Repositório de Segredos do Azure Key Vault para Kubernetes ("SSE") sincroniza automaticamente segredos de um Azure Key Vault com um cluster Kubernetes habilitado para Azure Arc para acesso offline. Isso significa que você pode usar o Azure Key Vault para armazenar, manter e fazer a rotação dos seus segredos, mesmo ao executar seu cluster Kubernetes em um estado semi-desconectado. Os segredos sincronizados são armazenados no repositório de segredos do cluster, disponibilizando-os como segredos do Kubernetes para serem usados de todas as maneiras usuais: montados como volumes de dados ou expostos como variáveis de ambiente para um contêiner em um pod.

Os segredos sincronizados são ativos comerciais críticos, portanto, o SSE os protege por meio de namespaces e nós isolados, políticas de RBAC (controle de acesso baseado em função) e permissões limitadas para o sincronizador de segredos. Para proteção extra, criptografe o repositório de segredos do Kubernetes em seu cluster.

Este artigo mostra como instalar e configurar o SSE como uma extensão do Kubernetes habilitada para Azure Arc.

Pré-requisitos

• Um cluster habilitado para Arc. Ele pode ser um ao qual você se conectou (os exemplos deste guia usam um cluster K3s) ou um AKS gerenciado pela Microsoft que possa ser acessado pelo cluster do Azure Arc. O cluster precisa executar o Kubernetes versão 1.27 ou superior e estar em uma das regiões com suporte (Leste dos EUA, Leste dos EUA 2, Oeste dos EUA, Oeste dos EUA 2, Oeste dos EUA 3, Oeste da Europa e Norte da Europa). A região é definida pela região do grupo de recursos usada para criar o cluster Arc.
• Verifique se você atende aos pré-requisitos gerais para extensões de cluster, incluindo a versão mais recente da extensão k8s-extension da CLI do Azure.
• O cert-manager é necessário para dar suporte ao TLS para comunicação de log intracluster. Os exemplos posteriores neste guia direcionam você para a instalação. Para obter mais informações sobre o cert-manager, confira cert-manager.io

Instale a CLI do Azure e entre, caso ainda não tenha feito isso:

az login

Antes de começar, defina as variáveis de ambiente a serem usadas para configurar recursos do Azure e do cluster. Se você já tiver uma identidade gerenciada, o Azure Key Vault ou outro recurso listado aqui, atualize os nomes nas variáveis de ambiente para refletir esses recursos.

export RESOURCE_GROUP="AzureArcTest"
export CLUSTER_NAME="AzureArcTest1"
export LOCATION="EastUS"
export SUBSCRIPTION="$(az account show --query id --output tsv)"
az account set --subscription "${SUBSCRIPTION}"
export AZURE_TENANT_ID="$(az account show -s $SUBSCRIPTION --query tenantId --output tsv)"
export CURRENT_USER="$(az ad signed-in-user show --query userPrincipalName --output tsv)"
export KEYVAULT_NAME="my-kv"
export KEYVAULT_SECRET_NAME="my-secret"
export USER_ASSIGNED_IDENTITY_NAME="my-identity"
export FEDERATED_IDENTITY_CREDENTIAL_NAME="my-credential"
export KUBERNETES_NAMESPACE="my-namespace"
export SERVICE_ACCOUNT_NAME="my-service-account"

Ativar a federação de identidades da carga de trabalho no cluster

O SSE usa um recurso chamado federação de identidades da carga de trabalho para acessar e sincronizar segredos do Azure Key Vault. Esta seção descreve como configurar esse recurso. As seções a seguir explicarão como ele é usado em detalhes.

az connectedk8s connect --name ${CLUSTER_NAME} --resource-group ${RESOURCE_GROUP} --enable-oidc-issuer --enable-workload-identity

az connectedk8s update --name ${CLUSTER_NAME} --resource-group ${RESOURCE_GROUP} --enable-oidc-issuer --enable-workload-identity

export SERVICE_ACCOUNT_ISSUER="$(az connectedk8s show --name ${CLUSTER_NAME} --resource-group ${RESOURCE_GROUP} --query "oidcIssuerProfile.issuerUrl" --output tsv)"
echo $SERVICE_ACCOUNT_ISSUER

export SERVICE_ACCOUNT_ISSUER="$(az connectedk8s show --name ${CLUSTER_NAME} --resource-group ${RESOURCE_GROUP} --query "oidcIssuerProfile.issuerUrl" --output tsv)"
echo $SERVICE_ACCOUNT_ISSUER

Criar um segredo e configurar uma identidade para acessá-lo

Para acessar e sincronizar um determinado segredo do Azure Key Vault, o SSE requer acesso a uma identidade gerenciada do Azure com permissões apropriadas do Azure para acessar esse segredo. A identidade gerenciada precisa estar vinculada a uma conta de serviço do Kubernetes por meio do recurso de identidade da carga de trabalho que você ativou acima. A extensão do SSE usa a identidade gerenciada federada do Azure associada para extrair segredos do Azure Key Vault para o repositório de segredos do Kubernetes. As seções a seguir descrevem como configurar isso.

Criar um Cofre de chaves do Azure

Crie um Azure Key Vault e adicione um segredo. Se você já tiver um Azure Key Vault e um segredo, ignore esta seção.

1. Crie um Azure Key Vault:

   az keyvault create --resource-group "${RESOURCE_GROUP}" --location "${LOCATION}" --name "${KEYVAULT_NAME}" --enable-rbac-authorization
   

2. Conceda a si mesmo permissões de "Oficial de Segredos" no cofre, para que você possa criar um segredo:

   az role assignment create --role "Key Vault Secrets Officer" --assignee ${CURRENT_USER} --scope /subscriptions/${SUBSCRIPTION}/resourcegroups/${RESOURCE_GROUP}/providers/Microsoft.KeyVault/vaults/${KEYVAULT_NAME}
   

3. Crie um segredo e atualize-o para que você tenha duas versões:

   az keyvault secret set --vault-name "${KEYVAULT_NAME}" --name "${KEYVAULT_SECRET_NAME}" --value 'Hello!'
   az keyvault secret set --vault-name "${KEYVAULT_NAME}" --name "${KEYVAULT_SECRET_NAME}" --value 'Hello2'
   

Criar uma identidade gerenciada atribuída ao usuário

Em seguida, crie uma identidade gerenciada atribuída pelo usuário e conceda a ela permissões para acessar o Azure Key Vault. Se você já tiver uma identidade gerenciada com as permissões de Leitor do Key Vault Usuário de Segredos do Key Vault para o Azure Key Vault, ignore esta seção. Para obter mais informações, consulte Criar identidades gerenciadas atribuídas pelo usuário e Usando as permissões de segredo, chave e certificado do RBAC do Azure com o Key Vault.

1. Crie a identidade gerenciada atribuída pelo usuário:

   az identity create --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --location "${LOCATION}" --subscription "${SUBSCRIPTION}"
   

2. Conceda permissões às identidades Leitor do Key Vault e Usuário de Segredos do Key Vault. Talvez seja necessário aguardar um momento para a replicação da criação de identidade antes que esses comandos sejam bem-sucedidos:

   export USER_ASSIGNED_CLIENT_ID="$(az identity show --resource-group "${RESOURCE_GROUP}" --name "${USER_ASSIGNED_IDENTITY_NAME}" --query 'clientId' -otsv)"
   az role assignment create --role "Key Vault Reader" --assignee "${USER_ASSIGNED_CLIENT_ID}" --scope /subscriptions/${SUBSCRIPTION}/resourcegroups/${RESOURCE_GROUP}/providers/Microsoft.KeyVault/vaults/${KEYVAULT_NAME}
   az role assignment create --role "Key Vault Secrets User" --assignee "${USER_ASSIGNED_CLIENT_ID}" --scope /subscriptions/${SUBSCRIPTION}/resourcegroups/${RESOURCE_GROUP}/providers/Microsoft.KeyVault/vaults/${KEYVAULT_NAME}
   

Criar uma credencial de identidade federada

Crie uma conta de serviço do Kubernetes para a carga de trabalho que precisa de acesso aos segredos. Em seguida, crie uma credencial de identidade federada para vincular entre a identidade gerenciada, o emissor da conta de serviço OIDC e a Conta de Serviço do Kubernetes.

1. Crie uma Conta de Serviço do Kubernetes que será federada para a identidade gerenciada. Anote-a com detalhes da identidade gerenciada atribuída pelo usuário associada.

   kubectl create ns ${KUBERNETES_NAMESPACE}
   

   cat <<EOF | kubectl apply -f -
     apiVersion: v1
     kind: ServiceAccount
     metadata:
       name: ${SERVICE_ACCOUNT_NAME}
       namespace: ${KUBERNETES_NAMESPACE}
   EOF
   

2. Crie uma credencial de identidade federada:

   az identity federated-credential create --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} --identity-name ${USER_ASSIGNED_IDENTITY_NAME} --resource-group ${RESOURCE_GROUP} --issuer ${SERVICE_ACCOUNT_ISSUER} --subject system:serviceaccount:${KUBERNETES_NAMESPACE}:${SERVICE_ACCOUNT_NAME}
   

Instalar o SSE

O SSE está disponível como uma extensão do Azure Arc. Um cluster Kubernetes habilitado para Azure Arc pode ser estendido com extensões do Kubernetes habilitadas para Azure Arc. As extensões habilitam os recursos do Azure em seu cluster conectado e fornecem uma experiência orientada pelo Azure Resource Manager para a instalação da extensão e o gerenciamento do ciclo de vida.

O cert-manager e o trust-manager também são necessários para a comunicação segura de logs entre os serviços de cluster e precisam ser instalados antes da extensão do Arc.

1. Instale o cert-manager.

   helm repo add jetstack https://charts.jetstack.io/ --force-update
   helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.16.2 --set crds.enabled=true 
   

2. Instale o trust-manager.

   helm upgrade trust-manager jetstack/trust-manager --install --namespace cert-manager --wait
   

3. Instale o SSE no cluster habilitado para Arc usando o seguinte comando:

   az k8s-extension create \
     --cluster-name ${CLUSTER_NAME} \
     --cluster-type connectedClusters \
     --extension-type microsoft.azure.secretstore \
     --resource-group ${RESOURCE_GROUP} \
     --release-train preview \
     --name ssarcextension \
     --scope cluster 
   

   Se desejado, você pode, opcionalmente, modificar o intervalo de votação de rotação padrão adicionando --configuration-settings rotationPollIntervalInSeconds=<time_in_seconds>:

   Nome do Parâmetro	Descrição	Valor padrão
   rotationPollIntervalInSeconds	Especifica a rapidez com que o SSE verifica ou atualiza o segredo que está gerenciando.	3600 (uma hora)

Configurar o SSE

Configure a extensão instalada com informações sobre o Azure Key Vault e quais segredos sincronizar com seu cluster definindo instâncias de recursos personalizados do Kubernetes. Você cria dois tipos de recursos personalizados:

• Um objeto SecretProviderClass para definir a conexão com o Key Vault.
• Um objeto SecretSync para cada segredo a ser sincronizado.

Criar um recurso SecretProviderClass

O recurso SecretProviderClass é usado para definir a conexão com o Azure Key Vault, a identidade a ser usada para acessar o cofre, quais segredos sincronizar e o número de versões de cada segredo a serem retidas localmente.

Você precisa de um SecretProviderClass separado para cada Azure Key Vault que pretende sincronizar, para cada identidade usada para acesso a um Azure Key Vault e para cada namespace Kubernetes de destino.

Crie um ou mais arquivos YAML SecretProviderClass com os valores apropriados para seu Key Vault e segredos seguindo este exemplo.

cat <<EOF > spc.yaml
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: secret-provider-class-name                      # Name of the class; must be unique per Kubernetes namespace
  namespace: ${KUBERNETES_NAMESPACE}                    # Kubernetes namespace to make the secrets accessible in
spec:
  provider: azure
  parameters:
    clientID: "${USER_ASSIGNED_CLIENT_ID}"               # Managed Identity Client ID for accessing the Azure Key Vault with.
    keyvaultName: ${KEYVAULT_NAME}                       # The name of the Azure Key Vault to synchronize secrets from.
    objects: |
      array:
        - |
          objectName: ${KEYVAULT_SECRET_NAME}            # The name of the secret to sychronize.
          objectType: secret
          objectVersionHistory: 2                       # [optional] The number of versions to synchronize, starting from latest.
    tenantID: "${AZURE_TENANT_ID}"                       # The tenant ID of the Key Vault 
EOF

Criar um objeto SecretSync

Cada segredo sincronizado também requer um objeto SecretSync para definir informações específicas do cluster. Aqui você especifica informações como o nome do segredo em seu cluster e nomes para cada versão do segredo armazenado em seu cluster.

Crie um arquivo YAML do objeto SecretSync para cada segredo, seguindo este modelo. O namespace do Kubernetes deve corresponder ao namespace do SecretProviderClass correspondente.

cat <<EOF > ss.yaml
apiVersion: secret-sync.x-k8s.io/v1alpha1
kind: SecretSync
metadata:
  name: secret-sync-name                                  # Name of the object; must be unique per Kubernetes namespace
  namespace: ${KUBERNETES_NAMESPACE}                      # Kubernetes namespace
spec:
  serviceAccountName: ${SERVICE_ACCOUNT_NAME}             # The Kubernetes service account to be given permissions to access the secret.
  secretProviderClassName: secret-provider-class-name     # The name of the matching SecretProviderClass with the configuration to access the AKV storing this secret
  secretObject:
    type: Opaque
    data:
    - sourcePath: ${KEYVAULT_SECRET_NAME}/0                # Name of the secret in Azure Key Vault with an optional version number (defaults to latest)
      targetKey: ${KEYVAULT_SECRET_NAME}-data-key0         # Target name of the secret in the Kubernetes secret store (must be unique)
    - sourcePath: ${KEYVAULT_SECRET_NAME}/1                # [optional] Next version of the AKV secret. Note that versions of the secret must match the configured objectVersionHistory in the secrets provider class 
      targetKey: ${KEYVAULT_SECRET_NAME}-data-key1         # [optional] Next target name of the secret in the K8s secret store
EOF

Aplicar as CRs de configuração

Aplique os CRs (recursos personalizados de configuração) usando o comando kubectl apply:

kubectl apply -f ./spc.yaml
kubectl apply -f ./ss.yaml

O SSE procura automaticamente os segredos e começa a sincronizá-los com o cluster.

Exibir opções de configuração

Para exibir opções de configuração adicionais para esses dois tipos de recursos personalizados, use o comando kubectl describe para inspecionar os CRDs no cluster:

# Get the name of any applied CRD(s)
kubectl get crds -o custom-columns=NAME:.metadata.name

# View the full configuration options and field parameters for a given CRD
kubectl describe crd secretproviderclass
kubectl describe crd secretsync

Observar segredos sincronizando com o cluster

Depois que a configuração é aplicada, os segredos começam a ser sincronizados com o cluster automaticamente na cadência especificada ao instalar o SSE.

Exibir segredos sincronizados

Exiba os segredos sincronizados com o cluster executando o seguinte comando:

# View a list of all secrets in the namespace
kubectl get secrets -n ${KUBERNETES_NAMESPACE}

# View details of all secrets in the namespace
kubectl get secrets -n ${KUBERNETES_NAMESPACE} -o yaml

Exibir o status da última sincronização

Para exibir o status da sincronização mais recente de um determinado segredo, use o comando kubectl describe para o objeto SecretSync. A saída inclui o carimbo de data/hora de criação do segredo, as versões do segredo e as mensagens de status detalhadas para cada evento de sincronização. Essa saída pode ser usada para diagnosticar erros de conexão ou configuração e observar quando o valor do segredo é alterado.

kubectl describe secretsync secret-sync-name -n ${KUBERNETES_NAMESPACE}

Exibir valores de segredos

Para exibir os valores de segredo sincronizados, agora armazenados no repositório de segredos do Kubernetes, use o seguinte comando:

kubectl get secret secret-sync-name -n ${KUBERNETES_NAMESPACE} -o jsonpath="{.data.${KEYVAULT_SECRET_NAME}-data-key0}" | base64 -d
kubectl get secret secret-sync-name -n ${KUBERNETES_NAMESPACE} -o jsonpath="{.data.${KEYVAULT_SECRET_NAME}-data-key1}" | base64 -d

Solução de problemas

O SSE é uma implantação do Kubernetes que contém um pod com dois contêineres: o controlador, que gerencia o armazenamento de segredos no cluster, e o provedor, que gerencia o acesso e extraindo segredos do Azure Key Vault. Cada segredo sincronizado tem um objeto SecretSync que contém o status da sincronização desse segredo do Azure Key Vault para o repositório de segredos do cluster.

Para solucionar um problema, comece examinando o estado do objeto SecretSync, conforme descrito em Exibir o status da última sincronização. A tabela a seguir lista tipos de status comuns, seus significados e possíveis etapas de solução de problemas para resolver erros.

Remover o SSE

Para remover o SSE e parar de sincronizar segredos, desinstale-o com o comando az k8s-extension delete:

az k8s-extension delete --name ssarcextension --cluster-name $CLUSTER_NAME  --resource-group $RESOURCE_GROUP  --cluster-type connectedClusters    

Desinstalar a extensão não remove segredos, objetos SecretSync ou CRDs do cluster. Esses objetos devem ser removidos diretamente com kubectl.

Excluir o SecretSync CRD remove todos os objetos SecretSync e, por padrão, remove todos os segredos de propriedade, mas os segredos podem persistir se:

• Você modificou a propriedade de qualquer um dos segredos.
• Você alterou as configurações de GC em seu cluster, incluindo a configuração de finalizadores diferentes.

Nos casos acima, os segredos devem ser excluídos diretamente usando kubectl.

Próximas etapas

• Saiba mais sobre as extensões do Azure Arc.
• Saiba mais sobre o Azure Key Vault.