Secrets Management

UCS 中的 Secrets 使用文件实现。微服务必须从文件中读取 secrets。它们不需要知道文件是如何在容器中创建/挂载的。这创建了一个抽象层，可以从微服务中移除对任何特定类型 secrets 管理的依赖。

UCS 应用程序负责集成 secrets 管理系统，并将 secret 正确挂载为微服务期望位置的文件。

在微服务中指定 secret 要求

微服务的 Secret 要求可以在微服务构建器输入 manifest.yaml 文件的 secrets 字段下描述，具体请参考 - Secrets。

secrets 预计将挂载在 <mountPath>/<fileName>，如 manifest 中指定。

任何在微服务内部运行且需要 secret 的应用程序都必须从此路径读取它。占位符 $secrets.<name>.path 可以用来代替 manifest.yaml 或 configs 目录内文件中的挂载路径。所有占位符实例都将在微服务 helm chart 构建期间被实际挂载路径 <mountPath>/<fileName> 替换。

查看微服务的 secret 要求

使用 CLI 工具

可以使用以下任一 CLI 工具查看任何微服务的 secret 要求 - UCS 微服务构建器 CLI 或 UCS 应用程序构建器 CLI，使用 service info 命令。

例如

$ ucf_ms_builder_cli service info -n ucf.svc.myservice
...
secrets:
-   name: some-secret-name
    description: Description for the secret
    mandatory: true
    mountPath: /secrets
    fileName: someSecretFileName
...

此微服务期望将 secret some-secret-name 挂载在 /secrets/someSecretFileName。

使用 UCS Studio

可以在 UCS Studio 中查看微服务的 Secret 要求，方法是创建一个新图，在图画布中添加所需的微服务，单击选择它，然后查看右侧属性窗口中的 Secrets 部分。

UCS Studio - Viewing Secrets Requirements

在 UCS 应用程序中满足 secret

使用 UCS Studio

首先右键单击图窗口打开上下文菜单，然后选择 配置器，打开图配置。

接下来选择 Secrets 窗口，单击添加以添加新的 secret。根据需要输入详细信息，包括 secret 的来源 Kubernetes Secret、Vault、Secrets Store CSI Driver、Certificate 和特定于来源的详细信息

现在在画布上选择一个微服务，这将在右侧的属性窗口中显示 Secrets 部分。对于每个 secret 要求，从下拉列表中选择一个 secret 来设置它。

使用文本表示和 CLI 工具

必须为每个微服务指定所有强制性 secret。需要在应用程序中使用的 secret（因此在微服务上设置）必须添加到应用程序的 secrets 部分，以及 secret 的来源详细信息。UCS Tools 支持 Kubernetes Secret、Vault、Certificate 或 Secrets Store CSI Driver 作为 secret 的来源。secrets 必须在 UCS 应用程序 YAML 中按如下方式指定

secrets:
  <secret-identifier>:
    <k8sSecret|vaultAgent|secretsStoreCsi|certificate>:
      <source specific details>

  <secret-identifier-1>:
    <k8sSecret|vaultAgent|secretsStoreCsi|certificate>:
      <source specific details>

根据 secret 的来源，必须指定其他详细信息。

这些 secrets 可以在需要它们的微服务的 components 中的 secrets 字段下设置在应用程序图文件中。格式为

components:
- name: <svc-name>
  type: <svc-ucf-type>
  secrets:
    <secretName1>: <secret-identifier>
    <secretName2>: <secret-identifier-1>

- name: <svc-name-1>
  type: <svc-ucf-type-1>
  secrets:
    <secretName>: <secret-identifier-1>

支持的 Secret 管理类型

UCS Tools 支持 Kubernetes Secret、Vault、Certificate 或 Secrets Store CSI Driver 作为 secret 的来源。

使用 Kubernetes `Secret`

可以使用以下格式将 Kubernetes Secret 添加到应用程序

secrets:
  <secret-identifier>:
    k8sSecret:
      secretName: <Name-of-K8S-Secret-Resource>
      key: <Key-in-K8S-Secret>

