Red Hat Summit Red Hat Summit지원콘솔개발자평가판 시작연락처

2장. Configuring TechDocs

The TechDocs plugin is preinstalled and enabled on a Developer Hub instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the Red Hat Developer Hub Helm chart or the Red Hat Developer Hub Operator ConfigMap.

중요

Red Hat Developer Hub includes a built-in TechDocs builder that generates static HTML documentation from your codebase. However, the default basic setup of the local builder is not intended for production.

You can use a CI/CD pipeline with the repository that has a dedicated job to generate docs for TechDocs. The generated static files are stored in OpenShift Data Foundation or in a cloud storage solution of your choice and published to a static HTML documentation site.

After you configure OpenShift Data Foundation to store the files that TechDocs generates, you can configure the TechDocs plugin to use the OpenShift Data Foundation for cloud storage.

2.1. Configuring storage for TechDocs files
링크 복사

The TechDocs publisher stores generated files in local storage or in cloud storage, such as AWS S3 or OpenShift Data Foundation.

2.1.1. Configuring Amazon S3 for file storage
링크 복사

You can create a dedicated Amazon S3 bucket to store TechDocs sites. {product} uploads TechDocs to this bucket and serves them from the same location.

Prerequisites

  • You are logged in to your AWS account as an administrator.

Procedure

  1. On the AWS console, create an AWS S3 bucket.

    1. On the Create bucket page, enter a Bucket name and use the default selections for all other settings.
    2. Create an IAM policy to give authorized users permissions to generate and publish TechDocs for your organization.

    3. On the Create policy > Specify permissions page, in the Policy editor, enter the following JSON content: 

      {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "TechDocsList",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::_<bucket_name>_"
        },
        {
            "Sid": "TechDocsObjects",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:DeleteObjectVersion"
            ],
            "Resource": "arn:aws:s3:::_<bucket_name>_/*"
        }
    ]
}

      where

      <bucket_name>
      Specifies the name of your Amazon S3 bucket.
    4. On the Create policy > Specify permissions page, enter a Policy name.
  2. Assign the IAM policy to a new or existing user.

  3. Generate a new access key and a new secret access key.

    참고

    You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.

  4. From the OpenShift Container Platform web console, click Topology > Actions > Restart rollout to restart the pod.

    참고

    You must restart the pod to apply the configuration changes.

Verification

  1. Go to your Amazon S3 bucket to see a set of static site files in your Objects list.

2.1.2. Configuring OpenShift Data Foundation for file storage
링크 복사

You can configure OpenShift Data Foundation to store the files that TechDocs generates instead of relying on other cloud storage solutions.

OpenShift Data Foundation provides an ObjectBucketClaim custom resource (CR) that you can use to request an S3-compatible bucket backend. You must install the OpenShift Data Foundation Operator to use this feature.

+

참고

For air-gapped environments, using OpenShift Data Foundation is the recommended storage for TechDocs.

Prerequisites

  • An OpenShift Container Platform administrator has installed the OpenShift Data Foundation Operator in Red Hat OpenShift Container Platform, created an OpenShift Data Foundation cluster and configured the StorageSystem schema. For more information, see Deploying OpenShift Data Foundation using Amazon Web Services.

Procedure

  • Create an ObjectBucketClaim CR where the generated TechDocs files are stored. For example: 

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

    Creating the Developer Hub ObjectBucketClaim CR automatically creates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret have the same name as the ObjectBucketClaim CR.

After you create the ObjectBucketClaim CR, you can use the information stored in the config map and secret to make the information accessible to the Developer Hub container as environment variables. Depending on the method that you used to install Developer Hub, you add the access information to either the Red Hat Developer Hub Helm chart or Operator configuration.

2.1.2.1. Making object storage accessible to containers by using the Helm chart
링크 복사

Creating a ObjectBucketClaim custom resource (CR) automatically generates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret contain ObjectBucket access information. Adding the access information to the Helm chart configuration makes it accessible to the Developer Hub container by adding the following environment variables to the container:

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

These variables are then used in the TechDocs plugin configuration.

Prerequisites

  • You have installed Red Hat Developer Hub on OpenShift Container Platform using the Helm chart.
  • You have created an ObjectBucketClaim CR for storing files generated by TechDocs. For more information see Using OpenShift Data Foundation for file storage

Procedure

  • In the upstream.backstage key in the Helm chart values, enter the name of the Developer Hub ObjectBucketClaim secret as the value for the extraEnvVarsSecrets field and the extraEnvVarsCM field. For example: 

    upstream:
  backstage:
    extraEnvVarsSecrets:
      - <rhdh_bucket_claim_name>
    extraEnvVarsCM:
      - <rhdh_bucket_claim_name>
2.1.2.1.1. Example TechDocs Plugin configuration for the Helm chart
링크 복사

The following example shows a Developer Hub Helm chart configuration for the TechDocs plugin: 

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

2.1.2.2. Making object storage accessible to containers by using the Operator
링크 복사

Creating a ObjectBucketClaim custom resource (CR) automatically generates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret contain ObjectBucket access information. Adding the access information to the Operator configuration makes it accessible to the Developer Hub container by adding the following environment variables to the container:

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

These variables are then used in the TechDocs plugin configuration.

Prerequisites

  • You have installed Red Hat Developer Hub on OpenShift Container Platform using the Operator.
  • You have created an ObjectBucketClaim CR for storing files generated by TechDocs.

Procedure

  • In your Backstage CR, enter the name of the Developer Hub ObjectBucketClaim config map as the value for the spec.application.extraEnvs.configMaps field and enter the Developer Hub ObjectBucketClaim secret name as the value for the spec.application.extraEnvs.secrets field. For example: 

    apiVersion: rhdh.redhat.com/v1alpha3
kind: Backstage
metadata:
 name: <name>
spec:
  application:
    extraEnvs:
      configMaps:
        - name: <rhdh_bucket_claim_name>
      secrets:
        - name: <rhdh_bucket_claim_name>
2.1.2.2.1. Example TechDocs Plugin configuration for the Operator
링크 복사

The following example shows a Red Hat Developer Hub Operator config map configuration for the TechDocs plugin: 

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은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

Legal Notice

Theme

© 2026 Red Hat맨 위로 이동