Service Fabric 应用程序的 KeyVaultReference 支持(预览版)KeyVaultReference support for Service Fabric applications (preview)

构建云应用程序时,一个常见的难题是如何安全存储应用程序所需的机密。A common challenge when building cloud applications is how to securely store secrets required by your application. 例如,你可能想要将容器存储库凭据存储在 keyvault 中,并在应用程序清单中引用它。For example, you might want to store the container repository credentials in keyvault and reference it in application manifest. Service Fabric KeyVaultReference 使用 Service Fabric 托管标识,并为引用 keyvault 机密提供方便。Service Fabric KeyVaultReference uses Service Fabric Managed Identity and makes it easy to reference keyvault secrets. 本文的余下内容将详细介绍如何使用 Service Fabric KeyVaultReference,并提供一些典型用法。The remainder of this article details how to use Service Fabric KeyVaultReference and includes some typical usage.

重要

不建议在生产环境中使用此预览功能。Use of this preview feature is not recommended in production environments.

备注

KeyVault 引用预览功能仅支持经版本控制的机密。KeyVault Reference Preview feature supports only versioned secrets. 不支持无版本的机密。Versionless secrets are not supported.

先决条件Prerequisites

  • 应用程序的托管标识 (MIT)Managed Identity for Application (MIT)

    Service Fabric KeyVaultReference 支持使用应用程序的托管标识,因此,计划使用 KeyVaultReferences 的应用程序应使用托管标识。Service Fabric KeyVaultReference support uses application's Managed Identity and therefore applications planing to use KeyVaultReferences should use Managed Identity. 可遵循此文档为应用程序启用托管标识。Follow this document to enable managed identity for your application.

  • 中心机密存储 (CSS)。Central Secrets Store (CSS).

    中心机密存储 (CSS) 是 Service Fabric 的已加密本地机密缓存。Central Secrets Store (CSS) is Service Fabric's encrypted local secrets cache. CSS 是一个本地机密存储缓存,用于保存敏感数据,例如,已在内存中加密的密码、令牌和密钥。CSS is a local secret store cache that keeps sensitive data, such as a password, tokens, and keys, encrypted in memory. KeyVaultReference 在提取后会缓存在 CSS 中。KeyVaultReference, once fetched, are cached in CSS.

    将以下内容添加到群集配置中的 fabricSettings 下,即可为 KeyVaultReference 支持启用所需的所有功能。Add the below to your cluster configuration under fabricSettings to enable all the required features for KeyVaultReference support.

    "fabricSettings": 
    [
        ...
        {
            "name":  "CentralSecretService",
            "parameters":  [
                {
                    "name":  "IsEnabled",
                    "value":  "true"
                },
                {
                    "name":  "MinReplicaSetSize",
                    "value":  "3"
                },
                {
                    "name":  "TargetReplicaSetSize",
                    "value":  "3"
                }
            ]
        },
        {
            "name":  "ManagedIdentityTokenService",
            "parameters":  [
                {
                    "name":  "IsEnabled",
                    "value":  "true"
                }
            ]
        }
    ]
    

    备注

    建议对 CSS 使用单独的加密证书。It's recommended to use a separate encryption certificate for CSS. 可将此证书添加到“CentralSecretService”节下。You can add it under the "CentralSecretService" section.

    {
        "name": "EncryptionCertificateThumbprint",
        "value": "<EncryptionCertificateThumbprint for CSS>"
    }
    

    若要让更改生效,还需更改升级策略,指定在升级进展到群集时,在每个节点上以强制方式重启 Service Fabric 运行时。In order for the changes to take effect, you will also need to change the upgrade policy to specify a forceful restart of the Service Fabric runtime on each node as the upgrade progresses through the cluster. 此重启确保新启用的系统服务在每个节点上启动并运行。This restart ensures that the newly enabled system service is started and running on each node. 在下面的代码片段中,forceRestart 是基本设置;请对其余设置使用你的现有值。In the snippet below, forceRestart is the essential setting; use your existing values for the remainder of the settings.

    "upgradeDescription": {
        "forceRestart": true,
        "healthCheckRetryTimeout": "00:45:00",
        "healthCheckStableDuration": "00:05:00",
        "healthCheckWaitDuration": "00:05:00",
        "upgradeDomainTimeout": "02:00:00",
        "upgradeReplicaSetCheckTimeout": "1.00:00:00",
        "upgradeTimeout": "12:00:00"
    }
    
  • 向应用程序的托管标识授予对 keyvault 的访问权限Grant application's managed identity access permission to the keyvault

    参考此文档来了解如何向托管标识授予对 keyvault 的访问权限。Reference this document to see how to grant managed identity access to keyvault. 另请注意,如果使用系统分配的托管标识,则只会在部署应用程序之后才创建托管标识。Also note if you are using System Assigned Managed Identity, the managed identity is created only after application deployment.

用作应用程序参数的 Keyvault 机密Keyvault secret as application parameter

