feat: Support YAML configuration for Launcher

README.md

@@ -148,7 +148,20 @@ For non-Java applications or tools like `cqlsh`, you can run the Spanner Cassand
 
     This will create an executable jar file `spanner-cassandra-launcher.jar` inside the folder `google-cloud-spanner-cassandra/target`.
 
-* Run the jar using the command:
+* Run the jar using one of the following methods:
+
+    **1. Using a YAML Configuration File (Recommended for Production)**
+
+    For production setups, it is recommended to use a YAML file to configure the adapter. This method supports multiple listeners and global settings. See the [Configuration Options](docs/config-options.md) for a complete list of all supported options. An example `config.yaml` file can be found [here](docs/config-options.md#example-configyaml).
+
+    Then, run the launcher with the `-DconfigFilePath` system property:
+    ```bash
+    java -DconfigFilePath=/path/to/config.yaml -jar path/to/your/spanner-cassandra-launcher.jar
+    ```
+
+    **2. Using System Properties (for a single listener)**
+
+    For simpler setups or quick testing, you can provide the configuration via system properties. This method only supports a single adapter listener.
 
     ```bash
     java -DdatabaseUri=projects/my-project/instances/my-instance/databases/my-database \
@@ -159,9 +172,16 @@ For non-Java applications or tools like `cqlsh`, you can run the Spanner Cassand
     -jar path/to/your/spanner-cassandra-launcher.jar
     ```
 
-    * Replace the value of `-DdatabaseUri` with your Spanner database URI.
-    * You can omit `-Dhost` to use the default `0.0.0.0`, omit `-Dport` to use the default `9042`, and omit `-DnumGrpcChannels` to use the default `4`.
-    * `-DhealthCheckPort` is optional. If specified, a health check endpoint will be started on same IP address as that of the client on the specified port at url `/debug/health`. The health check endpoint will return HTTP status `200: OK` if the client is up and running, and `503: Service Unavailable` otherwise. The health check endpoint is NOT enabled by default.
+    **Configuration Notes:**
+
+    * **Database URI**: You must specify the Spanner database URI. This is done via the `databaseUri` property in YAML or the `-DdatabaseUri` system property.
+    * **Host**: The default host is `0.0.0.0`. This can be overridden with the `host` property in YAML or `-Dhost`.
+    * **Port**: The default port is `9042`. This can be overridden with the `port` property in YAML or `-Dport`.
+    * **gRPC Channels**: The default number of gRPC channels is `4`. This can be overridden with `numGrpcChannels` in YAML or `-DnumGrpcChannels`.
+    * **Health Check**: You can optionally enable a health check endpoint.
+        *   In YAML, set `healthCheckEndpoint` to a `host:port` value (e.g., "127.0.0.1:8080").
+        *   With system properties, use `-DhealthCheckPort` and specify a port. The host will default to the adapter's host.
+        *   When enabled, the endpoint is available at `/debug/health` and returns HTTP `200 OK` if the client is running, or `503 Service Unavailable` otherwise. The health check is disabled by default.
 
 ## View and manage client-side metrics
 

config.yaml

@@ -0,0 +1,22 @@
+# Global client configuration
+globalClientConfigs:
+  enableBuiltInMetrics: true
+  healthCheckEndpoint: "127.0.0.1:8080"
+
+# List of all listeners
+listeners:
+  - # Configuration for listener_1
+    name: "listener_1"
+    host: "127.0.0.1"
+    port: 9042
+    spanner:
+      databaseUri: "projects/span-cloud-testing/instances/pecheverri-cassandra/databases/default"
+      numGrpcChannels: 4
+      maxCommitDelayMillis: 5
+  - # Configuration for listener_2
+    name: "listener_2"
+    host: "127.0.0.2"
+    port: 9043
+    spanner:
+      databaseUri: "projects/span-cloud-testing/instances/pecheverri-cassandra/databases/default"
+      numGrpcChannels: 8

docs/config-options.md

@@ -0,0 +1,59 @@
+# Config Options
+
+This file documents all the configuration options supported by the Spanner Cassandra Adapter.
+
+```yaml
+# [Optional] Global client configurations that apply to all listeners.
+globalClientConfigs:
+  # [Optional] Enables built-in metrics. Defaults to false. It is highly recommended to enable metrics in production environments for improved debuggability.
+  enableBuiltInMetrics: true
+  # [Optional] The endpoint for the health check server. If not specified, the health check server will not be started.
+  # To check the status, send a GET request to the '/debug/health' path on this endpoint.
+  # - A '200 OK' status indicates that the service is healthy.
+  # - A '503 Service Unavailable' status indicates that one or more listeners failed to start.
+  healthCheckEndpoint: "127.0.0.1:8080"
+
+# A list of all listeners to start.
+listeners:
+    # The name of the listener. It is recommended to use a meaningful name, such as the cluster name.
+  - name: "listener_1"
+    # [Optional] The host to bind the listener to. Defaults to "0.0.0.0".
+    host: "127.0.0.1"
+    # [Optional] The port to bind the listener to. Defaults to 9042.
+    port: 9042
+    # Spanner configuration for this listener.
+    spanner:
+      # The URI of the Spanner database.
+      databaseUri: "projects/my-project/instances/my-instance/databases/my-database"
+      # [Optional] The number of gRPC channels to use. Defaults to 4.
+      numGrpcChannels: 4
+      # [Optional] The maximum commit delay in milliseconds. Defaults to 0ms.
+      # This is the amount of latency this request is willing to incur in order
+      # to improve throughput. If this field is not set, Spanner assumes requests
+      # are relatively latency sensitive and automatically determines an appropriate
+      # delay time.
+      maxCommitDelayMillis: 5
+```
+
+# Example config.yaml
+
+```yaml
+globalClientConfigs:
+  enableBuiltInMetrics: true
+  healthCheckEndpoint: "127.0.0.1:8080"
+
+listeners:
+  - name: "listener_1"
+    host: "127.0.0.1"
+    port: 9042
+    spanner:
+      databaseUri: "projects/my-project/instances/my-instance/databases/my-database"
+      numGrpcChannels: 4
+      maxCommitDelayMillis: 5
+  - name: "listener_2"
+    host: "127.0.0.2"
+    port: 9043
+    spanner:
+      databaseUri: "projects/my-project/instances/my-instance/databases/my-database-2"
+      numGrpcChannels: 8
+```