---
title: "Decoupled configuration"
description: "Learn how the Aerospike SDK decouples cluster connection settings from developer-defined operational behaviors."
---

# Decoupled configuration

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

The Developer SDK separates **connection configuration** from **operational behavior**, giving operators and developers independent control.

## Why decoupled configuration?

Traditional clients mix connection settings with operation policies, making it hard to:

-   Change timeouts without code changes
-   Use different configurations per environment
-   Let operators tune behavior without developer involvement

The Developer SDK solves this with three layers:

```plaintext
┌─────────────────────────────────────────┐

│           Application Code              │

│  (uses Session, calls operations)       │

├─────────────────────────────────────────┤

│            Behaviors                    │

│  (operational policies, developer-set)  │

├─────────────────────────────────────────┤

│         Cluster Configuration           │

│  (connection details, operator-set)     │

└─────────────────────────────────────────┘
```

## Cluster configuration (operators)

Connection details that operators control:

-   [Java](#tab-panel-3055)
-   [Python](#tab-panel-3056)

```java
import com.aerospike.client.sdk.Cluster;

import com.aerospike.client.sdk.ClusterDefinition;

// From environment variables

Cluster cluster = new ClusterDefinition(

        System.getenv("AEROSPIKE_HOST"),

        3000)

    .withNativeCredentials(

        System.getenv("AEROSPIKE_USER"),

        System.getenv("AEROSPIKE_PASSWORD"))

    .connect();
```

> 📖 **API reference**: [`ClusterDefinition.connect()`](https://javadoc.io/doc/com.aerospike/aerospike-client-sdk/latest/com/aerospike/client/sdk/ClusterDefinition.html#connect%28%29) | [`ClusterDefinition.withNativeCredentials(...)`](https://javadoc.io/doc/com.aerospike/aerospike-client-sdk/latest/com/aerospike/client/sdk/ClusterDefinition.html#withNativeCredentials%28java.lang.String%2Cjava.lang.String%29)

```python
import os

from aerospike_sdk import ClusterDefinition

# From environment variables

cluster = await ClusterDefinition(

    os.environ["AEROSPIKE_HOST"],

    3000,

).with_native_credentials(

    os.environ.get("AEROSPIKE_USER"),

    os.environ.get("AEROSPIKE_PASSWORD"),

).connect()
```

> 📖 **API reference**: [`ClusterDefinition`](https://aerospike-python-sdk.readthedocs.io/en/latest/api/cluster-definition.html)

## Behaviors (developers)

Operational policies that developers control:

-   [Java](#tab-panel-3057)
-   [Python](#tab-panel-3058)

```java
// Developer chooses behavior for their use case

Behavior readHeavyBehavior = Behavior.DEFAULT.deriveWithChanges("READ_HEAVY", b -> {});

Behavior writeHeavyBehavior = Behavior.DEFAULT.deriveWithChanges("WRITE_HEAVY", b -> {});

Session readHeavy = cluster.createSession(readHeavyBehavior);

Session writeHeavy = cluster.createSession(writeHeavyBehavior);

Session balanced = cluster.createSession(Behavior.DEFAULT);
```

> 📖 **API reference**: [`Cluster.createSession(Behavior)`](https://javadoc.io/doc/com.aerospike/aerospike-client-sdk/latest/com/aerospike/client/sdk/Cluster.html#createSession%28com.aerospike.client.sdk.policy.Behavior%29)

```python
# Developer chooses behavior for their use case

read_heavy = cluster.create_session(Behavior.READ_FAST)

write_heavy = cluster.create_session(Behavior.DEFAULT)

balanced = cluster.create_session(Behavior.DEFAULT)
```

> 📖 **API reference**: [`Behavior.DEFAULT`](https://aerospike-python-sdk.readthedocs.io/en/latest/api/behavior.html#aerospike%5Fsdk.policy.behavior.Behavior.DEFAULT)

## External configuration files

Load configuration from YAML or properties files:

aerospike-config.yaml

```yaml
cluster:

  hosts:

    - host: prod-aerospike-1.example.com

      port: 3000

    - host: prod-aerospike-2.example.com

      port: 3000

  tls:

    enabled: true

    cert_file: /etc/ssl/aerospike.crt
```

## Configuration precedence

1.  **Code** (highest) — Explicit settings in code
2.  **Environment Variables** — `AEROSPIKE_*` variables
3.  **Config Files** — YAML/properties files
4.  **Defaults** (lowest) — Built-in sensible defaults

## Next steps

-   [Behaviors](https://aerospike.com/docs/develop/client/sdk/concepts/behaviors)
-   [Connect to Aerospike](https://aerospike.com/docs/develop/client/sdk/connect)
-   [Connect with TLS](https://aerospike.com/docs/develop/client/sdk/connect#connect-with-tls)