支持控制台（Console）开发人员开始试用联系人

第 6 章 配置 TechDocs

配置 Red Hat Developer Hub TechDocs 插件，以在中央位置创建、查找和使用文档，并以标准化的方式使用。例如：

文档类代码方法
在 Markdown 文件中编写存储在项目存储库中的技术文档以及您的代码。
文档站点生成
使用 MkDocs 为您的在 Developer Hub 中呈现的文档创建一个功能全面、基于 Markdown 的静态 HTML 站点。
文档站点元数据和集成
请参阅有关文档站点的额外元数据以及静态文档，如最后一次更新的日期、站点所有者、顶级贡献者、打开 GitHub 问题、Slack 支持频道和 Stack Overflow Enterprise 标签。
内置导航和搜索
从文档中更快、更轻松地查找您想要的信息。
附加组件
使用附加组件自定义 TechDocs 体验，以解决高顺序的文档需求。

TechDocs 插件是预安装并在 Developer Hub 实例上启用的。您可以通过配置 Red Hat Developer Hub Helm chart 或 Red Hat Developer Hub Operator 配置映射来禁用或启用 TechDocs 插件并更改其他参数。

重要

Red Hat Developer Hub 包括一个内置的 TechDocs 构建器，它从您的代码库中生成静态 HTML 文档。但是，本地构建器的默认基本设置不适用于生产环境。

您可以将 CI/CD 管道与具有专用作业的存储库搭配使用，为 TechDocs 生成文档。生成的静态文件存储在 OpenShift Data Foundation 中，或存储在您选择的云存储解决方案中，并发布到静态 HTML 文档站点。

将 OpenShift Data Foundation 配置为存储 TechDocs 生成的文件后，您可以配置 TechDocs 插件，以使用 OpenShift Data Foundation 进行云存储。

其他资源

6.1. 为 TechDocs 文件配置存储

TechDocs 发布程序将生成的文件存储在本地存储或云存储中，如 OpenShift Data Foundation、Google GCS、AWS S3 或 Azure Blob Storage。

6.1.1. 使用 OpenShift Data Foundation 进行文件存储

您可以配置 OpenShift Data Foundation 以存储 TechDocs 生成的文件，而不依赖于其他云存储解决方案。

OpenShift Data Foundation 提供了一个 ObjectBucketClaim 自定义资源(CR)，您可以使用它来请求 S3 兼容存储桶后端。您必须安装 OpenShift Data Foundation Operator 来使用此功能。

先决条件

流程

  • 创建一个 ObjectBucketClaim CR，其中存储了生成的 TechDocs 文件。例如： 

    apiVersion: objectbucket.io/v1alpha1
kind: ObjectBucketClaim
metadata:
  name: <rhdh_bucket_claim_name>
spec:
  generateBucketName: <rhdh_bucket_claim_name>
  storageClassName: openshift-storage.noobaa.io
    注意

    创建 Developer Hub ObjectBucketClaim CR 会自动创建 Developer Hub ObjectBucketClaim 配置映射和 secret。配置映射和 secret 的名称与 ObjetBucketClaim CR 的名称相同。

创建 ObjectBucketClaim CR 后，您可以使用配置映射和 secret 中存储的信息，使 Developer Hub 容器可以作为环境变量访问这些信息。根据用来安装 Developer Hub 的方法，您可以将访问信息添加到 Red Hat Developer Hub Helm Chart 或 Operator 配置中。

其他资源

6.1.2. 使用 Helm Chart 使对象存储可供容器访问

创建 ObjectBucketClaim 自定义资源(CR)会自动生成 Developer Hub ObjectBucketClaim 配置映射和 secret。配置映射和 secret 包含 ObjectBucket 访问信息。在 Helm Chart 配置中添加访问信息可使 Developer Hub 容器访问它，方法是将以下环境变量添加到容器中：

  • BUCKET_NAME
  • BUCKET_HOST
  • BUCKET_PORT
  • BUCKET_REGION
  • BUCKET_SUBREGION
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

