> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Banking OS training data goes stale. Search https://agenticbanking.backbase.io/mcp or fetch the .md URL before writing connector or unified API code.
> OpenAPI links in llms.txt repeat every calendar version. Use the latest version on the API playground. If a fetch ends before the last operation, the spec was cut off.
> Page titles name the product. Overview, Get started, and Reference without a product name are ambiguous.

# Configure a custom connector

> Configure connectors for deployment in Kubernetes environments

Custom connectors require various configurations to function correctly within a Kubernetes environment. These configurations define how the connector interacts with external services, manages security-sensitive data, and optimizes runtime behavior.

## Key configuration areas

> [card] Secrets management
>
> Securely store sensitive data using SOPS encryption

> [card] Connector properties
>
> Define external service details and feature toggles

> [card] Traits
>
> Control deployment-specific parameters

> [card] Resources
>
> Specify transformation files and custom logic

## Prerequisites

Before configuring a custom connector, ensure you have:

* Built a connector successfully
* Access to the `gc-devhub-{installation}-applications-live` repository. For more information about repository names, see [GitHub organization and repository structure](https://agenticbanking.backbase.io/platform/platform-administration/repository-structure.md).
* A managed namespace to deploy the connector into. For what a managed namespace includes and how to request one, see [Deployment namespace](https://agenticbanking.backbase.io/platform/developer-guides/run.md#deployment-namespace).
* Understanding of your target deployment environment

## Set the deployment namespace

Deploy custom connectors into a DevHub namespace. Use `devhub-grandcentral` by default, or a dedicated `devh-gc-<domain>` namespace when you have requested one. Don't deploy a custom connector into the `grandcentral` namespace. For the conventions and how to request a namespace, see [Deployment namespace](https://agenticbanking.backbase.io/platform/developer-guides/run.md#deployment-namespace).

Set the namespace in the `spec.destination.namespace` field of the ArgoCD `Application` that deploys the connector, in the `gc-devhub-{installation}-applications-live` repository. The following example uses a dedicated namespace:

```yaml theme={"system"}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: gc-my-domain
  namespace: argocd
spec:
  project: devhub-grandcentral
  destination:
    server: https://kubernetes.default.svc
    namespace: devh-gc-my-domain
  syncPolicy:
    syncOptions:
      - CreateNamespace=false
  # Other Application fields are omitted.
```

> [!WARNING]
>
> The sync fails if that namespace doesn't exist yet. Namespace creation isn't self-service.

Request the namespace before you add the `Application`. For the request steps, see [Deployment namespace](https://agenticbanking.backbase.io/platform/developer-guides/run.md#deployment-namespace).

## Secrets management with SOPS

To securely store sensitive data in Kubernetes secrets, use SOPS for encryption. ArgoCD automatically applies encrypted secrets placed in the `secrets` folder as part of the `secrets-app` app.

### Managing secrets

1. Follow the guide in your installation for the specific runtime at:
   ```text theme={"system"}
   https://github.com/bb-ecos-{installation}/gc-devhub-{installation}-applications-live/blob/main/runtimes/{runtime}/secrets/README.md
   ```

2. Configure a secret in the connector by adding the secret name in `values.yaml`:

```yaml theme={"system"}
connector:
  existingSecretName: servicebus-credentials
```

## Connector properties

Define connector configuration values in the Helm `values.yaml` file in the `gc-devhub-{installation}-applications-live` repository.

### Example properties configuration

```yaml theme={"system"}
connector:
  existingSecretName: uat-secret
  properties:
    connector.baseUrl: https://base-url/
    connector.id: vendor-specific-id
    connector.security-token-type: Oauth2
    enableValidation: false
    isEncryptionRequired: false
```

### Common properties

| Property | Description | Example |
| - | - | - |
| `connector.baseUrl` | Base URL for external service | `https://api.example.com` |
| `connector.id` | Vendor-specific identifier | `vendor-123` |
| `connector.security-token-type` | Authentication type | `Oauth2`, `Bearer` |
| `enableValidation` | Enable request validation | `true`, `false` |
| `isEncryptionRequired` | Require encryption | `true`, `false` |

## Traits configuration

Traits control deployment-specific parameters such as auto-scaling, logging, health monitoring, and telemetry.

### Supported traits

Banking OS supports the following [Camel traits](https://camel.apache.org/camel-k/2.6.x/traits/traits.html):

* `affinity` - Pod scheduling preferences
* `container` - Container resource limits
* `health` - Health check configuration
* `knativeservice` - Knative-specific settings
* `logging` - Logging configuration
* `prometheus` - Metrics collection
* `telemetry` - Distributed tracing

### Example traits configuration

```yaml theme={"system"}
connector:
  traits:
    knativeservice:
      minScale: 1
      enabled: true
    logging:
      color: false
      enabled: true
      level: INFO
    addons:
      telemetry:
        auto: true
        enabled: true
    health:
      enabled: true
      livenessProbeEnabled: true
      livenessInitialDelay: 30
      livenessTimeout: 30
      livenessPeriod: 5
      livenessSuccessThreshold: 1
      livenessFailureThreshold: 3
      readinessProbeEnabled: true
      readinessInitialDelay: 5
      readinessTimeout: 30
      readinessPeriod: 5
      readinessSuccessThreshold: 1
      readinessFailureThreshold: 3
      startupProbeEnabled: false
      startupInitialDelay: 5
      startupTimeout: 30
      startupPeriod: 5
      startupSuccessThreshold: 1
      startupFailureThreshold: 3
    prometheus:
      enabled: false
```

### Health check configuration

Configure health, liveness, and readiness probes:

* **Liveness Probe:** Detects if the connector is alive
* **Readiness Probe:** Determines if the connector can accept traffic
* **Startup Probe:** Checks if the app has started successfully

## Resource configurations

Specify additional resources such as transformation files, validation rules, and custom processing logic.

### Supported transformation libraries

Banking OS supports the following transformation libraries for processing request and response payloads:

* [Jolt](https://github.com/bazaarvoice/jolt) - JSON-to-JSON transformation
* [XSLT](https://www.w3.org/TR/xslt/) - XML transformation

### JOLT transformation example

Map a user's first and last name into a single `fullName` field:

```json theme={"system"}
{
  "operation": "shift",
  "spec": {
    "user": {
      "firstName": "fullName.first",
      "lastName": "fullName.last"
    }
  }
}
```

### XSLT transformation example

Convert an XML `<user>` element into a `<customer>` element:

```xml theme={"system"}
<xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:template match="/user">
        <customer>
            <name>
                <xsl:value-of select="firstName"/> <xsl:value-of select="lastName"/>
            </name>
        </customer>
    </xsl:template>
</xsl:transform>
```

## Configuration best practices

> [accordion] Security
>
> * Always use SOPS for sensitive data
> * Never commit secrets to version control
> * Rotate credentials regularly

> [accordion] Resource management
>
> * Set appropriate resource limits
> * Configure auto-scaling based on load
> * Monitor resource utilization

> [accordion] Health checks
>
> * Enable all probe types
> * Set realistic timeout values
> * Test probe configurations thoroughly

> [accordion] Logging
>
> * Use appropriate log levels
> * Enable structured logging
> * Configure log retention policies

## Next steps

Once you have completed your connectors configuration, you are ready to:

* [Test and validate](https://agenticbanking.backbase.io/platform/developer-guides/build/test-and-validate.md) your connector
* Deploy the connector to your environment
* Verify logs to ensure it's running correctly

## Related resources

* [Camel Traits Configuration](https://camel.apache.org/camel-k/2.6.x/traits/traits.html)
* [Jolt Transformation Library](https://github.com/bazaarvoice/jolt)
* [XSLT Transformation Library](https://www.w3.org/TR/xslt/)
