適用於 Azure 部署之 Service Fabric 應用程式的 KeyVaultReference 支援

  • 發行項

建立雲端應用程式時常見的挑戰，即是找出將秘密安全發佈至應用程式並加以管理的方法。 Service Fabric KeyVaultReference 支援可讓您輕鬆進行。 設定之後，您可以參考儲存在應用程式定義金鑰保存庫中秘密的 URL，Service Fabric 會處理擷取該秘密，並使用該秘密啟用您的應用程式。 使用功能「SF 管理」版本時，Service Fabric 也可以監視您的金鑰保存庫，並在保存庫中輪替秘密時自動觸發滾動應用程式參數升級。

在 Service Fabric 中將秘密傳遞至應用程式的選項

將秘密傳遞至 Service Fabric 應用程式的傳統方式是宣告加密參數。 這涉及針對加密憑證加密秘密，並將這些加密的秘密傳遞至您的應用程式。 此方法有一些缺點：需要管理加密憑證、暴露部署管線中的秘密，以及缺少附加至已部署應用程式的秘密中繼資料的可見度。 同樣地，輪替秘密需要應用程式部署。 除非您執行獨立叢集，否則不再建議使用加密的參數。

另一個選項是使用秘密存放區參考。 此體驗可讓您集中管理應用程式秘密、更清楚瞭解已部署秘密的中繼資料，以及允許集中管理加密憑證。 在執行獨立 Service Fabric 叢集時，有些使用者可能會偏好這種秘密管理方式。

現今的建議是盡可能使用適用於 Service Fabric 應用程式的受控識別，減少對秘密的依賴。 受控識別可用於直接驗證 Azure 儲存體、Azure SQL 等等。 這表示存取支援 Microsoft Entra 驗證的 Azure 服務時，不需要管理個別的認證。

當無法使用受控識別作為用戶端時，建議您使用 KeyVaultReferences。 您應該使用 KeyVaultReferences，而不是使用受控識別直接移至金鑰保存庫。 KeyVaultReferences 有助於增加應用程式的可用性，因為其會強制執行輪流升級期間發生的秘密變更。 其也能更妥善調整，因為可從叢集中快取和提供秘密。 如果您的應用程式目前使用加密參數，則只有應用程式程式碼使用 KeyVaultReferences 所需的最少變更。 您的應用程式可以繼續預期會產生單一秘密，而且該秘密在流程的存留期內相同。

必要條件

  • Service Fabric 應用程式的受控識別

    Service Fabric KeyVaultReference 支援可使用應用程式的受控識別，以代表應用程式擷取秘密。 您必須透過 ARM 部署應用程式，並為其指派受控識別。 請依循本文件指示，以啟用應用程式的受控識別。

  • 秘密集中存放區 (CSS)。

    秘密集中存放區 (CSS) 為 Service Fabric 加密的本機秘密快取。 自 Key Vault 擷取秘密後，這項功能會使用 CSS 來保護和保存秘密。 若要使用 KeyVaultReferences，必須啟用此系統服務。 請依循此文件啟用和設定 CSS。

  • 將應用程式的受控識別存取權授與 Key Vault

    請參考此文件，了解如何將受控識別存取權授與 Key Vault。 另請注意，若使用系統所指派的受控識別，則受控識別只會在部署應用程式後建立。 這可能會建立競爭條件，在提供保存庫的身分識別存取權前，應用程式即會嘗試存取秘密。 系統指派的身分識別名稱將為 {cluster name}/{application name}/{service name}。

KeyVaultReference 與受控 KeyVaultReference

KeyVaultReferences 的基本概念是將其設定為 Key Vault URL，然後在應用程式啟用時解析為秘密值，而不是將應用程式參數的值設定為秘密。 例如，在 Key Vault 中，單一秘密 https://my.vault.azure.net/secrets/MySecret/ 可以有多個版本，例如 https://my.vault.azure.net/secrets/MySecret/<oid1> 和 <oid2>。 當您使用 KeyVaultReference 時，此值應該是版本化參考 (https://my.vault.azure.net/secrets/MySecret/<oid1>)。 例如，如果您將保存庫中的秘密輪替為 <oid2>，您應該觸發應用程式升級至新的參考。 當您使用 ManagedKeyVaultReference 時，此值應該是無版本參考 (https://my.vault.azure.net/secrets/MySecret/)。 Service Fabric 會解析最新的執行個體 <oid1>，並使用該秘密啟動應用程式。 如果您將保存庫中的秘密輪替為 <oid2>，Service Fabric 會自動觸發應用程式參數升級，以代表您移至 <oid2>。

注意

自 Service Fabric 版本 7.2 CU5 起正式推出 Service Fabric 應用程式的 KeyVaultReference (版本秘密) 支援。 在使用這項功能前，建議先升級至此版本。

注意

從 Service Fabric 9.0 版開始，適用於 Service Fabric 應用程式的受控 KeyVaultReference (版本無版本密碼) 支援正式推出。

在您的應用程式中使用 KeyVaultReferences

KeyVaultReferences 可使用於

作為環境變數

<EnvironmentVariables>
      <EnvironmentVariable Name="MySecret" Type="KeyVaultReference" Value="<KeyVaultURL>"/>