假设应用程序需要读取存储在 keyvault 中的后端数据库密码,Service Fabric KeyVaultReference 支持可以轻松实现此目的。Let's say the application needs to read the backend database password stored in keyvault, Service Fabric KeyVaultReference support makes it easy. 以下示例使用 Service Fabric KeyVaultReference 支持从 keyvault 中读取 DBPassword 机密。Below example reads DBPassword secret from keyvault using Service Fabric KeyVaultReference support.

  • 将一个节添加到 settings.xmlAdd a section to settings.xml

    定义类型为 KeyVaultReference、值为 <KeyVaultURL>DBPassword 参数Define DBPassword parameter with Type KeyVaultReference and Value <KeyVaultURL>

    <Section Name="dbsecrets">
        <Parameter Name="DBPassword" Type="KeyVaultReference" Value="https://vault200.vault.azure.cn/secrets/dbpassword/8ec042bbe0ea4356b9b171588a8a1f32"/>
    </Section>
    
  • <ConfigPackagePolicies> 中引用 ApplicationManifest.xml 中的新节Reference the new section in ApplicationManifest.xml in <ConfigPackagePolicies>

    <ServiceManifestImport>
        <Policies>
        <IdentityBindingPolicy ServiceIdentityRef="WebAdmin" ApplicationIdentityRef="ttkappuser" />
        <ConfigPackagePolicies CodePackageRef="Code">
            <!--Linux container example-->
    
            <ConfigPackage Name="Config" SectionName="dbsecrets" EnvironmentVariableName="SecretPath" MountPoint="/var/secrets"/>
            <!--Windows container example-->
    
            <!-- <ConfigPackage Name="Config" SectionName="dbsecrets" EnvironmentVariableName="SecretPath" MountPoint="C:\secrets"/> -->
    
        </ConfigPackagePolicies>
        </Policies>
    </ServiceManifestImport>
    
  • 在应用程序中使用 KeyVaultReferenceUsing KeyVaultReference in your application

    服务实例化时,Service Fabric 将使用应用程序的托管标识来解析 KeyVaultReference 参数。Service Fabric on service instantiation will resolve the KeyVaultReference Parameter using application's managed identity. <Section Name=dbsecrets> 下面列出的每个参数将是 EnvironmentVariable SecretPath 指向的文件夹下的某个文件。Each parameter listed under <Section Name=dbsecrets> will be a file under the folder pointed to by EnvironmentVariable SecretPath. 以下 C# 代码片段演示如何在应用程序中读取 DBPassword。Below C# code snippet show how to read DBPassword in your application.

    string secretPath = Environment.GetEnvironmentVariable("SecretPath");
    using (StreamReader sr = new StreamReader(Path.Combine(secretPath, "DBPassword"))) 
    {
        string dbPassword =  sr.ReadToEnd();
        // dbPassword to connect to DB
    }
    

    备注

    对于容器方案,可以使用 MountPoint 来控制 secrets 的装载位置。For the container scenario, you can use the MountPoint to control where the secrets will be mounted.

用作环境变量的 Keyvault 机密Keyvault secret as environment variable

Service Fabric 环境变量现在支持 KeyVaultReference 类型。以下示例演示如何将环境变量绑定到 KeyVault 中存储的机密。Service Fabric environment variables now support KeyVaultReference type, below example shows how to bind an environment variable to a secret stored in KeyVault.

<EnvironmentVariables>
      <EnvironmentVariable Name="EventStorePassword" Type="KeyVaultReference" Value="https://ttkvault.vault.azure.cn/secrets/clustercert/e225bd97e203430d809740b47736b9b8"/>
</EnvironmentVariables>
string eventStorePassword =  Environment.GetEnvironmentVariable("EventStorePassword");

用作容器存储库密码的 Keyvault 机密Keyvault secret as container repository password

KeyVaultReference 是容器 RepositoryCredentials 支持的类型。以下示例演示如何使用 keyvault 引用作为容器存储库密码。KeyVaultReference is a supported type for container RepositoryCredentials, below example shows how to use a keyvault reference as container repository password.

 <Policies>
      <ContainerHostPolicies CodePackageRef="Code">
        <RepositoryCredentials AccountName="user1" Type="KeyVaultReference" Password="https://ttkvault.vault.azure.cn/secrets/containerpwd/e225bd97e203430d809740b47736b9b8"/>
      </ContainerHostPolicies>

常见问题解答FAQ

  • 需要为 KeyVaultReference 支持启用托管标识,如果在未启用托管标识的情况下使用 KeyVaultReference,应用程序激活将会失败。Managed identity needs to be enabled for KeyVaultReference support, your application activation will fail if KeyVaultReference is used without enabling Managed Identity.

  • 如果使用系统分配的标识,则只会在部署应用程序之后才创建该标识,而这会造成循环依赖关系。If you are using system assigned identity, it's created only after the application is deployed and this creates a circular dependency. 部署应用程序后,可向系统分配的标识授予对 keyvault 的访问权限。Once your application is deployed, you can grant the system assigned identity access permission to keyvault. 可按名称 {cluster}/{application name}/{servicename} 查找系统分配的标识。You can find the system assigned identity by name {cluster}/{application name}/{servicename}

  • keyvault 需与 Service Fabric 群集位于同一订阅中。The keyvault needs to be in the same subscription as your service fabric cluster.

后续步骤Next steps