Vault 後端

Spring Cloud Config Server 也支援使用 Vault 作為後端。

Vault 是一個安全訪問秘密的工具。秘密是指您希望嚴密控制訪問的任何內容，例如 API 金鑰、密碼、證書和其他敏感資訊。Vault 為任何秘密提供統一介面，同時提供嚴密的訪問控制並記錄詳細的審計日誌。

有關 Vault 的更多資訊，請參閱 Vault 快速入門指南。

要使 Config Server 使用 Vault 後端，您可以使用 vault profile 執行 Config Server。例如，在您的 Config Server 的 application.properties 中，您可以新增 spring.profiles.active=vault。

預設情況下，Spring Cloud Config Server 使用基於令牌的身份驗證從 Vault 獲取配置。Vault 還支援其他身份驗證方法，如 AppRole、LDAP、JWT、CloudFoundry、Kubernetes Auth。為了使用 TOKEN 或 X-Config-Token 請求頭以外的任何身份驗證方法，我們需要在類路徑中包含 Spring Vault Core，以便 Config Server 可以將身份驗證委託給該庫。請將以下依賴項新增到您的 Config Server App 中。

Maven (pom.xml)

<dependencies>
	<dependency>
		<groupId>org.springframework.vault</groupId>
		<artifactId>spring-vault-core</artifactId>
	</dependency>
</dependencies>

Gradle (build.gradle)

dependencies {
    implementation "org.springframework.vault:spring-vault-core"
}

預設情況下，Config Server 假設您的 Vault 伺服器執行在 127.0.0.1:8200。它還假設後端名稱為 secret，鍵為 application。所有這些預設值都可以在 Config Server 的 application.properties 中配置。下表描述了可配置的 Vault 屬性。

名稱 預設值

host

127.0.0.1

port

8200

scheme

http

backend

secret

defaultKey

application

defaultLabel

main（僅在 enableLabel 設定為 true 時使用）

enableLabel

false

profileSeparator

,

kvVersion

1

skipSslValidation

false

timeout

5

namespace

null
前述表格中的所有屬性必須以 spring.cloud.config.server.vault 為字首，或者放在複合配置中正確的 Vault 部分下。

所有可配置屬性可以在 org.springframework.cloud.config.server.environment.VaultEnvironmentProperties 中找到。

Vault 0.10.0 引入了版本化的鍵值後端（k/v 後端版本 2），它提供了與早期版本不同的 API。現在，它要求在掛載路徑和實際上下文路徑之間有一個 data/，並將秘密包裝在 data 物件中。設定 spring.cloud.config.server.vault.kv-version=2 將考慮此特性。

可選地，支援 Vault Enterprise 的 X-Vault-Namespace 請求頭。要將其傳送到 Vault，請設定 namespace 屬性。

Config Server 啟動後，您可以向伺服器發出 HTTP 請求以從 Vault 後端檢索值。為此，您需要 Vault 伺服器的令牌。

首先，在您的 Vault 中放置一些資料，示例如下：

$ vault kv put secret/application foo=bar baz=bam
$ vault kv put secret/myapp foo=myappsbar

其次，向您的 Config Server 發出 HTTP 請求以檢索值，示例如下：

$ curl -X "GET" "https://:8888/myapp/default" -H "X-Config-Token: yourtoken"

您應該看到類似以下的響應：

{
   "name":"myapp",
   "profiles":[
      "default"
   ],
   "label":null,
   "version":null,
   "state":null,
   "propertySources":[
      {
         "name":"vault:myapp",
         "source":{
            "foo":"myappsbar"
         }
      },
      {
         "name":"vault:application",
         "source":{
            "baz":"bam",
            "foo":"bar"
         }
      }
   ]
}

客戶端向 Config Server 提供必要身份驗證以使其與 Vault 通訊的預設方法是設定 X-Config-Token 請求頭。但是，您可以省略此請求頭，並在伺服器端配置身份驗證，方法是設定與 Spring Cloud Vault 相同的配置屬性。需要設定的屬性是 spring.cloud.config.server.vault.authentication。應將其設定為受支援的身份驗證方法之一。您可能還需要設定特定於您使用的身份驗證方法的其他屬性，方法是使用與 spring.cloud.vault 文件中相同的屬性名稱，但改用 spring.cloud.config.server.vault 字首。有關更多詳細資訊，請參閱 Spring Cloud Vault 參考指南。

如果您省略 X-Config-Token 請求頭並使用伺服器屬性來設定身份驗證，則 Config Server 應用程式需要額外依賴 Spring Vault 以啟用額外的身份驗證選項。有關如何新增該依賴項的資訊，請參閱 Spring Vault 參考指南。

多個屬性源

使用 Vault 時，您可以為應用程式提供多個屬性源。例如，假設您已將資料寫入 Vault 中的以下路徑：

secret/myApp,dev
secret/myApp
secret/application,dev
secret/application

寫入 secret/application 的屬性可供使用 Config Server 的所有應用程式使用。名為 myApp 的應用程式將可以使用寫入 secret/myApp 和 secret/application 的任何屬性。當 myApp 啟用了 dev profile 時，寫入上述所有路徑的屬性都可供其使用，列表中的第一個路徑中的屬性優先於其他路徑中的屬性。

啟用按標籤搜尋

預設情況下，Vault 後端在搜尋秘密時不使用標籤。您可以透過將 enableLabel 特性標誌設定為 true，並可選地設定 defaultLabel 來更改此行為。如果未提供 defaultLabel，將使用 main。

當 enableLabel 特性標誌開啟時，Vault 中的秘密在其路徑中應始終包含所有三個部分（應用程式名稱、profile 和標籤）。因此，上一節中的示例在啟用此特性標誌後將類似於：

secret/myApp,dev,myLabel
secret/myApp,default,myLabel       # default profile
secret/application,dev,myLabel     # default application name
secret/application,default,myLabel # default application name and default profile.

解密屬性源中的 Vault 秘密

Spring Cloud Config Server 支援透過利用特殊的佔位符字首 {vault} 來解密 Vault 中的屬性。此功能允許在執行時直接從 Vault 動態解析敏感配置屬性。

配置步驟

所有與 Vault 整合的配置設定應放置在您的 application.yml 或 application.properties 中。以下是啟用 Vault profile、連線到您的 Vault 伺服器以及使用 {vault} 字首格式化屬性所需的具體配置。

啟用 Vault Profile

為您的 Spring Cloud Config Server 啟用 Vault profile

spring:
  profiles:
    active: vault

Vault 配置

使用必要的身份驗證詳細資訊設定與您的 Vault 伺服器的連線

spring:
  cloud:
    config:
      server:
        vault:
          host: vault.example.com
          port: 8200
          scheme: https
          backend: secret
          defaultKey: application
          kvVersion: 2
          authentication: TOKEN
          token: ${VAULT_TOKEN}
          skipSslValidation: true

這些設定指定了 Vault 伺服器地址、身份驗證方法以及訪問 Vault 所需的令牌。

屬性格式化

使用 {vault} 字首定義屬性，以指定從 Vault 檢索秘密的路徑和鍵

some:
  sensitive:
    value: '{vault}:path/to/secret#key'

此格式直接對映到秘密在 Vault 中儲存的位置（path/to/secret）以及要檢索的特定秘密鍵（key）。

錯誤處理

如果 Config Server 在解密過程中遇到任何問題，例如路徑不正確、訪問問題或缺少鍵，受影響的屬性將以 invalid. 為字首，其值將設定為 <n/a>。這種方法類似於處理以 {cipher} 為字首的屬性，但它專門針對與 Vault 的整合進行了定製，在解密失敗時提供清晰的反饋。