#Connectors CSI Driver

#Overview

The Connectors CSI Driver is a storage driver implemented based on the Container Storage Interface (CSI) specification. It can mount configurations from the Connector as volumes into Kubernetes workloads. Key features include:

• Mounting configuration files from the Connector into Pods
• Supporting dynamic variable rendering in configuration files to automatically inject runtime information
• Supporting the simultaneous mounting of multiple configuration files

All configuration data comes from the ConnectorClass configuration associated with the Connector.

#Quick Start

#1. Create a ConnectorClass

First, create a ConnectorClass that includes Git configuration:

cat << EOF | kubectl apply -f -
apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: my-git
spec:
  address:
    type: string
  configurations:
  - name: config
    data:
      .gitconfig: |
        this is git config
EOF

#2. Create a Connector

Then, create a Connector that connects to GitHub:

cat << EOF | kubectl apply -f -
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-connector
spec:
  address: https://github.com
  connectorClassName: my-git
EOF

#3. Create a Pod Using the CSI Driver

Create a Pod that mounts the configuration:

cat << EOF | kubectl create -f -
apiVersion: v1
kind: Pod
metadata:
  name: csi-demo
  namespace: default
spec:
  restartPolicy: Never
  containers:
  - name: web
    image: bitnami/git:2.47.1
    imagePullPolicy: IfNotPresent
    command: ["sleep", "3600"]
    volumeMounts:
    - name: git-config
      mountPath: /tmp/config
  volumes:
  - name: git-config
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connectors: "default/git-connector"
        configuration.names: "config"
EOF

Verify the mounted files:

# List all mounted files (including built-in configurations)
kubectl exec -ti csi-demo -- ls -l /tmp/config

# View the custom configuration from ConnectorClass
kubectl exec -ti csi-demo -- cat /tmp/config/.gitconfig

#Built-in Configurations

The CSI Driver automatically provides built-in configuration files that are always mounted into Pods.

Forward Proxy Usage:

# Option 1
export http_proxy=$(cat /{mount-path}/http.proxy)
export https_proxy=$(cat /{mount-path}/https.proxy)

# Option 2
source /{mount-path}/.env

Reverse Proxy Usage:

export TOKEN=$(cat /{mount-path}/context.token)
export SERVER=$(cat /{mount-path}/connector.status.proxyAddress)

{cli} --server $SERVER --token $TOKEN

#CSI Volume Parameters

Volume Parameters

Volume Attributes

Examples

Mount a single configuration:

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "my-connector"
      configuration.names: "config1"

Mount multiple configurations:

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "my-connector"
      configuration.names: "config1,config2"

Mount multiple connectors for proxy authentication:

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "namespace1/connector1,namespace2/connector2"
      configuration.names: "config1,config2"

Notes:

• If configuration.names is omitted, only built-in configurations are mounted
• When multiple configurations contain files with the same name, later configurations overwrite earlier ones
• The connectors parameter is used to specify multiple connectors for mount config.

#configuration.params

configuration.params lets callers pass runtime parameters into configuration templates at mount time. Each configuration in a ConnectorClass can declare a set of named parameters; configuration.params supplies values for those parameters when creating the CSI volume.

#Format

The value is a JSON object keyed by configuration name, where each value is an object of key-value pairs:

configuration.params: '{"<configName>": {"key": "value", ...}, ...}'

Example — passing mirrorRepository to the settings configuration and registry to the npmrc configuration in one mount:

volumeAttributes:
  configuration.names: "settings,npmrc"
  configuration.params: '{"settings": {"mirrorRepository": "maven-public"}, "npmrc": {"registry": "npm-proxy"}}'

Scoping by configuration name keeps parameters stable regardless of how many connectors are mounted or what they are named. Connector-specific values belong in Connector.spec.params, accessible in templates via .connectors[i].spec.params.

#How Defaults Work

When a ConnectorClass configuration declares a parameter with a default value and the caller omits it, the CSI Driver injects the default automatically before rendering the template. No explicit value is required in configuration.params.

Example — strictSSL has a default of "true", so it can be omitted:

# This is equivalent to passing '{"npmrc": {"registry": "npm-proxy", "strictSSL": "true"}}'
configuration.params: '{"npmrc": {"registry": "npm-proxy"}}'