使用 Kubernetes Secret 作为 secret 来源的应用程序图文件示例

specVersion: 2.5.0

version: 0.0.1

name: myservice-test

...

dependencies:
- ucf.svc.myservice:0.0.1

components:
- name: myservice
  type: ucf.svc.myservice
  parameters:
    timeToSleep: 1200000
  secrets:
    some-secret-name: db-username
...

connections:
  ...

secrets:
  db-username:
    k8sSecret:
      secretName: db-creds-k8s-secret
      key: username

在 UCS Studio 中也可以实现相同的效果，方法是从类型下拉列表中选择 K8S Secret，并为 Secret 名称 和 Key 设置有效值

UCS Studio - Secrets - Kubernetes Secret

对于 Kubernetes Secret 作为 secret 的来源，应用程序部署者有责任确保名为 <Name-of-K8S-Secret-Resource> 的 Kubernetes secret 包含 key <Key-in-K8S-Secret> 已经部署。例如，在这种情况下，可以使用以下命令完成：

$ kubectl create secret generic db-creds-k8s-secret --from-literal=username=admin

在构建应用程序时，UCS 应用程序构建器 CLI 工具将添加适当的参数，以将 secret db-creds-k8s-secret 的 key username 挂载到微服务容器中预期的位置 /secrets/someSecretFileName。

使用 `Vault` secrets

UCS 应用程序构建器 CLI 工具支持与 Hashicorp Vault 集成以进行 secrets 管理。应用程序开发人员应了解如何管理 Vault 服务器、向其添加 secrets 以及使用 JWT 方法对 Kubernetes 集群进行 Vault 身份验证。有关 Vault 的文档，请参阅 - https://developer.hashicorp.com/vault。

对于 Vault 作为 secret 的来源，vaultAgent 参数必须添加到应用程序中，该参数指定 Vault 服务器的连接和身份验证详细信息。vaultAgent 的规范是

vaultAgent:
  auth:
    path: "<vault-jwt-auth-mount-path>"
    type: "jwt"
    jwt:
      audience: "<bound-audience>"
      role: "<vault-role>"
  role: "<vault-role>"
  namespace: "<vault-namespace>"
  service: "<vault-host>"

可以使用以下格式将基于 Vault 的 secret 添加到应用程序

secrets:
  <secret-identifier>:
    vaultAgent:
      path: "<path-to-secret-in-vault-server>"
      template:
        # Following type is used for KV secrets engine of Vault
        type: kv
        key: "<key-in-secret>"

  <secret-identifier-1>:
    vaultAgent:
      path: "<path-to-secret-in-vault-server>"
      template:
        # Following type is used for X.509 PKI certificate engine of Vault
        type: pki/certificate      # OR "pki/private_key" OR "pki/issuing_ca" #
        common_name: <common-name>  # Common name to use when requesting certificate from Vault
        ttl: <ttl>                  # TTL for the certificates e.g. 720h

  <secret-identifier-2>:
    vaultAgent:
      path: "<path-to-secret-in-vault-server>"
      # Following can be used for custom templates using the Consul template language.
      template: |
        {{- with secret "<path-to-secret-in-vault-server>" }}
        {{- .Data.data.username }}:{{ .Data.data.password }}
        {{- end }}

一个使用示例是

specVersion: 2.5.0

version: 0.0.1

name: myservice-test

...

dependencies:
- ucf.svc.myservice:0.0.1

components:
- name: myservice
  type: ucf.svc.myservice
  parameters:
    timeToSleep: 1200000
  secrets:
    some-secret-name: db-username
...

connections:
  ...

vaultAgent:
  auth:
    path: auth/jwt/my-cluster
    type: "jwt"
    jwt:
      audience: custom-audience
      role: my-auth-role
  role: my-auth-role
  namespace: my-namespace
  service: https://vault.example.com

secrets:
  db-username:
    vaultAgent:
      path: my-app-kv/db-creds
      template:
        type: kv
        key: username

您也可以在 UCS Studio 中实现这一点，首先填写 图配置器 中的 Vault Agent 部分。

