Enable Topic Documentation in Redpanda Console

The Redpanda Operator deploys Redpanda Console v2.x, not v3.x.

Redpanda Console v3 is not yet available when deploying with the Redpanda Operator. The Redpanda Operator continues to deploy Redpanda Console v2. To try Redpanda Console v3 in Kubernetes, you can deploy Redpanda using the Redpanda Helm chart instead of the Redpanda Operator.

Redpanda Console configuration syntax varies by major version. Before configuring, determine which version you’re using:

# Check console version from deployment
kubectl get deployment -n <namespace> redpanda-console -o jsonpath='{.spec.template.spec.containers[0].image}'

# Or check from running pod
kubectl get pod -n <namespace> -l app.kubernetes.io/name=console -o jsonpath='{.items[0].spec.containers[0].image}'

# Or check from console logs
kubectl logs -n <namespace> -l app.kubernetes.io/name=console | grep "started Redpanda Console"

If you see output like redpandadata/console:v2.8.0, you’re using Redpanda Console v2.x. If you see redpandadata/console:v3.0.0, you’re using Redpanda Console v3.x.

You can embed topic documentation into the Redpanda Console user interface by providing access to a public or private Git repository that hosts the documentation files in Markdown format.

topic documentation

Redpanda Console clones the provided Git repository and stores all Markdown files it finds in memory. The Documentation tab in the frontend displays the content of the Markdown file that matches the name of the Kafka topic.

Path/Filename Topic Name Matches

ordersv2.md

orders-v2

Orders-v2.md

orders-v2

orders-v2.md

orders-v2

/orders/orders-v2.md

orders-v2

Repository information

Start by specifying the Git repository that contains the Markdown documentation files. Provide the repository URL, the branch, and the base directory that contains the documentation.

  • Standalone

  • Kubernetes embedded

  • Kubernetes standalone

console:
  topicDocumentation:
    git:
      enabled: true
      repository:
        url: https://github.com/<github-organization>/<repository-name>.git
        branch: <branch-name>
        baseDirectory: <base-directory-path>

When Redpanda Console is part of the Redpanda Helm chart or Operator:

  • Operator

  • Helm

apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  clusterSpec:
    console:
      enabled: true
      console:
        config:
          console:
            topicDocumentation:
              git:
                enabled: true
                repository:
                  url: https://github.com/<github-organization>/<repository-name>.git
                  branch: <branch-name>
                  baseDirectory: <base-directory-path>
console:
  enabled: true
  console:
    config:
      console:
        topicDocumentation:
          git:
            enabled: true
            repository:
              url: https://github.com/<github-organization>/<repository-name>.git
              branch: <branch-name>
              baseDirectory: <base-directory-path>

When using the standalone Redpanda Console Helm chart:

config:
  console:
    topicDocumentation:
      git:
        enabled: true
        repository:
          url: https://github.com/<github-organization>/<repository-name>.git
          branch: <branch-name>
          baseDirectory: <base-directory-path>

Refresh interval

Define how often Redpanda Console should refresh the documentation from the repository.

console:
  topicDocumentation:
    git:
      enabled: true
      refreshInterval: 10m
  • refreshInterval: Set a duration like 10m to refresh documentation every 10 minutes. Use 0 to disable automatic refresh.

Authenticate with private Git repositories

If the Git repository is private, Redpanda Console must authenticate using either:

Authenticate using a GitHub Personal Access Token (PAT)

  • Standalone

  • Kubernetes embedded

  • Kubernetes standalone

  1. Set the environment variables:

    TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME=token
    TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD=<github_pat>

    Replace <github_pat> with a GitHub personal access token that has repo scope.

  2. Configure Redpanda Console:

    console:
      topicDocumentation:
        git:
          enabled: true
          repository:
            url: https://github.com/<github-organization>/<repository-name>.git
            branch: <branch-name>
            baseDirectory: <base-directory-path>
          refreshInterval: 10m
          basicAuth:
            enabled: true
  1. Create the Secret:

    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-auth
      namespace: redpanda
    type: Opaque
    stringData:
      TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD: <github_pat>
  2. Configure the deployment:

    • Operator

    • Helm

    apiVersion: cluster.redpanda.com/v1alpha2
    kind: Redpanda
    metadata:
      name: redpanda
    spec:
      clusterSpec:
        console:
          enabled: true
          extraEnv:
            - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME
              value: token
          extraEnvFrom:
            - secretRef:
                name: topic-doc-git-auth
          console:
            config:
              console:
                topicDocumentation:
                  git:
                    enabled: true
                    repository:
                      url: https://github.com/<github-organization>/<repository-name>.git
                      branch: <branch-name>
                      baseDirectory: <base-directory-path>
                    refreshInterval: 10m
                    basicAuth:
                      enabled: true
    console:
      enabled: true
      extraEnv:
        - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME
          value: token
      extraEnvFrom:
        - secretRef:
            name: topic-doc-git-auth
      console:
        config:
          console:
            topicDocumentation:
              git:
                enabled: true
                repository:
                  url: https://github.com/<github-organization>/<repository-name>.git
                  branch: <branch-name>
                  baseDirectory: <base-directory-path>
                refreshInterval: 10m
                basicAuth:
                  enabled: true
  1. Create the Secret:

    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-auth
      namespace: redpanda
    type: Opaque
    stringData:
      TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD: <github_pat>
  2. Reference it in Helm values:

    config:
      console:
        topicDocumentation:
          git:
            enabled: true
            repository:
              url: https://github.com/<github-organization>/<repository-name>.git
              branch: <branch-name>
              baseDirectory: <base-directory-path>
            refreshInterval: 10m
            basicAuth:
              enabled: true
    
    extraEnv:
      - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME
        value: token
    
    extraEnvFrom:
      - secretRef:
          name: topic-doc-git-auth

