本文为 SPIRE 官方文档 plugin_server_datastore_sql 的中文译本,以英文原文为准。 🔗 穿越源码分析:Server 详解 · DataStore · 高可用

Server 插件:DataStore "sql"

sql 插件为 SPIRE server 实现了基于 SQL 的数据存储,支持 SQLite、PostgreSQL 或 MySQL 数据库。

配置项	说明
database_type	数据库类型
connection_string	连接字符串
ro_connection_string	只读连接
root_ca_path	根 CA 证书包(Root CA bundle)路径(仅 MySQL)
client_cert_path	客户端证书路径(仅 MySQL)
client_key_path	客户端证书对应私钥的路径(仅 MySQL)
max_open_conns	打开的数据库连接的最大数量(默认:100)
max_idle_conns	连接池中空闲连接的最大数量(默认:100)
conn_max_lifetime	连接可被复用的最长时间(默认:无限制)
disable_migration	设为 true 可关闭自动迁移(auto-migration)功能。使用该标志可以更精细地控制数据存储迁移发生的时机,并协调与某个 SPIRE Server 集群共享的数据存储的迁移。仅适用于 SPIRE 代码版本 0.9.0 及以后创建的数据库。

关于 max_open_conns、max_idle_conns 和 conn_max_lifetime 的更多信息,请参阅 Go database/sql 包的文档。

注意: SQL 插件对每个连接的最大空闲时间(ConnMaxIdleTime)使用了 30 秒的内部默认值。该设置无法通过插件配置进行修改。

数据库配置

database_type = "sqlite3"

我们使用 mattn/go-sqlite3 驱动。它接受一个 SQLite 数据库文件名或 URI 作为连接字符串,并支持用于设置 pragma 及类似选项的驱动专有扩展。

将数据库保存到文件:

connection_string = "DATABASE_FILE.db"

将数据库保存在内存中:

connection_string = "file:memdb?mode=memory&cache=shared"

如果你从源码编译 SPIRE,请参阅 SQLite 与 CGO 了解更多信息。

示例配置

    DataStore "sql" {
        plugin_data {
            database_type = "sqlite3"
            connection_string = "./.data/datastore.sqlite3"
        }
    }

database_type = "postgres"

PostgreSQL 数据库连接的 connection_string 由若干个以空格分隔的配置选项组成。

例如:

connection_string = "dbname=postgres user=postgres password=password host=localhost sslmode=disable"

更多 connection_string 选项请查阅 lib/pq 驱动文档。

支持的 PostgreSQL 版本

我们使用 lib/pq 驱动,因此目前支持该库所支持的 PostgreSQL 版本。这通常意味着当前处于维护状态的受支持版本集合。我们会针对多个版本运行集成测试。更老的版本可能仍然可用,但未经测试。

配置选项

• dbname - 要连接的数据库名称
• user - 登录所用的用户
• password - 用户的密码
• host - 要连接的主机。以 / 开头的值表示 unix 域套接字。(默认为 localhost)
• port - 要绑定的端口。(默认为 5432)
• sslmode - 是否使用 SSL(默认为 require,这并非 libpq 的默认值)
• fallback_application_name - 当未提供 application_name 时回退使用的名称。
• connect_timeout - 建立连接的最长等待时间(秒)。为 0 或未指定表示无限期等待。
• sslcert - 证书文件位置。文件必须包含 PEM 编码的数据。
• sslkey - 私钥文件位置。文件必须包含 PEM 编码的数据。
• sslrootcert - 根证书文件位置。文件必须包含 PEM 编码的数据。

有效的 sslmode 配置

• disable - 不使用 SSL
• require - 始终使用 SSL(跳过验证)
• verify-ca - 始终使用 SSL(验证服务器出示的证书由受信任的 CA 签发)
• verify-full - 始终使用 SSL(验证服务器出示的证书由受信任的 CA 签发,且服务器主机名与证书中的主机名匹配)

示例配置

    DataStore "sql" {
        plugin_data {
            database_type = "postgres"
            connection_string = "dbname=spire_development user=spire host=127.0.0.1 sslmode=disable"
        }
    }

Google Cloud SQL Proxy 支持

PostgreSQL 数据存储支持通过 Cloud SQL Proxy 连接 Google Cloud SQL 实例。当使用 Cloud SQL 连接字符串时,该支持会自动启用。插件内置了 Cloud SQL Proxy 的 PostgreSQL dialer,可透明地处理与 Cloud SQL PostgreSQL 实例的安全连接。

连接 Cloud SQL PostgreSQL 实例时,请使用采用 Cloud SQL 实例连接名格式的连接字符串。Cloud SQL Proxy 会自动管理认证与加密。

database_type = "mysql"

MySQL 数据库连接的 connection_string 由若干个配置选项组成(可选部分以方括号标注):

username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

例如:

connection_string = "username:password@tcp(localhost:3306)/dbname?parseTime=true"

更多 connection_string 选项请查阅 MySQL 驱动仓库。

支持的 MySQL 版本

我们支持当前所有处于维护状态的 MySQL 版本,并针对 LTS 版本运行集成测试。更老的 MySQL 版本可能仍然可用,但未经测试。

配置选项

• dbname - 要连接的数据库名称
• username - 登录所用的用户
• password - 用户的密码
• address - 要连接的主机。以 / 开头的值表示 unix 域套接字。(默认为 localhost)

如果你需要使用自定义的根 CA(Root CA),只需在插件配置中指定 root_ca_path。同样,如果需要使用客户端证书,请指定 client_key_path 和 client_cert_path。其他选项可通过 connection_string 中的 tls 参数进行配置。

示例配置

    DataStore "sql" {
        plugin_data {
            database_type = "mysql"
            connection_string = "spire:@tcp(127.0.0.1)/spire_development?parseTime=true"
        }
    }

Google Cloud SQL Proxy 支持

MySQL 数据存储支持通过 Cloud SQL Proxy 连接 Google Cloud SQL 实例。当使用 Cloud SQL 连接字符串时,该支持会自动启用。插件内置了 Cloud SQL Proxy 的 MySQL dialer,可透明地处理与 Cloud SQL MySQL 实例的安全连接。

连接 Cloud SQL MySQL 实例时,请使用采用 Cloud SQL 实例连接名格式的连接字符串。Cloud SQL Proxy 会自动管理认证与加密。

IAM 认证

身份与访问管理(Identity and Access Management,IAM)认证可实现对云服务上托管数据库的安全认证。与传统方式不同,它使用认证令牌(authentication token)而非密码。使用 IAM 认证时,必须从连接字符串中去除密码。

database_type 配置允许指定支持 IAM 认证的数据库类型。其配置始终遵循如下结构:

    database_type "dbtype-with-iam-support" {
        setting_1 = "value-1"
        setting_2 = "value-2"
        ...
    }

注意:请将 dbtype-with-iam-support 替换为具体支持 IAM 认证的数据库类型。

支持 IAM 认证的数据库类型包括:

"aws_postgres"

用于 AWS RDS 上使用 IAM 认证的 PostgreSQL 数据库。region 设置为必填项,用于指定 AWS 服务区域。

当设置为 aws_postgres 时,database_type 设置下的完整配置选项列表如下:

配置项	说明	是否必填	默认值
access_key_id	AWS 访问密钥 ID。	仅当未设置 AWS_ACCESS_KEY_ID 环境变量时必填。	AWS_ACCESS_KEY_ID 环境变量的值。
secret_access_key	AWS 私密访问密钥。	仅当未设置 AWS_SECRET_ACCESS_KEY 环境变量时必填。	AWS_SECRET_ACCESS_KEY 环境变量的值。
region	数据库所在的 AWS 区域。	是。

postgres 数据库类型的各项设置在此同样适用。

示例配置

    DataStore "sql" {
        plugin_data {
            database_type "aws_postgres" {
                region = "us-east-2"
            }
            connection_string = "dbname=spire user=test_user host=spire-test.example.us-east-2.rds.amazonaws.com port=5432 sslmode=require"
        }
    }

"aws_mysql"

用于 AWS RDS 上使用 IAM 认证的 MySQL 数据库。region 设置为必填项。

当设置为 aws_mysql 时,database_type 设置下的完整配置选项列表如下:

配置项	说明	是否必填	默认值
access_key_id	AWS 访问密钥 ID。	仅当未设置 AWS_ACCESS_KEY_ID 环境变量时必填。	AWS_ACCESS_KEY_ID 环境变量的值。
secret_access_key	AWS 私密访问密钥。	仅当未设置 AWS_SECRET_ACCESS_KEY 环境变量时必填。	AWS_SECRET_ACCESS_KEY 环境变量的值。
region	数据库所在的 AWS 区域。	是。

mysql 数据库类型的各项设置在此同样适用。

示例配置

    DataStore "sql" {
        plugin_data {
            database_type "aws_mysql" {
                region = "us-east-2"
            }
            connection_string="test_user:@tcp(spire-test.example.us-east-2.rds.amazonaws.com:3306)/spire?parseTime=true&allowCleartextPasswords=1&tls=true"
        }
    }

只读连接(Read Only connection)

当设置了可选的 ro_connection_string 时,将使用只读连接。该字符串的格式与 connection_string 相同。此选项不适用于 SQLite3。

SQLite 与 CGO

SQLite 支持依赖 CGO。对于下载 SPIRE 或使用官方 SPIRE 容器镜像的用户来说,这不是问题。但如果你从源码构建 SPIRE,请注意:在不启用 CGO(例如 CGO_ENABLED=0)的情况下编译 SPIRE 将会禁用 SQLite 支持。