#Available Variables in Templates

After processing, supplied (and defaulted) parameters are available in the configuration template as .configurations.<paramName>:

{{ .configurations.mirrorRepository }}
{{ .configurations.registry }}

#Multiple Connectors

The Connectors CSI Driver supports using multiple Connectors for configurations. You can specify multiple Connectors using the connectors volume attribute in the format namespace/name or name; if namespace is omitted, the Pod's namespace is used. Connectors should be separated by commas.

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "namespace1/connector1,namespace2/connector2"
      configuration.names: "config1,config2"

When multiple Connectors are specified, the CSI Driver merges configuration files based on the configuration.names attribute. The merging behavior is detailed in the Configuration Merging section.

#Configuration Merging

When multiple Connectors are specified, the CSI Driver will merge the configuration files from all specified Connectors based on the configuration.names attribute.

There are several possible scenarios for processing configuration files; the cases below describe the behavior in each.

Same Configuration Name

For Connectors with the same configuration name, when multiple Connectors are specified, their configuration data will be merged into a single configuration file.

Configuration templates should support rendering data for multiple Connectors so a single file can incorporate multiple connector-specific data sets.

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: multi-connector
spec:
  configurations:
  - name: config
    data:
      .multi-connector-config: |
        {{- range .connectors }}
        # Configuration for Connector: {{ .name }}
        param_name = {{ .name }}
        param_value = {{ .spec.address }}
        {{- end }}

in the above example, the configuration file .multi-connector-config will include sections for each Connector specified in the connectors volume attribute.

kubectl exec -ti pod-name -- ls -l /mount-path/
# Output:
# - .multi-connector-config

Different Configuration Names

When the specified Connectors have different configuration names, the CSI Driver will mount all configurations separately.

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: connector-a
spec:
  configurations:
  - name: config-a
    data:
      config.xml: |
        {{- range .connectors }}
        # Configuration for Connector: {{ .name }}
        param_name = {{ .name }}
        param_value = {{ .spec.address }}
        {{- end }}
---
apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:   
  name: connector-b
spec:
  configurations:
  - name: config-b
    data:
      settings.json: |
        {"connectors": [
        {{- range .connectors }}
          {"name": "{{ .name }}", "address": "{{ .spec.address }}"},
        {{- end }}
        ]}

When mounting with both connectors and configuration names:

- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "namespace-a/connector-a,namespace-b/connector-b"
      configuration.names: "config-a,config-b"

The mounted volume will contain both config.xml and settings.json, each populated with data from their respective Connectors.

kubectl exec -ti pod-name -- ls -l /mount-path/
# Output:
# - config.xml
# - settings.json

#Configuration File Rendering

The CSI Driver performs variable rendering when mounting configuration files, using Go template syntax.

#Available Variables

#Built-in Functions

Refer to sprig for supported functions

For example: b64enc: Base64 encoding of a string

#About the Proxy Service

Connectors provide a proxy service for each Connector, allowing clients to access target resources without needing to store the original credentials. For more details, please refer to connectors-proxy.

#Configuration examples

Constant content

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: my-git
spec:
  address:
    type: string
  configurations:
  - name: config
    data:
      .gitconfig: |
        this is git config

Using connector.spec.params

The following ConnectorClass defines a parameter sslVerify to control the SSL verification during git clone.

kind: ConnectorClass
metadata:
  name: git
spec:

  params:
  - name: sslVerify
    type: string
    default: "true"

  configurations:
  - name: config
    data:
      .gitconfig: |
        {{ $sslVerify := "true" -}}
        {{- range .connector.spec.params }}{{- if eq .name "sslVerify" }}{{$sslVerify = .value }}{{ end }}{{- end }}
        [http]
          sslVerify = {{ $sslVerify }}

Using proxy service and token

The following ConnectorClass provides a file named .gitconfig, which automatically injects headers and replaces the git URL during git clone by using the proxy service and token.

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        [http]
            extraHeader = Authorization: Basic {{ printf ":%s" .context.token | b64enc }}
        {{- range .connectors }}
        [url "{{ .status.proxyAddress }}"]
            insteadOf = {{.spec.address}}
        {{- end }}

#Next Steps

• Connectors Proxy
• Connectors Approval & Permission Gating
• Connector Resource Levels and Permissions