サポートコンソール開発者トライアルの開始お問い合わせ

第6章 TechDocs の設定

Red Hat Developer Hub TechDocs プラグインを設定して、中央の場所で標準化された方法でドキュメントを作成、検索、使用します。以下に例を示します。

docs-like-code アプローチ
技術ドキュメントを Markdown ファイルに記述し、コードとともにプロジェクトリポジトリー内に保存します。
ドキュメントサイトの生成
MkDocs を使用して、Developer Hub で一元的にレンダリングされるドキュメント用に、フル機能の Markdown ベースの静的 HTML サイトを作成します。
ドキュメントサイトのメタデータと統合
静的ドキュメントに加えて、最終更新日、サイト所有者、トップコントリビューター、未解決の GitHub イシュー、Slack サポートチャネル、Stack Overflow Enterprise タグなど、ドキュメントサイトに関する追加のメタデータを参照できます。
組み込みのナビゲーションおよび検索機能
ドキュメントから必要な情報をより迅速かつ簡単に検索します。
アドオン
より高次のドキュメントのニーズに対応するために、アドオンを使用して TechDocs エクスペリエンスをカスタマイズします。

TechDocs プラグインは、Developer Hub インスタンスにデフォルトでプリインストールされ、有効になっています。Red Hat Developer Hub の Helm チャートまたは Red Hat Developer Hub Operator の config map を設定することで、TechDocs プラグインを無効または有効にしたり、その他のパラメーターを変更したりできます。

重要

Red Hat Developer Hub には、コードベースから静的 HTML ドキュメントを生成する TechDocs ビルダーが組み込まれています。ただし、ローカルビルダーのデフォルトの基本設定は、実稼働環境向けではありません。

TechDocs のドキュメントを生成するための専用のリポジトリーで、CI/CD パイプラインを使用できます。生成された静的ファイルは、OpenShift Data Foundation または選択したクラウドストレージソリューションに保存され、静的 HTML ドキュメントサイトに公開されます。

TechDocs によって生成されるファイルを保存するように OpenShift Data Foundation を設定した後、OpenShift Data Foundation をクラウドストレージとして使用するように TechDocs プラグインを設定できます。

関連情報

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 をインストールする必要があります。

前提条件

手順

  • 生成された TechDocs ファイルを保存する ObjectBucketClaim CR を作成します。以下に例を示します。 

    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 の config map とシークレットの両方が自動的に作成されます。config map とシークレットの名前は ObjetBucketClaim CR と同じです。

ObjectBucketClaim CR を作成したら、config map とシークレットに保存されている情報を使用して、Developer Hub コンテナーからその情報に環境変数としてアクセスできるようにします。Developer Hub のインストールに使用した方法に応じて、Red Hat Developer Hub の Helm チャート設定または Operator 設定にアクセス情報を追加します。

関連情報

6.1.2. Helm チャートを使用してオブジェクトストレージをコンテナーからアクセス可能にする

ObjectBucketClaim カスタムリソース (CR) を作成すると、Developer Hub ObjectBucketClaim の config map とシークレットの両方が自動的に作成されます。config map とシークレットには ObjectBucket のアクセス情報が含まれています。Helm チャート設定にアクセス情報を追加すると、次の環境変数がコンテナーに追加され、Developer Hub コンテナーからその情報にアクセスできるようになります。

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

これらの変数は、TechDocs プラグインの設定で使用されます。

前提条件

手順

  • Helm チャート値の upstream.backstage キーに、extraEnvVarsSecrets フィールドと extraEnvVarsCM フィールドの値として、Developer Hub の ObjectBucketClaim シークレットの名前を入力します。以下に例を示します。 

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

6.1.2.1. Helm チャート用の TechDocs プラグイン設定の例

次の例は、TechDocs プラグイン用の Developer Hub Helm チャート設定を示しています。 

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 の config map とシークレットの両方が自動的に作成されます。config map とシークレットには 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 をインストールした。
  • TechDocs によって生成されるファイルを保存するための ObjectBucketClaim CR を作成した。

手順

  • Developer Hub Backstage CR で、spec.application.extraEnvs.configMaps フィールドの値として Developer Hub ObjectBucketClaim の config map の名前を入力し、spec.application.extraEnvs.secrets フィールドの値として Developer Hub ObjectBucketClaim のシークレット名を入力します。以下に例を示します。 

    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 の config map 設定を示しています。 

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

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.