シークレット ストア拡張機能を使用して、Azure Arc 対応 Kubernetes クラスターでオフライン アクセス用のシークレットをフェッチする

Kubernetes 用 Azure Key Vault シークレット ストア拡張機能 ("SSE") は、オフライン アクセスのために、Azure Key Vault から Azure Arc 対応 Kubernetes クラスター にシークレットを自動的に同期します。 つまり、半切断状態で Kubernetes クラスターを実行している場合でも、Azure Key Vault を使用してシークレットを格納、維持、ローテーションできます。 同期されたシークレットは、クラスター シークレット ストアに格納され、Kubernetes シークレットとして使用できるようになり、データ ボリュームとしてマウントされるや、ポッド内のコンテナーに環境変数として公開されるなどのいつもの方法で使用できます。

同期されたシークレットは重要なビジネス資産であるため、SSE は、分離された名前空間とノード、ロールベースのアクセス制御 (RBAC) ポリシー、シークレット シンクロナイザーの制限付きアクセス許可を使用してセキュリティで保護します。 保護を強化するには、クラスター上の Kubernetes シークレット ストアを暗号化します。

この記事では、SSE を Azure Arc 対応 Kubernetes の拡張機能としてインストールして構成する方法について説明します。

前提条件

• Arc 対応クラスター。 これは、自分自身に接続したもの (このガイド全体で例として K3s クラスターを使用しています)、または Microsoft が管理する Azure Arc で有効になっている AKS クラスターのいずれかです。 クラスターは Kubernetes バージョン 1.27 以降を実行し、サポートされているリージョンのいずれか (米国東部、米国東部 2、米国西部、米国西部 2、米国西部 3、西ヨーロッパ、北ヨーロッパ) で使用されている必要があります。 リージョンは、Arc クラスターの作成に使用されるリソース グループ リージョンによって定義されます。
• k8s-extension Azure CLI 拡張機能の最新バージョンを含め、クラスター拡張機能の一般的な前提条件を満たしていることを確認します。
• cert-manager は、クラスター内ログ通信の TLS をサポートするために必要です。 このガイドで後述する例で、手順を追ってインストールします。 cert-manager の詳細については、cert-manager.io を参照してください

Azure CLI をインストールしてサインインします (まだ行っていない場合)。

az login

開始する前に、Azure リソースとクラスター リソースの構成に使用する環境変数を設定します。 マネージド ID、Azure Key Vault、またはここに記載されているその他のリソースが既にある場合は、それらのリソースを反映するように環境変数の名前を更新します。

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"

クラスターでワークロード ID フェデレーションをアクティブにする

SSE は、ワークロード ID フェデレーションという機能を使用して Azure Key Vault シークレットにアクセスし、同期しています。 このセクションでは、これを設定する方法について説明します。 以下のセクションでは、その使用方法について詳しく説明します。

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

シークレットを作成し、それにアクセスするための ID を構成する

特定の Azure Key Vault シークレットにアクセスして同期するには、SSE では、そのシークレットにアクセスするための適切な Azure アクセス許可を持つ Azure マネージド ID へのアクセスが必要です。 マネージド ID は、先ほどアクティブにしたワークロード ID 機能を使用して Kubernetes サービス アカウントにリンクする必要があります。 SSE では、関連付けられているフェデレーションされた Azure マネージド ID を使用して、Azure Key Vault から Kubernetes シークレット ストアにシークレットをプルします。 以降のセクションでは、これを設定する方法について説明します。

Azure Key Vault を作成する

Azure Key Vault を作成してシークレットを追加します。 Azure Key Vault とシークレットが既にある場合は、このセクションをスキップしてください。

1. Azure Key Vault を作成します。

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

2. シークレットを作成できるように、自分にコンテナーに対する 'Secrets Officer' アクセス許可を付与します:

   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. シークレットを作成して更新し、次の 2 つのバージョンを使用できるようにします:

   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'
   

ユーザー割り当てマネージド ID を作成する

次に、ユーザー割り当てマネージド ID を作成し、Azure Key Vault にアクセスするためのアクセス許可を付与します。 Azure Key Vault に対する Key Vault 閲覧者と Key Vault シークレット ユーザーのアクセス許可を持つマネージド ID が既にある場合は、このセクションをスキップできます。 詳細については、「ユーザー割り当てマネージド ID の作成」および「Key Vault での Azure RBAC シークレット、キー、および証明書のアクセス許可の使用」を参照してください。

1. ユーザー割り当てマネージド ID の作成:

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

2. ID に Key Vault 閲覧者と Key Vault シークレット ユーザーのアクセス許可を付与します。 これらのコマンドが成功する前に、ID の作成のレプリケーションをしばらく待つ必要がある場合があります:

   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}
   

フェデレーション ID 資格情報を作成する

シークレットへのアクセスが必要なワークロードの Kubernetes サービス アカウントを作成します。 次に、マネージド ID、OIDC サービス アカウント発行者、および Kubernetes サービス アカウントの間でリンクする フェデレーション ID 資格情報 を作成します。

1. マネージド ID にフェデレーションされる Kubernetes サービス アカウントを作成します。 関連付けられているユーザー割り当てマネージド ID の詳細で注釈を付けます。

   kubectl create ns ${KUBERNETES_NAMESPACE}
   

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

2. フェデレーション ID 資格情報の作成:

   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}
   