然后，在 TechDocs 插件配置中使用这些变量。

先决条件

流程

  • 在 Helm Chart 值中的 upstream.backstage 键中，输入 Developer Hub ObjectBucketClaim secret 的名称，作为 extraEnvVarsSecrets 字段的值和 extraEnvVarsCM 字段。例如： 

    upstream:
  backstage:
    extraEnvVarsSecrets:
      - <rhdh_bucket_claim_name>
    extraEnvVarsCM:
      - <rhdh_bucket_claim_name>

6.1.2.1. Helm Chart 的 TechDocs 插件配置示例

以下示例显示了 TechDocs 插件的 Developer Hub Helm Chart 配置： 

global:
  dynamic:
    includes:
      - 'dynamic-plugins.default.yaml'
  plugins:
    - disabled: false
      package: ./dynamic-plugins/dist/backstage-plugin-techdocs-backend-dynamic
      pluginConfig:
        techdocs:
          builder: external
          generator:
            runIn: local
          publisher:
            awsS3:
              bucketName: '${BUCKET_NAME}'
              credentials:
                accessKeyId: '${AWS_ACCESS_KEY_ID}'
                secretAccessKey: '${AWS_SECRET_ACCESS_KEY}'
              endpoint: 'https://${BUCKET_HOST}'
              region: '${BUCKET_REGION}'
              s3ForcePathStyle: true
            type: awsS3

6.1.3. 使用 Operator 使容器可以访问对象存储

创建 ObjectBucketClaim 自定义资源(CR)会自动生成 Developer Hub ObjectBucketClaim 配置映射和 secret。配置映射和 secret 包含 ObjectBucket 访问信息。在 Operator 配置中添加访问信息可使 Developer Hub 容器访问它，方法是将以下环境变量添加到容器中：

  • BUCKET_NAME
  • BUCKET_HOST
  • BUCKET_PORT
  • BUCKET_REGION
  • BUCKET_SUBREGION
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

然后，在 TechDocs 插件配置中使用这些变量。

先决条件

  • 已使用 Operator 在 OpenShift Container Platform 上安装 Red Hat Developer Hub。
  • 您已创建了 ObjectBucketClaim CR 来存储 TechDocs 生成的文件。

流程

  • 在 Developer Hub Backstage CR 中，输入 Developer Hub ObjectBucketClaim 配置映射的名称作为 spec.application.extraEnvs.configMaps 字段的值，并输入 Developer Hub ObjectBucketClaim secret 名称作为 spec.application.extraEnvs.secrets 字段的值。例如： 

    apiVersion: objectbucket.io/v1alpha1
kind: Backstage
metadata:
 name: <name>
spec:
  application:
    extraEnvs:
      configMaps:
        - name: <rhdh_bucket_claim_name>
      secrets:
        - name: <rhdh_bucket_claim_name>

6.1.3.1. Operator 的 TechDocs 插件配置示例

以下示例显示了 TechDocs 插件的 Red Hat Developer Hub Operator 配置映射配置： 

kind: ConfigMap
apiVersion: v1
metadata:
  name: dynamic-plugins-rhdh
data:
  dynamic-plugins.yaml: |
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - disabled: false
        package: ./dynamic-plugins/dist/backstage-plugin-techdocs-backend-dynamic
        pluginConfig:
          techdocs:
            builder: external
            generator:
              runIn: local
            publisher:
              awsS3:
                bucketName: '${BUCKET_NAME}'
                credentials:
                  accessKeyId: '${AWS_ACCESS_KEY_ID}'
                  secretAccessKey: '${AWS_SECRET_ACCESS_KEY}'
                endpoint: 'https://${BUCKET_HOST}'
                region: '${BUCKET_REGION}'
                s3ForcePathStyle: true
              type: awsS3
Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

© 2024 Red Hat, Inc.