Authenticate using SSH

  • Standalone

  • Kubernetes embedded

  • Kubernetes standalone

  1. Save the SSH key to a secure path (for example, /etc/redpanda/ssh/id_rsa).

  2. Set the environment variables:

    TOPICDOCUMENTATION_GIT_SSH_ENABLED=true
    TOPICDOCUMENTATION_GIT_SSH_USERNAME=git
    TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH=/etc/redpanda/ssh/id_rsa
    TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE=<private-key-passphrase>
  3. Configure Redpanda Console:

    console:
      topicDocumentation:
        git:
          enabled: true
          repository:
            url: git@github.com:<github-organization>/<repository-name>.git
            branch: <branch-name>
            baseDirectory: <base-directory-path>
          refreshInterval: 10m
          ssh:
            enabled: true
  1. Create the Secret:

    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-ssh
      namespace: redpanda
    type: Opaque
    stringData:
      privateKey: |
        -----BEGIN OPENSSH PRIVATE KEY-----
        <ssh-private-key>
        -----END OPENSSH PRIVATE KEY-----
      passphrase: <private-key-passphrase>
  2. Mount the secret and set environment variables:

    • Operator

    • Helm

    apiVersion: cluster.redpanda.com/v1alpha2
    kind: Redpanda
    metadata:
      name: redpanda
    spec:
      clusterSpec:
        console:
          enabled: true
          extraVolumeMounts:
            - name: git-ssh
              mountPath: /etc/git-ssh
              readOnly: true
          extraVolumes:
            - name: git-ssh
              secret:
                secretName: topic-doc-git-ssh
          extraEnv:
            - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED
              value: "true"
            - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME
              value: git
            - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH
              value: /etc/git-ssh/privateKey
            - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE
              value: <private-key-passphrase>
    console:
      enabled: true
      extraVolumeMounts:
        - name: git-ssh
          mountPath: /etc/git-ssh
          readOnly: true
      extraVolumes:
        - name: git-ssh
          secret:
            secretName: topic-doc-git-ssh
      extraEnv:
        - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED
          value: "true"
        - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME
          value: git
        - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH
          value: /etc/git-ssh/privateKey
        - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE
          value: <private-key-passphrase>
  1. Create the Secret:

    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-ssh
      namespace: redpanda
    type: Opaque
    stringData:
      privateKey: |
        -----BEGIN OPENSSH PRIVATE KEY-----
        <ssh-private-key>
        -----END OPENSSH PRIVATE KEY-----
      passphrase: <private-key-passphrase>
  2. Configure Helm values:

    config:
      console:
        topicDocumentation:
          git:
            enabled: true
            repository:
              url: git@github.com:<github-organization>/<repository-name>.git
              branch: <branch-name>
              baseDirectory: <base-directory-path>
            refreshInterval: 10m
            ssh:
              enabled: true
    
    extraVolumeMounts:
      - name: git-ssh
        mountPath: /etc/git-ssh
        readOnly: true
    
    extraVolumes:
      - name: git-ssh
        secret:
          secretName: topic-doc-git-ssh
    
    extraEnv:
      - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED
        value: "true"
      - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME
        value: git
      - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH
        value: /etc/git-ssh/privateKey
      - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE
        value: <private-key-passphrase>

Replace the following values throughout the examples:

  • <github-organization>: GitHub organization or user that owns the repository

  • <repository-name>: Name of the GitHub repository containing the topic documentation files

  • <branch-name>: Name of the Git branch to use (for example, main or docs)

  • <base-directory-path>: Relative path inside the repository where Markdown documentation files are stored

  • <github_pat>: GitHub personal access token with repo scope (used for basic authentication)

  • <ssh-private-key>: SSH private key content used to authenticate to GitHub (must be base64-safe if stored in secrets)

  • <private-key-passphrase>: Passphrase used to decrypt the SSH private key, if applicable

Example configuration

This example is for a setup where documentation needs frequent updates and is stored in a private repository accessed through SSH:

console:
  topicDocumentation:
    enabled: true
    git:
      enabled: true
      repository:
        url: https://github.com/example/redpanda-docs
        branch: main
        baseDirectory: path/to/documentation
      refreshInterval: 10m
      ssh:
        enabled: true
        username: git
        privateKeyFilepath: "/home/user/.ssh/redpanda_docs_key"
        passphrase: "passphrase"

This configuration is designed for a secure and automated integration of topic documentation into the Redpanda Console, using SSH for secure repository access and a refresh interval that keeps the documentation consistently updated without manual intervention.