SSE をインストールする

SSE は、Azure Arc 拡張機能として使用できます。 Azure Arc 対応の Kubernetes クラスター は、Azure Arc 対応 Kubernetes 拡張機能を使用して拡張できます。 拡張機能により、接続されたクラスターで Azure の機能が有効になり、拡張機能のインストールとライフサイクル管理に Azure Resource Manager 主導のエクスペリエンスが提供されます。

また、クラスター サービス間でログを安全に通信するには、cert-manager と trust-manager も必要であり、これらは Arc 拡張機能の前にインストールする必要があります。

1. 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. trust-manager をインストールします。

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

3. 次のコマンドを使用して、Arc 対応クラスターに SSE をインストールします。

   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 
   

   必要に応じて、必要に応じて、次の --configuration-settings rotationPollIntervalInSeconds=<time_in_seconds> を追加して、既定の回転ポーリング間隔を変更できます:

   パラメーター名	説明	規定値
   rotationPollIntervalInSeconds	SSE が管理しているシークレットを確認または更新する速度を指定します。	3600 (1 時間)

SSE を構成する

Kubernetes カスタム リソースのインスタンスを定義して、Azure Key Vault とクラスターに同期するシークレットに関する情報を使用して、インストールされている拡張機能を構成します。 次の 2 種類のカスタム リソースを作成します:

• Key Vault への接続を定義する SecretProviderClass オブジェクト。
• 同期する各シークレットの SecretSync オブジェクト。

SecretProviderClass リソースを作成する

SecretProviderClass リソースは、Azure Key Vault への接続、コンテナーへのアクセスに使用する ID、同期するシークレット、ローカルに保持する各シークレットのバージョンの数を定義するために使用されます。

同期する予定の Azure Key Vault ごとに、Azure Key Vault へのアクセスに使用される ID ごとに、およびターゲット Kubernetes 名前空間ごとに個別の SecretProviderClass が必要です。

この例に従って、Key Vault とシークレットの適切な値を持つ 1 つ以上の SecretProviderClass YAML ファイルを作成します。

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

SecretSync オブジェクトを作成します

同期された各シークレットには、クラスター固有の情報を定義するために、SecretSync オブジェクトも必要です。 ここでは、クラスター内のシークレットの名前や、クラスターに格納されているシークレットの各バージョンの名前などの情報を指定します。

このテンプレートに従って、シークレットごとに 1 つの SecretSync オブジェクト YAML ファイルを作成します。 Kubernetes 名前空間は、一致する SecretProviderClass の名前空間と一致する必要があります。

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

構成 CR を適用する

kubectl apply コマンドを使用して、構成カスタム リソース (CR) を適用します:

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

SSE は、シークレットを自動的に検索し、クラスターとの同期を開始します。

構成オプションの表示

これら 2 つのカスタム リソースの種類に対する追加の構成オプションを表示するには、kubectl describe コマンドを使用してクラスター内の CRD を検査します:

# 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

クラスターに同期しているシークレットを観察する

構成が適用されると、SSE のインストール時に指定した間隔で、シークレットがクラスターへの同期を自動的に開始します。

同期されたシークレットを表示する

次のコマンドを実行して、クラスターに同期されたシークレットを表示します:

# 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

最終同期状態の表示

特定のシークレットの最新の同期の状態を表示するには、SecretSync オブジェクトの kubectl describe コマンドを使用します。 出力には、シークレット作成タイムスタンプ、シークレットのバージョン、各同期イベントの詳細なステータス メッセージが含まれます。 この出力を使用して、接続または構成エラーを診断し、シークレット値がいつ変更するかを確認できます。

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

シークレットの値を表示する

Kubernetes シークレット ストアに格納された、同期されたシークレットの値を表示するには、次のコマンドを使用します:

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

トラブルシューティング

SSE は Kubernetes デプロイであり、1 つのポッドと 2 つのコンテナー、つまりクラスターへのシークレットの格納を管理するコントローラーと、Azure Key Vault へのアクセスと Azure Key Vault からのシークレットのプルを管理するプロバイダーが含まれます。 同期された各シークレットには、Azure Key Vault からクラスター シークレット ストアへのそのシークレットの同期の状態を含む SecretSync オブジェクトがあります。

問題のトラブルシューティングを行うには、「最後の同期状態の表示」の説明に従って、SecretSync オブジェクト状態を確認することから始めます。 次のテーブルに、一般的な状態の種類、その意味、およびエラーを解決するための潜在的なトラブルシューティング手順を示します。

SSE を削除する

SSE を削除し、シークレットの同期を停止するには、az k8s-extension delete コマンドを使用してアンインストールします。

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

拡張機能をアンインストールしても、シークレット、SecretSync オブジェクト、または CRD はクラスターから削除されません。 これらのオブジェクトは、kubectl を使用して直接削除する必要があります。

SecretSync CRD を削除すると、すべての SecretSync オブジェクトが削除され、既定ではすべての所有シークレットが削除されますが、シークレットは次の場合に保持される場合があります:

• いずれかのシークレットの所有権を変更しました。
• さまざまな ファイナライザー設定が含ふ、クラスター内の GC 設定を変更しました。

上記の場合、シークレットは kubectl を使用して直接削除する必要があります。

次のステップ

• Azure Arc 拡張機能の詳細を確認します。
• Azure Key Vault の詳細はこちらです。