Quick Start

此部分说明如何开始使用 Vault 和 Spring Cloud Vault。

This section explains how to get you started with Vault and Spring Cloud Vault.

Prerequisites

若要开始使用 Vault 和本指南，你需要一个提供下列内容的类似于 NIX 的操作系统：

To get started with Vault and this guide you need a *NIX-like operating systems that provides:

wget, openssl and unzip
at least Java 8 and a properly configured JAVA_HOME environment variable

本指南从 Spring Cloud Vault 的角度解释了 Vault 设置以进行集成测试。你可以在 Vault 项目网站上找到入门指南：[role="bare"][role="bare"]https://learn.hashicorp.com/vault

This guide explains Vault setup from a Spring Cloud Vault perspective for integration testing. You can find a getting started guide directly on the Vault project site: [role="bare"]https://learn.hashicorp.com/vault

安装 Vault

Install Vault

$ wget https://releases.hashicorp.com/vault/${vault_version}/vault_${vault_version}_${platform}.zip
$ unzip vault_${vault_version}_${platform}.zip

通过下载并运行 install_vault.sh 可以实现这些步骤。

These steps can be achieved by downloading and running install_vault.sh.

Create SSL certificates for Vault

接下来，你需要生成一组证书：

Next, you’re required to generate a set of certificates:

Root CA
Vault Certificate (decrypted key work/ca/private/localhost.decrypted.key.pem and certificate work/ca/certs/localhost.cert.pem)

务必将根证书导入符合 Java 的信任库。

Make sure to import the Root Certificate into a Java-compliant truststore.

最简单的实现方法是使用 OpenSSL。

The easiest way to achieve this is by using OpenSSL.

create_certificates.sh 在 work/ca 和 JKS 信任库 work/keystore.jks 中创建证书。如果要使用本快速入门指南运行 Spring Cloud Vault，则需要将信任库 spring.cloud.vault.ssl.trust-store 属性配置为 file:work/keystore.jks。

create_certificates.sh creates certificates in work/ca and a JKS truststore work/keystore.jks. If you want to run Spring Cloud Vault using this quickstart guide you need to configure the truststore the spring.cloud.vault.ssl.trust-store property to file:work/keystore.jks.

Start Vault server

接下来，创建配置文件，如下所示：

Next create a config file along the lines of:

backend "inmem" {
}

listener "tcp" {
  address = "0.0.0.0:8200"
  tls_cert_file = "work/ca/certs/localhost.cert.pem"
  tls_key_file = "work/ca/private/localhost.decrypted.key.pem"
}

disable_mlock = true

可以在 vault.conf 找到一个示例配置文件。

You can find an example config file at vault.conf.

$ vault server -config=vault.conf

Vault 开始监听使用 inmem 存储和 https 的 0.0.0.0:8200。Vault 在启动时处于密封状态，并且未初始化。

Vault is started listening on 0.0.0.0:8200 using the inmem storage and https. Vault is sealed and not initialized when starting up.

如果您想运行测试，请让 Vault 保持未初始化状态。测试将初始化 Vault 并创建一个根令牌 00000000-0000-0000-0000-000000000000。

If you want to run tests, leave Vault uninitialized. The tests will initialize Vault and create a root token 00000000-0000-0000-0000-000000000000.

如果你想在应用程序中使用 Vault 或者试用它，则需要先初始化它。

If you want to use Vault for your application or give it a try then you need to initialize it first.

$ export VAULT_ADDR="https://localhost:8200"
$ export VAULT_SKIP_VERIFY=true # Don't do this for production
$ vault operator init

您应看到类似内容：

You should see something like:

Key 1: 7149c6a2e16b8833f6eb1e76df03e47f6113a3288b3093faf5033d44f0e70fe701
Key 2: 901c534c7988c18c20435a85213c683bdcf0efcd82e38e2893779f152978c18c02
Key 3: 03ff3948575b1165a20c20ee7c3e6edf04f4cdbe0e82dbff5be49c63f98bc03a03
Key 4: 216ae5cc3ddaf93ceb8e1d15bb9fc3176653f5b738f5f3d1ee00cd7dccbe926e04
Key 5: b2898fc8130929d569c1677ee69dc5f3be57d7c4b494a6062693ce0b1c4d93d805
Initial Root Token: 19aefa97-cccc-bbbb-aaaa-225940e63d76

Vault initialized with 5 keys and a key threshold of 3. Please
securely distribute the above keys. When the Vault is re-sealed,
restarted, or stopped, you must provide at least 3 of these keys
to unseal it again.

Vault does not store the master key. Without at least 3 keys,
your Vault will remain permanently sealed.

Vault 将初始化并返回一组 unsealing 密钥和根令牌。选择 3 个密钥和 unseal Vault。将 Vault 令牌存储在 VAULT_TOKEN 环境变量中。

Vault will initialize and return a set of unsealing keys and the root token. Pick 3 keys and unseal Vault. Store the Vault token in the VAULT_TOKEN environment variable.

$ vault operator unseal (Key 1)
$ vault operator unseal (Key 2)
$ vault operator unseal (Key 3)
$ export VAULT_TOKEN=(Root token)
# Required to run Spring Cloud Vault tests after manual initialization
$ vault token create -id="00000000-0000-0000-0000-000000000000" -policy="root"

Spring Cloud Vault 访问不同的资源。默认情况下，启用秘密后端，它通过 JSON 端点访问秘密配置设置。

Spring Cloud Vault accesses different resources. By default, the secret backend is enabled which accesses secret config settings via JSON endpoints.

