IBM Cloud Docs
使用持久性数据存储

使用持久性数据存储

通过使用持久化数据存储，您可以将 IBM Cloud Object Storage (COS) 桶挂载到 IBM Cloud® Code Engine 应用程序或作业。 该功能允许工作负载使用标准文件操作，通过本地文件系统访问 COS 文件桶的内容。

Code Engine 中的持久数据存储是对 Code Engine 不管理的现有数据存储的引用。 目前，IBM Cloud Object Storage 是唯一受支持的数据存储类型。 通过创建对 COS 文件桶的引用，可以将其直接挂载到应用程序或作业容器的文件系统中。

准备工作

在使用持久化数据存储之前，请确保满足以下前提条件。

  • 您必须有一个 IBM Cloud Object Storage 实例。
  • Object Storage 实例中必须有一个可用的存储桶。
  • 您必须为 Object Storage 实例创建服务凭据，并启用 HMAC 凭据。 HMAC 证书至少需要 Writer 服务访问角色才能读取和写入数据桶。 如果只需要读取访问权限，请选择“内容阅读器”服务访问角色。
  • 您必须有一个 Code Engine 项目，并且必须将其选为当前上下文。

第 1 步：使用控制台在 Code Engine 中创建 HMAC 密文

要安全访问 COS 存储桶，Code Engine 需要与 Object Storage 实例关联的 HMAC 凭据。 您可以将这些凭证存储在 Code Engine 项目中的一个秘密文件中。

按照 从控制台创建 HMAC 密钥的 步骤创建以下格式的密钥 HMAC。

根据提示提供 COS 服务证书中的相应值。

第 2 步：使用控制台创建持久数据存储

现在，在 Code Engine 中创建持久数据存储资源。 该资源可作为 COS 数据桶的引用，并将其与您创建的 HMAC 密钥相链接。

  1. 单击 Code Engine 项目页面上的项目名称。
  2. 从组件页面，单击持久数据存储。
  3. 从持久性数据存储页面，单击创建。
  4. 从创建持久性数据存储页面，完成以下步骤：
    1. 提供一个名称，例如 mysecret-hmac。
    2. 指定是选择现有的 COS 桶规格，还是手动添加。
    3. 选择一个 COS 实例或手动指定其名称。
    4. 选择水桶或手动指定其名称。
    5. 选择验证 COS 实例所需的 HMAC 访问秘密。
    6. 单击创建创建持久性数据存储。

第 3 步：使用控制台将数据存储挂载到工作负载中

创建持久化数据存储后，就可以在创建或更新应用程序或任务时将其作为卷挂载。

安装到应用程序中

  1. 导航至您的应用程序。

    • 在 Code Engine 项目页面中，单击您的项目名称。 单击应用程序，处理您的应用程序。
    • 在“应用程序”页面，单击要更新的应用程序名称，或单击“创建”创建新的应用程序。

  2. 选择“配置”选项卡。

  3. 从卷挂载选项卡，单击添加。

  4. 选择卷类型为持久数据存储。

  5. 选择所需的持久性数据存储。

  6. 如果应用程序只能通过子路径前缀访问存储桶中的对象，请指定相对存储桶子路径 （可选），例如 path/in/bucket。 当你想隔离对邮筒内特定文件夹的访问时，这很有用。 子路径必须是 COS 邮筒中的有效前缀。 从挂载的目录中只能访问该路径下的内容。

  7. 指定安装路径。 这是应用容器内可以访问卷挂载数据的目录，例如 /mnt/bucket。

  8. 选择所需的访问权限，即读写或只读。

  9. 单击添加创建卷挂载。

  10. 单击“**部署 **”保存更改并部署应用程序修订版。

更新应用程序时，应用程序会创建一个新版本，并将流量路由到该实例。

装入工作

  1. 导航至您的工作页面。

    • 在 Code Engine 项目页面中，单击您的项目名称。 单击作业，处理作业和作业运行。
    • 在“任务”页面，单击“任务”选项卡，然后单击要更新或创建新任务的任务名称。

  2. 选择“配置”选项卡。

  3. 从卷挂载选项卡，单击添加。

  4. 选择卷类型为持久数据存储。

  5. 选择所需的持久性数据存储。

  6. 如果任务运行只能访问具有该子路径前缀的存储桶中的对象，则指定相对存储桶子路径 （可选），例如 path/in/bucket。 当你想隔离对邮筒内特定文件夹的访问时，这很有用。 子路径必须是 COS 邮筒中的有效前缀。 从挂载的目录中只能访问该路径下的内容。

  7. 指定安装路径。 这是作业运行容器内可以访问卷挂载数据的目录，例如 /mnt/bucket。

  8. 选择所需的访问权限，即读写或只读。

  9. 单击添加创建卷挂载。

  10. 单击“**部署 **”保存更改并部署作业。

  11. 单击提交任务。

第 1 步：使用 CLI 在 Code Engine 中创建 HMAC 密文

要安全访问 COS 存储桶，Code Engine 需要与 Object Storage 实例关联的 HMAC 凭据。 您可以将这些凭证存储在 Code Engine 项目中的一个秘密文件中。