</EnvironmentVariables>

string secret =  Environment.GetEnvironmentVariable("MySecret");

以檔案形式掛接至您的容器

  • 在 settings.xml 中新增區段

    使用類型 KeyVaultReference 和值 <KeyVaultURL> 來定義 MySecret 參數

    <Section Name="MySecrets">
    <Parameter Name="MySecret" Type="KeyVaultReference" Value="<KeyVaultURL>"/>
</Section>

  • 參考 ApplicationManifest.xml 中 <ConfigPackagePolicies> 的新區段

    <ServiceManifestImport>
    <Policies>
    <IdentityBindingPolicy ServiceIdentityRef="MyServiceMI" ApplicationIdentityRef="MyApplicationMI" />
    <ConfigPackagePolicies CodePackageRef="Code">
        <!--Linux container example-->
        <ConfigPackage Name="Config" SectionName="MySecrets" EnvironmentVariableName="SecretPath" MountPoint="/var/secrets"/>
        <!--Windows container example-->
        <!-- <ConfigPackage Name="Config" SectionName="dbsecrets" EnvironmentVariableName="SecretPath" MountPoint="C:\secrets"/> -->
    </ConfigPackagePolicies>
    </Policies>
</ServiceManifestImport>

  • 使用服務程式代碼中的秘密

    <Section Name=MySecrets> 下所列的各參數皆是 EnvironmentVariable SecretPath 所指向資料夾下的檔案。 下列 C# 程式碼片段說明如何自應用程式讀取 MySecret。

    string secretPath = Environment.GetEnvironmentVariable("SecretPath");
using (StreamReader sr = new StreamReader(Path.Combine(secretPath, "MySecret"))) 
{
    string secret =  sr.ReadToEnd();
}

    注意

    掛接點用於控制含秘密值檔案要掛接的資料夾。

作為容器存放庫密碼的參考

 <Policies>
      <ContainerHostPolicies CodePackageRef="Code">
        <RepositoryCredentials AccountName="MyACRUser" Type="KeyVaultReference" Password="<KeyVaultURL>"/>
      </ContainerHostPolicies>

在您的應用程式中使用受控 KeyVaultReferences

首先，除了其他必要的 CSS 設定之外，您還必須透過升級叢集定義以新增 EnableSecretMonitoring 設定來啟用秘密監視：

"fabricSettings": [
    {
        "name": "CentralSecretService",     
        "parameters": [
            {
                "name": "EnableSecretMonitoring",
                "value": "true"
            },
            {
                "name":  "DeployedState",
                "value":  "enabled"
            },
            {
                "name" : "EncryptionCertificateThumbprint",
                "value": "<thumbprint>"
            },
            {
                "name":  "MinReplicaSetSize",
                "value":  "<size>"
            },
            {
                "name":  "TargetReplicaSetSize",
                "value":  "<size>"
            }
        ]
    }
],

注意

預設值未來可能會變成 true

完成叢集升級後，即可升級您的使用者應用程式。 在可以使用 KeyVaultReference 的任何位置，也可以使用 ManagedKeyVaultReference，例如，

    <Section Name="MySecrets">
        <Parameter Name="MySecret" Type="ManagedKeyVaultReference" Value="[MySecretReference]"/>
    </Section>

指定 ManagedKeyVaultReferences 的主要差異在於「無法」在您的應用程式類型資訊清單中對其進行硬式編碼。 其必須宣告為應用層級參數，而且必須在 ARM 應用程式定義中進一步加以覆寫它。

以下是來自語式正確資訊清單的摘錄

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest ApplicationTypeName="MyAppType" ApplicationTypeVersion="1.0.0">
  <Parameters>
    <Parameter Name="MySecretReference" DefaultValue="" />
  </Parameters>
  <ServiceManifestImport>
    <EnvironmentOverrides CodePackageRef="Code">
      <EnvironmentVariable Name="MySecret" Value="[MySecretReference]" Type="ManagedKeyVaultReference" />
    </EnvironmentOverrides>
    <Policies>
      <IdentityBindingPolicy ServiceIdentityRef="MySvcIdentity" ApplicationIdentityRef="MyAppIdentity" />
    </Policies>
  </ServiceManifestImport>
  <Principals>
    <ManagedIdentities>
      <ManagedIdentity Name="MyAppIdentity" />
    </ManagedIdentities>
  </Principals>
</ApplicationManifest>

以及應用程式資源定義的摘錄：

{
    "type": "Microsoft.ServiceFabric/clusters/applications",
    "name": "MyApp",
    "identity": {
        "type" : "userAssigned",
        "userAssignedIdentities": {
            "[variables('userAssignedIdentityResourceId')]": {}
        }
    },
    "properties": {
        "parameters": {
            "MySecretReference": "https://my.vault.azure.net/secrets/MySecret/"
        },
        "managedIdentities": [
            {
            "name" : "MyAppIdentity",
            "principalId" : "<guid>"
            }
        ]
    }
}

Service Fabric 需要同時將 ManagedKeyVaultReference 宣告為應用程式參數，以及在部署時覆寫該參數，才能成功管理已部署秘密的生命週期。

下一步