然后从 secret 的类型下拉列表中选择 Vault，并在 Vault 服务器中设置有效的 secret 路径。根据 secret 的类型，从 模板类型 下拉列表中选择 kv / pki/certificate / pki/private_key / pki/issuing_ca，并指定其他信息，如 key、common_name、ttl。要指定用于渲染模板的原始模板字符串，请从 模板类型 下拉列表中选择 string。

在此示例中，应用程序开发人员负责确保：

Vault 服务器托管在 https://vault.example.com
正在使用 Vault 服务器的命名空间 my-namespace
vault 的 JWT 身份验证方法在路径 auth/jwt/my-cluster 启用
配置身份验证方法时，bound_audience 设置为 custom-audience
身份验证方法已配置 bound_subject，允许 some-service-account 访问
身份验证方法已配置 my-auth-role 身份验证角色
已在 my-app-kv 创建并配置 KV2 secrets 引擎
已在挂载路径 my-app-kv/db-creds 创建 KV2 secret
KV2 secret 包含 key username
已配置策略，允许 my-auth-role 角色访问 my-app-kv/db-creds
Vault Agent Injector Service 已经在集群上运行

在构建应用程序时，UCS 应用程序构建器 CLI 工具将添加适当的参数，以将 Vault 服务器中路径 my-app-kv/db-creds 的 secret 的 key username 的值挂载到微服务容器中预期的位置 /secrets/someSecretFileName。

使用 `Secrets Store CSI Driver`

UCS 应用程序构建器 CLI 工具支持与 Secrets Store CSI Driver 集成以进行 secrets 管理。应用程序开发人员应了解如何安装 Secrets Store CSI Driver 和 SecretProviderClass，后者提及要用作 secrets 的对象。有关文档，请参阅 - https://secrets-store-csi-driver.sigs.k8s.io/getting-started/getting-started.html。

可以使用以下格式将基于 Secrets Store CSI Driver 的 Secret 添加到应用程序

secrets:
  <secret-identifier>:
    secretsStoreCsi:
      providerClassName: <Secret-Provider-Class-Resource-Name>
      objectName: <Name-of-Object-in-Secret-Provider-Class-Resource>

使用 Secrets Store CSI Driver 作为 secret 来源的应用程序图文件示例

specVersion: 2.5.0

version: 0.0.1

name: myservice-test

...

dependencies:
- ucf.svc.myservice:0.0.1

components:
- name: myservice
  type: ucf.svc.myservice
  parameters:
    timeToSleep: 1200000
  secrets:
    some-secret-name: db-username
...

connections:
  ...

secrets:
  db-username:
    secretsStoreCsi:
      providerClassName: azure-secrets-sync
      objectName: db-username

在 UCS Studio 中也可以实现相同的效果，方法是从类型下拉列表中选择 Secrets Store CSI，并为 Secret Provider Class Name 和 Object Name 设置有效值。

UCS Studio - Secrets - Secrets Store CSI Driver

对于基于 Secrets Store CSI Driver 的 Secret 作为 secret 的来源，应用程序部署者有责任确保名为 <Secret-Provider-Class-Resource-Name> 的 SecretProviderClass 资源包含名为 <Name-of-Object-in-Secret-Provider-Class-Resource> 的对象已经部署。

在构建应用程序时，UCS 应用程序构建器 CLI 工具将添加适当的参数，以将 SecretProviderClass 资源中名为 azure-secrets-sync 的对象 db-username 挂载到微服务容器中预期的位置 /secrets/someSecretFileName。

使用 cert-manager `Certificate`

UCS 应用程序构建器 CLI 工具支持与 cert-manager 集成以进行证书管理。应用程序开发人员应了解如何安装 cert-manager 以及用于配置证书并创建相应 Kubernetes Secret 的 Certificate 和 Issuer/ClusterIssuer 自定义资源。有关文档，请参阅 - https://cert-manager.k8s.ac.cn/docs/

对于 cert-manager Certificate 作为 secret 的来源，certificates 参数必须添加到应用程序中，该参数指定应用程序将需要的证书和一些其他详细信息。证书的规范是