HTTP 服务具有以下形式的资源：

The HTTP service has resources in the form:

/secret/{application}/{profile}
/secret/{application}
/secret/{defaultContext}/{profile}
/secret/{defaultContext}

其中“应用程序”注入为 SpringApplication 中的 spring.application.name（即在常规 Spring Boot 应用程序中通常为“应用程序”），"profile" 是活动配置文件（或以逗号分隔的属性列表）。从 Vault 检索的属性将“原样”使用，而不进一步添加属性名称的前缀。

where the "application" is injected as the spring.application.name in the SpringApplication (i.e. what is normally "application" in a regular Spring Boot app), "profile" is an active profile (or comma-separated list of properties). Properties retrieved from Vault will be used "as-is" without further prefixing of the property names.

Client Side Usage

要在应用程序中使用这些功能，只需将其构建为依赖于 spring-cloud-vault-config 的 Spring Boot 应用程序（例如，请参见测试用例）。示例 Maven 配置：

To use these features in an application, just build it as a Spring Boot application that depends on spring-cloud-vault-config (e.g. see the test cases). Example Maven configuration:

pom.xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>${springBootVersion}</version>
    <relativePath /> <!-- lookup parent from repository -->
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-vault-config</artifactId>
        <version>{project-version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

<!-- repositories also needed for snapshots and milestones -->

然后，您可以创建一个标准 Spring Boot 应用程序，例如这个简单的 HTTP 服务器：

Then you can create a standard Spring Boot application, like this simple HTTP server:

@SpringBootApplication
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

当其运行时，如果默认本地 Vault 服务器在端口 8200 上运行，它将从该服务器选取外部配置。若要修改启动行为，可以使用 application.properties 更改 Vault 服务器的位置，例如

When it runs it will pick up the external configuration from the default local Vault server on port 8200 if it is running. To modify the startup behavior you can change the location of the Vault server using application.properties, for example

application.yml

spring.cloud.vault:
    host: localhost
    port: 8200
    scheme: https
    uri: https://localhost:8200
    connection-timeout: 5000
    read-timeout: 15000
spring.config.import: vault://

host sets the hostname of the Vault host. The host name will be used for SSL certificate validation
port sets the Vault port
scheme setting the scheme to http will use plain HTTP. Supported schemes are http and https.
uri configure the Vault endpoint with an URI. Takes precedence over host/port/scheme configuration
connection-timeout sets the connection timeout in milliseconds
read-timeout sets the read timeout in milliseconds
spring.config.import mounts Vault as PropertySource using all enabled secret backends (key-value enabled by default)

启用进一步的集成需要额外的依赖项和配置。根据您设置 Vault 的方式，您可能需要额外的配置，例如 SSL 和 authentication。

Enabling further integrations requires additional dependencies and configuration. Depending on how you have set up Vault you might need additional configuration like SSL and authentication.

如果应用程序导入 spring-boot-starter-actuator 项目，Vault 服务器的状态将通过 /health 端点获得。

If the application imports the spring-boot-starter-actuator project, the status of the vault server will be available via the /health endpoint.

Vault 健康指示器可以通过属性 management.health.vault.enabled 启用或禁用（默认为 true）。

The vault health indicator can be enabled or disabled through the property management.health.vault.enabled (default to true).

在 Spring Cloud Vault 3.0 和 Spring Boot 2.4 中，属性源的引导上下文初始化 (bootstrap.yml，bootstrap.properties) 已弃用。相反，Spring Cloud Vault 偏向于 Spring Boot 的配置数据 API，该 API 允许从 Vault 导入配置。使用 Spring Boot 配置数据方法时，您需要设置 spring.config.import 属性才能绑定到 Vault。您可以在 Config Data Locations section 中了解有关它的更多信息。您可以通过设置配置属性 spring.cloud.bootstrap.enabled=true 或包括依赖项 org.springframework.cloud:spring-cloud-starter-bootstrap 来启用引导上下文。

With Spring Cloud Vault 3.0 and Spring Boot 2.4, the bootstrap context initialization (bootstrap.yml, bootstrap.properties) of property sources was deprecated. Instead, Spring Cloud Vault favors Spring Boot’s Config Data API which allows importing configuration from Vault. With Spring Boot Config Data approach, you need to set the spring.config.import property in order to bind to Vault. You can read more about it in the Config Data Locations section. You can enable the bootstrap context either by setting the configuration property spring.cloud.bootstrap.enabled=true or by including the dependency org.springframework.cloud:spring-cloud-starter-bootstrap.

Authentication

Vault 需要一个 authentication mechanism 到 authorize client requests。

Vault requires an authentication mechanism to authorize client requests.

Spring Cloud Vault 支持多个 authentication mechanisms来使用 Vault 对应用程序进行身份验证。

Spring Cloud Vault supports multiple authentication mechanisms to authenticate applications with Vault.

要快速启动，请使用 Vault initialization 打印的根令牌。

For a quickstart, use the root token printed by the Vault initialization.

application.yml

spring.cloud.vault:
    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
spring.config.import: vault://

认真考虑您的安全需求。如果想快速启动 Vault，静态令牌身份验证很好，但静态令牌没有任何进一步的保护。任何意外披露给未授权方都允许使用关联的令牌角色使用 Vault。

Consider carefully your security requirements. Static token authentication is fine if you want quickly get started with Vault, but a static token is not protected any further. Any disclosure to unintended parties allows Vault use with the associated token roles.