用法¶
本文档描述了 Castellan 的一些常见用法模式。将此软件包合并到您的应用程序中时，应注意考虑您希望封装的密钥管理器行为以及您的应用程序将运行的 OpenStack 部署。
身份验证¶
使用 Castellan 的一个基本概念是凭证上下文对象。Castellan 支持以下凭证进行身份验证
令牌
密码
Keystone Token
Keystone Password
为了使用这些凭证，必须提供有效的配置参数。
# token credential
# token variable not required, token can be obtained from context
[key_manager]
auth_type = 'token'
token = '5b4de0bb77064f289f7cc58e33bea8c7'
# password credential
[key_manager]
auth_type = 'password'
username = 'admin'
password = 'passw0rd1'
# keystone token credential
[key_manager]
auth_url = 'http://192.169.5.254:5000'
auth_type = 'keystone_token'
token = '5b4de0bb77064f289f7cc58e33bea8c7'
project_id = 'a1e19934af81420d980a5d02b4afe9fb'
# keystone password credential
[key_manager]
auth_url = 'http://192.169.5.254:5000'
auth_type = 'keystone_password'
username = 'admin'
password = 'passw0rd1'
project_id = '1099302ec608486f9879ba2466c60720'
user_domain_name = 'default'
注意
使用 keystoneauth1.identity Token 和 Password 身份验证插件实现 Keystone Token 和 Password 身份验证。可以为 keystone 凭证选项设置各种不同的变量。
必须将配置传递给凭证工厂，该工厂将生成适当的上下文。
from castellan.common import utils
CONF = cfg.CONF
CONF(default_config_files=['~/castellan.conf'])
context = utils.credential_factory(conf=CONF)
现在您可以传递上下文并将其用于身份验证。
注意
对于 token 存在一个特殊情况。由于用户可能不想将 token 存储在配置中，因此用户可以传递包含 ‘auth_token’ 的上下文对象以及将 ‘token’ 作为身份验证类型的配置文件。
也可以使用 oslo 上下文对象进行身份验证，它通常从 oslo.context.RequestContext 继承。此对象表示包含在当前请求中的信息，通常在 WSGI 管道中填充。Castellan 将使用此对象中的信息与正在抽象的特定密钥管理器进行交互。
示例。从 Keystone Client 创建 RequestContext
from keystoneauth1 import identity
from keystoneauth1 import session
from oslo_context import context
username = 'admin'
password = 'openstack'
project_name = 'admin'
auth_url = 'https:///identity/v3'
auth = identity.Password(auth_url=auth_url,
username=username,
password=password,
project_name=project_name,
default_domain_id='default')
sess = session.Session()
ctxt = context.RequestContext(auth_token=auth.get_token(sess),
project_id=auth.get_project_id(sess))
然后可以将 ctxt 传递到任何 key_manager api 调用。
基本用法¶
Castellan 的工作原理是提供一个基于您的配置的抽象密钥管理器。 这样，可以通过单个接口支持多种不同的管理服务。
除了密钥管理器之外，Castellan 还提供各种类型秘密的基元（例如，非对称密钥、简单的密码短语和证书）。这些基元与密钥管理器结合使用，以创建、存储、检索和销毁管理的秘密。
示例。创建和存储密钥。
import myapp
from castellan.common.objects import passphrase
from castellan import key_manager
key = passphrase.Passphrase('super_secret_password')
manager = key_manager.API()
stored_key_id = manager.store(myapp.context(), key)
首先，我们想创建一个要管理的密钥。我们创建一个简单的密码短语密钥，然后实例化密钥管理器，最后将其存储到管理器服务。我们记录密钥标识符以供后续使用。
示例。检索密钥并检查内容。
import myapp
from castellan import key_manager
manager = key_manager.API()
key = manager.get(myapp.context(), stored_key_id)
if key.get_encoded() == 'super_secret_password':
myapp.do_secret_stuff()
此示例演示了从密钥管理器服务检索存储的密钥并检查其内容。首先我们实例化密钥管理器，然后使用先前存储的标识符检索密钥，最后我们在执行受限操作之前检查密钥的有效性。
示例。删除密钥。
import myapp
from castellan import key_manager
manager = key_manager.API()
manager.delete(myapp.context(), stored_key_id)
完成密钥的工作后，现在可以将其从密钥管理器服务中删除。我们再次实例化一个密钥管理器，然后我们只需使用其标识符删除密钥。在正常情况下，此调用不会返回任何内容，但如果存在通信、标识或授权问题，可能会引发异常。
示例。秘密消费者。
import myapp
from castellan import key_manager
manager = key_manager.API()
# Listing consumers:
stored_secret = self.key_mgr.get(myapp.context(), stored_id)
consumer_list = stored_secret.consumers # consumers is a list of dicts
# Adding consumers:
consumer = {'service': 'glance',
'resource_type': 'image',
'resource_id': 'image_id'}
try:
manager.add_consumer(myapp.context(), stored_id, consumer)
except NotImplementedError:
pass # backends like Vault don't support adding/removing consumers
# Remove the consumer before calling secret delete without the force flag:
try:
manager.remove_consumer(myapp.context(), stored_id, consumer)
except NotImplementedError:
pass
manager.delete(myapp.context(), stored_key_id)
# Alternatively, force delete a secret
manager.delete(myapp.context(), stored_key_id, force=True)
创建秘密后，我们可以向其添加消费者。没有使用 force 标志，则无法删除带有消费者的秘密。
注意
秘密消费者当前仅适用于 Barbican 后端。 https://docs.openstack.org/barbican/2025.2/api/reference/secret_consumers.html
配置 castellan¶
Castellan 包含几个控制密钥管理服务使用情况和该服务配置的选项。它还包含帮助配置默认值并为与 oslo-config-generator 应用程序一起使用的列表的功能。
通常，castellan 配置是通过将 oslo_config.cfg.ConfigOpts 对象传递到创建密钥管理器时的 castellan.key_manager.API 调用来处理的。默认情况下，当未提供 ConfigOpts 对象时，密钥管理器将使用全局 oslo_config.cfg.CONF 对象。
示例。使用全局 CONF 对象进行配置。
from castellan import key_manager
manager = key_manager.API()
示例。使用预先确定的配置对象。
from oslo_config import cfg
from castellan import key_manager
conf = cfg.ConfigOpts()
manager = key_manager.API(configuration=conf)
控制默认选项¶
要更改 castellan 和其使用的密钥管理服务的默认行为，castellan.options 模块提供了 set_defaults 函数。此函数可以在运行时用于更改库或密钥管理服务提供商的行为。
示例。更改 barbican 端点。
from oslo_config import cfg
from castellan import options
from castellan import key_manager
conf = cfg.ConfigOpts()
options.set_defaults(conf, barbican_endpoint='http://192.168.0.1:9311/')
manager = key_manager.API(conf)
示例。在使用全局配置时更改密钥管理器提供商。
from oslo_config import cfg
from castellan import options
from castellan import key_manager
options.set_defaults(cfg.CONF, api_class='some.other.KeyManager')
manager = key_manager.API()
Castellan 中的日志记录¶
Castellan 使用 oslo_log 进行日志记录。如果您的应用程序配置了 oslo_log 模块，将生成日志信息。如果您的应用程序不使用 oslo_log，则可以使用 castellan.options 模块中的 enable_logging 启用默认日志记录。
示例。启用默认日志记录。
from castellan import options
from castellan import key_manager
options.enable_logging()
manager = key_manager.API()
生成示例配置文件¶
Castellan 包含一个 tox 配置，用于创建示例配置文件。此文件将仅包含 castellan 将使用的值。要生成此文件，请从 castellan 项目目录的根目录运行以下命令
$ tox -e genconfig
解析配置文件¶
默认情况下，Castellan 不会解析配置文件。当您创建文件并占用它们时，仍然需要操作 oslo_config.cfg 对象，然后将其传递给 castellan.key_manager.API 对象。您可以创建配置文件的位置列表。如果指定了多个配置文件，则将使用最近解析的文件的变量并覆盖任何先前的变量。在下面的示例中，/etc/castellan 目录中的配置文件将覆盖在用户主目录中找到的文件中的值。如果在指定的位置之一中未找到文件，则将发生配置文件未找到错误。
示例。解析配置文件。
from oslo_config import cfg
from castellan import key_manager
conf=cfg.CONF
config_files = ['~/castellan.conf', '/etc/castellan/castellan.conf']
conf(default_config_files=config_files)
manager = key_manager.API(configuration=conf)
有两种方法可以从配置文件中解析 Castellan 值
可以将值放在单独的文件中。
您可以将值包含在您已经使用的配置文件中。
为了查看 Castellan 使用的所有默认值，请通过参考上面的部分生成示例配置。
将 castellan 添加到配置文件¶
OpenStack 项目的一个常见任务是创建项目配置文件。Castellan 在 castellan.options 模块中提供了一个 list_opts 函数，以帮助在使用 oslo-config-generator 时生成这些文件。可以将此函数在项目的 setup.cfg 文件中指定，以告知 oslo 配置选项。请注意，这将使用 castellan 包提供的默认值。
示例。将 castellan 添加到 oslo.config 入口点。
[entry_points]
oslo.config.opts =
castellan.config = castellan.options:list_opts
还需要将新的命名空间添加到项目的 oslo-config-generator 配置文件，例如 etc/oslo-config-generator/myproject.conf
[DEFAULT]
output_file = etc/myproject/myproject.conf
namespace = castellan.config
有关 oslo 配置生成器的更多信息，请参见 https://docs.openstack.org/oslo.config/2025.2/cli/generator.html