certificates:
  <nameForCertificates>:
    file: <path-to-certificates-file>
    addToHelmChart: <true|false>
  <nameForCertificates-2>:
    file: <path-to-certificates-file-2>
    addToHelmChart: <true|false>

证书文件路径可以是绝对路径，也可以是相对于应用程序 YAML 文件的相对路径。该文件必须包含 cert-manager Certificate/Issuer/ClusterIssuer 自定义资源。此文件的示例为

---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: self-signed-issuer
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: self-signed-certificate
spec:
  dnsNames:
    - cluster.local
    - test.cluster.local
  secretName: selfsigned-cert-tls
  issuerRef:
    name: self-signed-issuer

可以使用以下格式将基于 Certificate 的 Secret 添加到应用程序

secrets:
  <secret-identifier>:
    certificate:
      certName: <Name-of-Certificate-Resource>
      type: <certificate/privateKey/issuingCA> # Whether to mount the certificate file or the private key file or the issuing CA file
  <secret-identifier-2>:
    certificate:
      # Use this if you do not wish to provide a certificates file and
      # instead provide the secret name that will contain the certificate files
      isExternal: true
      secretName: <name-of-secret-created-by-cert-manager>
      type: <certificate/privateKey/issuingCA>

使用 cert-manager Certificate 作为 secret 来源的应用程序图文件示例

specVersion: 2.5.0

version: 0.0.1

name: myservice-test

...

dependencies:
- ucf.svc.myservice:0.0.1

components:
- name: myservice
  type: ucf.svc.myservice
  parameters:
    timeToSleep: 1200000
  secrets:
    tls-cert: app-tls-cert
    tls-key: app-tls-key
    tls-ca: app-tls-ca
...

connections:
  ...

certificates:
  devCerts:
    file: certificates.yaml
    addToHelmChart: true

secrets:
  app-tls-cert:
    certificate:
      certName: self-signed-certificate
      type: certificate
  app-tls-key:
    certificate:
      certName: self-signed-certificate
      type: privateKey
  app-tls-ca:
    certificate:
      certName: self-signed-certificate
      type: issuingCA

在 UCS Studio 中也可以实现相同的效果，方法是从 证书文件 选项卡加载包含 Certificate 资源的文件。

UCS Studio - Secrets - Certificates Files

然后从类型下拉列表中选择 Certificate，并选择适用的 Certificate 名称 和要挂载的文件 Certificate、Private Key 或 Issuing CA。如果使用外部创建的 Certificate 资源，请选择 Is External，然后输入为 Certificate 创建的 secret 资源的 Secret 名称。

对于基于 Certificate 的 Secret 作为 secret 的来源，应用程序部署者有责任：

确保通过 certificates 字段向应用程序提供名为 <Name-of-Certificate-Resource> 的 Certificate 资源。
- 如果 addToHelmChart 为 false，则必须手动部署 Certificate 资源。
或者，如果将 secretName 与 isExternal 一起使用，则已部署 secretName 设置为 <name-of-secret-created-by-cert-manager> 的 Certificate 资源

在构建应用程序时，UCS 应用程序构建器 CLI 工具将添加适当的参数，以将名为 self-signed-certificate 的 Certificate 资源的 TLS 证书/私钥/颁发 CA 挂载到微服务容器中的预期位置。

应用程序信息 - Secrets

构建应用程序会在输出目录中生成应用程序信息文件。此文件包含应用程序中添加的 secrets 列表及其详细信息。有关更多信息，请参阅应用程序信息。

Secrets Management

在微服务中指定 secret 要求

查看微服务的 secret 要求

使用 CLI 工具

使用 UCS Studio

在 UCS 应用程序中满足 secret

使用 UCS Studio

使用文本表示和 CLI 工具

支持的 Secret 管理类型

使用 Kubernetes Secret

使用 Vault secrets

使用 Secrets Store CSI Driver

使用 cert-manager Certificate

应用程序信息 - Secrets

使用 Kubernetes `Secret`

使用 `Vault` secrets

使用 `Secrets Store CSI Driver`

使用 cert-manager `Certificate`