Configure OpenShift Data Foundation

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

Before you begin

  • 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.

About this task

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.

Note

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

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
Note

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.

Make object storage accessible to containers by using the Helm chart

Add ObjectBucketClaim access information to the Helm chart configuration to make it accessible to the Developer Hub container as environment variables.

Before you begin

  • 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

About this task

Creating an ObjectBucketClaim custom resource (CR) automatically generates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret contain ObjectBucket access information. The Helm chart uses the following environment variables:

  • 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.

Procedure

In the Helm chart values, add the Developer Hub ObjectBucketClaim secret and config map to the extraEnvFrom field. For example:
extraEnvFrom:
  - secretRef:
      name: <rhdh_bucket_claim_name>
  - configMapRef:
      name: <rhdh_bucket_claim_name>

Example TechDocs Plugin configuration for the Helm chart

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

dynamicPlugins:
  includes:
    - 'dynamic-plugins.default.yaml'
  plugins:
    - enabled: true
      package: ref://backstage-plugin-techdocs-backend
      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

Configure object storage access with Operator

Add ObjectBucketClaim access infomation to the Operator configuration to make it accessible to the Developer Hub container as environment variables.

Before you begin

  • 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.

About this task

Creating an ObjectBucketClaim custom resource (CR) automatically generates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret contain ObjectBucket access information. The Operator uses the following environment variables:

  • 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.

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/v1alpha5
kind: {backstage}
metadata:
 name: <name>
spec:
  application:
    extraEnvs:
      configMaps:
        - name: <rhdh_bucket_claim_name>
      secrets:
        - name: <rhdh_bucket_claim_name>

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:
      - enabled: true
        package: ref://backstage-plugin-techdocs-backend
        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