要创建格式为 hmac 的秘密，请使用 secret create 命令。

ibmcloud ce secret create --name my-hmac-secret --format hmac --secret-access-key-prompt --access-key-id-prompt

命令提示时，请提供 COS 服务证书中的相应值。secret create 命令提示时，提供 COS 服务凭据中的相应值。

第 2 步：使用 CLI 创建持久数据存储

现在，在 Code Engine 中创建持久数据存储资源。 该资源可作为 COS 数据桶的引用，并将其与您创建的 HMAC 密钥相链接。

ibmcloud ce persistentdatastore create --name my-cos-bucket-pds --cos-bucket-name my-cos-bucket --cos-access-secret my-hmac-secret
  • 将 my-cos-bucket-pds 替换为数据存储的唯一名称。
  • 将 my-cos-bucket 替换为 COS 桶的准确名称。
  • 将 my-hmac-secret 替换为 HMAC 密文的名称。

第 3 步：使用 CLI 将数据存储挂载到工作负载中

创建持久化数据存储后，就可以在创建或更新应用程序或作业时加载它。 使用 --mount-data-store 选项，格式为 MOUNT_PATH=PDS_NAME。

安装到应用程序中

以下命令将创建名为 myapp 的应用程序，并将 my-cos-bucket-pds 数据存储挂载到应用程序容器内的 /mnt/bucket 目录。

ibmcloud ce application create --name myapp --image icr.io/codeengine/helloworld --mount-data-store /mnt/bucket=my-cos-bucket-pds

装入工作

同样，该命令会创建一个名为 myjob 的任务，并将相同的数据存储挂载到 /mnt/bucket 目录。

ibmcloud ce job create --name myjob --image icr.io/codeengine/helloworld --mount-data-store /mnt/bucket=my-cos-bucket-pds

在数据桶内安装子路径

您还可以使用冒号（: ）在挂载定义中添加相对路径，从而挂载 COS 文件桶中的特定子路径。当你想隔离对存储桶内特定文件夹的访问时，这很有用。

例如，要将 my-cos-bucket-pds 数据存储中的 path/in/bucket 目录挂载到 /mnt/bucket：

ibmcloud ce application create --name myapp --image icr.io/codeengine/helloworld --mount-data-store /mnt/bucket=my-cos-bucket-pds:path/in/bucket

或者是为了工作：

ibmcloud ce job create --name myjob --image icr.io/codeengine/helloworld --mount-data-store /mnt/bucket=my-cos-bucket-pds:path/in/bucket

注意： path/in/bucket 必须是 COS 邮筒中的有效前缀。 从挂载的目录中只能访问该路径下的内容。

步骤 4：访问已挂载数据存储中的文件

一旦你的应用程序或作业开始运行，代码就可以与已挂载的 COS 文件桶进行交互，就像与本地目录交互一样。 支持所有标准文件系统操作。

例如，在容器内，您可以列出文件、读取内容和写入新文件：

# List files in the bucket
ls -l /mnt/bucket

# Read a file from the bucket
cat /mnt/bucket/my-document.txt

# Write a new file to the bucket
echo "Hello from Code Engine" > /mnt/bucket/new-file.txt

限制

挂载使用 s3fs，它为 S3-compatible 存储提供了一个基于 FUSE 的文件系统接口。 请注意以下限制：

  • 持久性数据存储的数量：
    • 有一项限制，即每个应用程序或作业最多允许挂载两个持久性数据存储。
  • 性能：
    • Object Storage 在第一字节到第一字节的时间上有很高的延迟，这使得它们在进行需要立即访问的操作时比本地文件系统慢。
    • 修改文件的操作（如随机写入或追加）需要在后端重写整个对象，由于没有随机写入访问，因此速度会很慢，效率也很低。
    • 元数据操作（如列出目录）的性能可能很差。
  • 一致性：
    • IBM Cloud Object Storage 为新对象提供强大的读写后一致性，但为对象的覆盖和删除提供最终一致性。 这意味着在更新或删除后，读取操作可能会暂时返回过时的数据。
    • 从挂载系统外部（如直接通过 COS API 或其他客户端）对邮筒所做的更改不会立即被检测到，可能在一段时间内都无法看到。
  • 文件系统语义
    • 不完全支持 POSIX 文件系统的标准功能。 具体来说，文件或目录没有原子重命名，也没有硬链接。
  • 并发性：
    • 挂载同一数据桶的多个客户端（如多个应用程序实例）之间不存在协调。 从不同实例同时写入同一文件可能会导致数据丢失或损坏。
  • 活动订阅：
    • 如果您为 Object Storage bucket 配置了事件订阅，请注意通过挂载执行的文件创建操作可能会生成多个更新事件。 这可能会导致 Code Engine 应用程序或作业因单个文件操作而被触发多次，从而影响下游处理或事件驱动工作流。 由于这些限制，该功能并不适用于所有工作负载。 它最适合主要读取大文件的工作负载，如深度学习或数据分析，在这些负载中可以实现良好的吞吐量。 对于需要低延迟、频繁的小规模写入或事务性文件操作的工作负载，不建议使用它。

后续步骤

现在你已经了解了如何使用持久化数据存储，可以探索更高级的主题：