Exposing client configurations for download

Cloudera Surveyor exposes a per-cluster bundle of files on the Client Configurations tab of the Cluster Details page. End users can preview, copy, and download the files they need to connect external clients to a registered Kafka cluster.

End users of Cloudera Surveyor might need an easy way to download the files required to connect an external client to a specific Kafka cluster. You can configure Cloudera Surveyor to expose a bundle of such files on the Cluster Details > Client Configurations tab. From the tab, end users can preview file content, copy it to the clipboard, and download individual files or the full archive.

The primary use case is making Kafka client connection material easily accessible in one place, such as properties files, CA certificates, and usage instructions, without having to distribute them manually. You control what appears on the tab: the choice of files, their display names, and their descriptions in the UI. You can also surface any other cluster-related file, not only Kafka client configurations.

You configure this with the clusterConfigs.clusters[*].clientConfigs properties in your values file. The clientConfigs block is optional and per-cluster. Add it only to the clusters you want to expose files for. When clientConfigs is omitted for a cluster, the Client Configurations tab is empty for that cluster.

You store file content in Kubernetes Secrets in the same namespace as the Cloudera Surveyor release. You reference each file with a secretRef in clientConfigs.files, specifying the Secret name and the key within the Secret that holds the file content. The Cloudera Surveyor Helm chart automatically generates the pod volume and mount for each referenced Secret. No manual extraVolumes or extraVolumeMounts entries are required for client configuration files.

Creating Kubernetes Secrets for client configuration files

Create the Kubernetes Secrets that hold the file content for the client configuration bundle you want to expose in Cloudera Surveyor.

You store each file's content as a key in a Kubernetes Secret. You can group multiple files into a single Secret or use one Secret per logical source, such as one for client configuration properties files and one for TLS certificates. The key name in the Secret must match the secretRef.key value you declare in your values file.

Secrets must be in the same namespace as the Cloudera Surveyor release. If a Secret is already managed by cert-manager or a Kafka operator, you can reference it directly in your values file without creating a new one. When the Secret name and key remain the same, certificate rotations propagate to Cloudera Surveyor without a Helm upgrade.

Create a Secret for each file or group of files you want to include in the bundle. The following examples use kubectl to create two Secrets: one holding a client configuration properties file and a README, and one holding a CA certificate.

kubectl create secret generic [***CLIENT CONFIG SECRET NAME***] \
  --namespace [***NAMESPACE***] \
  --from-file=external.properties=[***PATH TO external.properties***] \
  --from-file=README.md=[***PATH TO README.md***]

kubectl create secret generic [***TLS SECRET NAME***] \
  --namespace [***NAMESPACE***] \
  --from-file=ca.crt=[***PATH TO CA CERTIFICATE***]

Alternatively, use a YAML manifest to create the same Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: [***CLIENT CONFIG SECRET NAME***]
  namespace: [***NAMESPACE***]
type: Opaque
stringData:
  external.properties: |
    [***CLIENT CONFIGURATION PROPERTIES***]
  README.md: |
    [***README CONTENT***]
---
apiVersion: v1
kind: Secret
metadata:
  name: [***TLS SECRET NAME***]
  namespace: [***NAMESPACE***]
type: Opaque
stringData:
  ca.crt: |
    [***CA CERTIFICATE (PEM)***]

[***NAMESPACE***] must be the same namespace as the Cloudera Surveyor release.
The key names (external.properties, README.md, ca.crt) must match the secretRef.key values you declare in your values file when you add clientConfigs to the cluster. When using kubectl, the key name is the part before the = in each --from-file flag.
You can add more files to a Secret by adding more --from-file flags or more keys under stringData. Each key becomes a separate file entry in clientConfigs.files.

Adding client configurations to a registered cluster

Declare clientConfigs in your values file for a registered Kafka cluster to populate the Client Configurations tab with files for end users to download.

You have created the Kubernetes Secrets that hold the file content in the Cloudera Surveyor release namespace. See Creating Kubernetes Secrets for client configuration files.

Add a clientConfigs block under the cluster entry in clusterConfigs.clusters in your values file.
```
#...
clusterConfigs:
  clusters:
    - clusterName: "[***CLUSTER NAME***]"
      bootstrapServers: "[***BOOTSTRAP SERVERS***]"
      clientConfigs:
        files:
          - name: external.properties
            contentType: text/plain
            description: "Kafka client properties for the external listener."
            secretRef:
              name: [***CLIENT CONFIG SECRET NAME***]
              key: external.properties
          - name: kafka-ca.crt
            contentType: application/x-pem-file
            description: "CA certificate for the Kafka broker."
            secretRef:
              name: [***TLS SECRET NAME***]
              key: ca.crt
          - name: README.md
            contentType: text/markdown
            description: "Usage instructions."
            secretRef:
              name: [***CLIENT CONFIG SECRET NAME***]
              key: README.md
```
- clientConfigs.files[*].name – The filename shown in the UI and used inside the zip archive. The Cloudera Surveyor Helm chart also uses this value as the file basename on the pod under /etc/surveyor/client-configs/[***CLUSTER NAME***]/. No separate path property is required.
- clientConfigs.files[*].contentType – The MIME type of the file. End users can preview files with a text/* or application/x-pem-file content type in the UI. Other types are available for download only.
- clientConfigs.files[*].description – Optional. A human-readable description shown alongside the filename in the UI.
- clientConfigs.files[*].secretRef.name – The name of the Kubernetes Secret in the Cloudera Surveyor release namespace that contains the file content.
- clientConfigs.files[*].secretRef.key – The key within the Secret whose value is the file content. Required.
Apply the changes with helm upgrade.
```
helm upgrade [***RELEASE NAME***] [***CHART***] \
  --namespace [***NAMESPACE***] \
  --values [***MY-VALUES.YAML***] \
  --reuse-values
```
note
When using helm upgrade, clusterConfigs properties are overridden and not merged, even if the --reuse-values option is specified. Always provide the full configuration for clusterConfigs during updates. Otherwise, previously set configuration might be lost. As a best practice, save a values file containing your complete clusterConfigs configuration. If you need to make changes, update this file and specify it with --values when running helm upgrade. Additionally use the --reuse-values option to retain other properties.

The Client Configurations tab shows the configured files for the cluster. End users can preview, copy, and download the files from the tab.