为 TechDocs 生成的文件使用云存储

在技术文档架构在 "基本 "和 "推荐 "设置中，您都可以添加云存储提供商，如 Google GCS、亚马逊 AWS S3 等。techdocs-backend在 "基本 "设置中，拥有其中一个云存储是前提条件。请在 TechDocs 架构文档页面阅读更多内容。

您可以在本页了解如何启用它们。

使用 TechDocs 配置 Google GCS Bucket

按照谷歌云官方文档以获取关于以下涉及 GCP 的步骤的最新说明。

1. 在app-config.yaml中设置techdocs.publisher.type配置*

设置techdocs.publisher.type至'googleGcs'.

techdocs:
  publisher:
    type: 'googleGcs'

2.创建全球监控系统水桶

为 TechDocs 站点创建一个专用的 Google Cloud Storage 存储桶。 techdocs-backend 将向此存储桶发布文档。 TechDocs 将从这里获取文件，以便在 Backstage 中提供文档。请注意，存储桶的名称是全局唯一的。

设置配置techdocs.publisher.googleGcs.bucketName在你的app-config.yaml为您刚刚创建的水桶的名称。设置techdocs.publisher.googleGcs.projectId为包含水桶的 Google 云项目的 ID。

techdocs:
  publisher:
    type: 'googleGcs'
    googleGcs:
      bucketName: 'name-of-techdocs-storage-bucket'
      projectId: 'name-of-project'

3a.(建议)使用环境变量进行身份验证

GCS Node.js 客户端将自动使用环境变量GOOGLE_APPLICATION_CREDENTIALS可能已在 Compute Engine、Google Kubernetes Engine 等中设置。详情请阅读 https://cloud.google.com/docs/authentication/production。

3b.使用 app-config.yaml 进行身份验证

如果您不喜欢 (3a)，并希望使用服务帐户，可以按照以下步骤操作。

创建新的服务账户和与之关联的密钥。在服务账户的角色中，使用 "存储对象管理员"。

如果要创建自定义角色，请确保同时包含get和create对象 "和 "桶 "的权限。参见 https://cloud.google.com/storage/docs/access-control/iam-permissions

一个服务账户可以有多个密钥。打开新创建的账户页面(在 IAM 和管理控制台中)，创建一个新密钥。密钥使用 JSON 格式。

A<GCP-PROJECT-ID-random-uid>.json这是 TechDocs 调用 API 时使用的Secret密钥。请在Backstage服务器和/或本地开发服务器中提供该密钥，并在应用程序配置中进行设置techdocs.publisher.googleGcs.credentials.

techdocs:
  publisher:
    type: 'googleGcs'
    googleGcs:
      bucketName: 'name-of-techdocs-storage-bucket'
      credentials:
        $file: '/path/to/google_application_credentials.json'

注意：如果您发现很难将文件google_application_credentials.json然后使用

techdocs:
  publisher:
    type: 'googleGcs'
    googleGcs:
      bucketName: 'name-of-techdocs-storage-bucket'
      credentials: ${GOOGLE_APPLICATION_CREDENTIALS}

假设您使用的服务账户是在与水桶相同的项目中创建的，则无需设置projectId如果没有，则必须使用默认凭据覆盖它：

techdocs:
  publisher:
    type: 'googleGcs'
    googleGcs:
      bucketName: 'name-of-techdocs-storage-bucket'
      credentials: ${GOOGLE_APPLICATION_CREDENTIALS}
      projectId: 'name-of-project'

4.就是这样！

您的 Backstage 应用程序现在可以使用 Google Cloud Storage for TechDocs 来存储和读取静态生成的文档文件。

使用 TechDocs 配置 AWS S3 存储桶

1. 在app-config.yaml中设置techdocs.publisher.type配置*

设置techdocs.publisher.type至'awsS3'.

techdocs:
  publisher:
    type: 'awsS3'

2. 创建 S3 存储桶

创建一个专用的 AWS S3 存储桶，用于存储 TechDocs 网站。参考官方文件.Terraform 示例.

TechDocs 会将文档发布到这个文件桶，并从这里获取文件，为 Backstage 中的文档提供服务。请注意，文件桶名称是全局唯一的。

设置配置techdocs.publisher.awsS3.bucketName在你的app-config.yaml改为刚刚创建的水桶名称。

techdocs:
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'name-of-techdocs-storage-bucket'

创建最低限度的 AWS IAM 策略来管理 TechDocs。

至写将 TechDocs 放入 S3 存储桶，IAM 策略至少需要拥有该存储桶的权限：

s3:ListBucket 用于检索邮筒元数据 * s3:PutObject 用于将文件上传到邮筒 * s3:DeleteObject 和 s3:DeleteObjectVersion 用于在重新发布时删除过时内容

至阅读IAM 策略至少需要拥有 S3 存储桶中 TechDocs 的权限：

s3:ListBucket - 提取文件桶元数据 * s3:GetObject - 从文件桶中提取文件

注意：如果需要从旧式路径 > 格式(包括大小写敏感的实体元数据)迁移文档对象，则需要添加一些 > 额外的权限才能执行迁移，包括： > > * s3:PutBucketAcl(用于复制文件，> 更多信息请点击此处 > * s3:DeleteObject和s3:DeleteObjectVersion(用于删除迁移的文件，> 更多信息请点击此处 > > ...并且需要确保权限适用于文件桶本身，以及 > 文件桶下的所有资源。请参阅下面的策略示例。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TechDocsWithMigration",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObjectVersion",
        "s3:ListBucket",
        "s3:DeleteObject",
        "s3:PutObjectAcl"
      ],
      "Resource": ["arn:aws:s3:::your-bucket", "arn:aws:s3:::your-bucket/*"]
    }
  ]
}

4a.(建议)使用环境变量以 AWS 的方式设置身份验证

您应遵循AWS 身份验证安全最佳实践指南.

TechDocs 需要读取 S3 存储桶的文件和元数据的权限。因此，如果要为某个用户创建策略，就必须确保授予该用户对 ListBucket、GetObject 和 PutObject 的访问权限。

如果环境变量

aws_access_key_id * aws_secret_access_key * `aws_region

已设置并可用于访问在步骤 2 中创建的水桶，它们将被 AWS SDK V3 Node.js 客户端用于身份验证。关于在 Node.js 中从环境变量加载证书，请参阅官方文档.

如果缺少环境变量，AWS SDK 会尝试读取~/.aws/credentials文件获取证书。请参阅官方文件。

如果要将 Backstage 部署到 Amazon EC2、Amazon ECS 或 Amazon EKS，则无需单独获取访问密钥。通过定义可访问存储桶的适当 IAM 角色，可在环境中自动提供访问密钥。请阅读更多内容。使用 IAM 角色的 AWS 官方文档.

4b.使用 app-config.yaml 进行身份验证

可以通过以下方式向 AWS SDK 提供 AWS 认证和区域app-config.yaml如果存在以下配置，它们将取代现有的AWS_*环境变量和~/.aws/credentials配置文件。

techdocs:
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'name-of-techdocs-storage-bucket'
      accountId: '123456789012'
      region: ${AWS_REGION}
aws:
  accounts:
    - accountId: '123456789012'
      accessKeyId: ${AWS_ACCESS_KEY_ID}
      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}

参考获得证书的 AWS 官方文件.

4c. 使用假定角色进行身份验证拥有多个 AWS 账户的用户可能希望为不同 AWS 账户中的 S3 存储使用一个角色。roleArn如下图所示，你可以指示 TechDocs 发布者在访问 S3 之前承担一个角色。

techdocs:
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'name-of-techdocs-storage-bucket'
      region: ${AWS_REGION}
      credentials:
        roleArn: arn:aws:iam::123456789012:role/my-backstage-role

注：假设一个角色需要已在以下位置配置了主要凭据AWS.config.credentials.了解更多在 AWS 中担任角色.

5.就是这样！

现在，您的 Backstage 应用程序已准备好使用 AWS S3 for TechDocs 来存储和读取静态生成的文档文件。当您启动应用程序后端时，应该可以看到techdocs info Successfully connected to the AWS S3 bucket在日志中。

使用 TechDocs 配置 Azure Blob 存储容器

按照Azure Blob Storage 官方文档了解有关 Azure Blob Storage 以下步骤的最新说明。

1. 在app-config.yaml中设置techdocs.publisher.type配置*

设置techdocs.publisher.type至'azureBlobStorage'.

techdocs:
  publisher:
    type: 'azureBlobStorage'

2.创建 Azure Blob 存储容器

为 TechDocs 网站创建专用容器。参考官方文件.

TechDocs 将向此容器发布文档，并从这里获取文件，为 Backstage 中的文档提供服务。请注意，容器名称是全局唯一的。

设置配置techdocs.publisher.azureBlobStorage.containerName在你的app-config.yaml改为刚刚创建的容器的名称。

techdocs:
  publisher:
    type: 'azureBlobStorage'
    azureBlobStorage:
      containerName: 'name-of-techdocs-storage-container'

3a.(建议)使用环境变量进行身份验证

如果您不喜欢 (3a)，并希望使用服务账户，可以设置配置techdocs.publisher.azureBlobStorage.credentials.accountName在你的app-config.yaml到您的账户名。

存储 blob 客户端会自动使用环境变量AZURE_TENANT_ID,AZURE_CLIENT_ID,AZURE_CLIENT_SECRET来验证 Azure Blob Storage 的身份。创建可检索变量的服务的步骤.

https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad 了解更多详情。

techdocs:
  publisher:
    type: 'azureBlobStorage'
    azureBlobStorage:
      containerName: 'name-of-techdocs-storage-bucket'
      credentials:
        accountName: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME}

3b.使用 app-config.yaml 进行身份验证

如果您不喜欢 (3a)，并希望使用服务帐户，可以按照以下步骤操作。

要获取凭证，请访问 Azure 门户并转到 "设置 > 访问密钥"，然后获取存储账户名称和主密钥。详情请访问 https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key。

techdocs:
  publisher:
    type: 'azureBlobStorage'
    azureBlobStorage:
      containerName: 'name-of-techdocs-storage-bucket'
      credentials:
        accountName: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME}
        accountKey: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY}

在这两种情况下，用于访问容器及其下所有 TechDocs 对象的账户或凭据都应具有Storage Blog Data Owner角色，以便根据需要读取、写入和删除对象。

4.就是这样！

现在，您的 Backstage 应用程序已准备好使用 Azure Blob Storage for TechDocs 来存储和读取静态生成的文档文件。启动应用程序后端时，您应该可以看到techdocs info Successfully connected to the Azure Blob Storage container在日志中。

利用 TechDocs 配置 OpenStack Swift 容器

按照官方 OpenStack Api 文档了解有关 OpenStack 存储的以下步骤的最新说明。

1. 在app-config.yaml中设置techdocs.publisher.type配置*

设置techdocs.publisher.type至'openStackSwift'.

techdocs:
  publisher:
    type: 'openStackSwift'

2. 创建 OpenStack Swift 存储容器

为 TechDocs 网站创建专用容器。参考官方文件.

TechDocs 将向此容器发布文档，并从这里获取文件，为 Backstage 中的文档提供服务。请注意，容器名称是全局唯一的。

设置配置techdocs.publisher.openStackSwift.containerName在你的app-config.yaml改为刚刚创建的容器的名称。

techdocs:
  publisher:
    type: 'openStackSwift'
    openStackSwift:
      containerName: 'name-of-techdocs-storage-container'

3 使用 app-config.yaml 进行身份验证

在您的app-config.yaml以指向您的容器名称。

https://docs.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-unscoped-authorization-detail,authenticating-with-an-application-credential-detail#authenticating-with-an-application-credential 了解更多详情。

techdocs:
  publisher:
    type: 'openStackSwift'
    openStackSwift:
      containerName: 'name-of-techdocs-storage-bucket'
      credentials:
        id: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_ID}
        secret: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_SECRET}
      authUrl: ${OPENSTACK_SWIFT_STORAGE_AUTH_URL}
      swiftUrl: ${OPENSTACK_SWIFT_STORAGE_SWIFT_URL}

4.就是这样！

您的 Backstage 应用程序现在可以使用 OpenStack Swift Storage for TechDocs 来存储和读取静态生成的文档文件。启动应用程序后端时，您应该可以看到techdocs info Successfully connected to the OpenStack Swift Storage container在日志中。

奖金：从旧的 OpenStack Swift 配置迁移

假设我们这里使用的是旧版 OpenStack Swift 配置。

techdocs:
  publisher:
    type: 'openStackSwift'
    openStackSwift:
      containerName: 'name-of-techdocs-storage-bucket'
      credentials:
        username: ${OPENSTACK_SWIFT_STORAGE_USERNAME}
        password: ${OPENSTACK_SWIFT_STORAGE_PASSWORD}
      authUrl: ${OPENSTACK_SWIFT_STORAGE_AUTH_URL}
      keystoneAuthVersion: ${OPENSTACK_SWIFT_STORAGE_AUTH_VERSION}
      domainId: ${OPENSTACK_SWIFT_STORAGE_DOMAIN_ID}
      domainName: ${OPENSTACK_SWIFT_STORAGE_DOMAIN_NAME}
      region: ${OPENSTACK_SWIFT_STORAGE_REGION}

步骤 1：更改凭证密钥

由于新的 SDK 使用要验证 OpenStack，我们需要更改密钥credentials.username至credentials.id,credentials.password至credentials.secret并在此处使用应用程序凭据 ID 和Secret。有关凭据的更多详情，请查阅这里.

步骤 2：取出未使用的钥匙

由于新的 SDK 不使用旧的身份验证方式，因此我们不需要密钥openStackSwift.keystoneAuthVersion,openStackSwift.domainId,openStackSwift.domainName和openStackSwift.region所以你可以把它们移走。

第 3 步：添加 Swift URL

新的 SDK 需要 OpenStack Swift 连接 URL 来连接 Swift。因此，您需要添加一个名为openStackSwift.swiftUrl示例 URL 应如下所示：https://example.com:6780/swift/v1

就这样！

新配置应该是这样的！

techdocs:
  publisher:
    type: 'openStackSwift'
    openStackSwift:
      containerName: 'name-of-techdocs-storage-bucket'
      credentials:
        id: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_ID}
        secret: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_SECRET}
      authUrl: ${OPENSTACK_SWIFT_STORAGE_AUTH_URL}
      swiftUrl: ${OPENSTACK_SWIFT_STORAGE_SWIFT_URL}

使用 TechDocs 配置 Google GCS Bucket​

使用 TechDocs 配置 AWS S3 存储桶​

使用 TechDocs 配置 Azure Blob 存储容器​

利用 TechDocs 配置 OpenStack Swift 容器​

奖金：从旧的 OpenStack Swift 配置迁移​

步骤 1：更改凭证密钥​

步骤 2：取出未使用的钥匙​

第 3 步：添加 Swift URL​

就这样！​

使用 TechDocs 配置 Google GCS Bucket

使用 TechDocs 配置 AWS S3 存储桶

使用 TechDocs 配置 Azure Blob 存储容器

利用 TechDocs 配置 OpenStack Swift 容器

奖金：从旧的 OpenStack Swift 配置迁移

步骤 1：更改凭证密钥

步骤 2：取出未使用的钥匙

第 3 步：添加 Swift URL

就这样！