You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Merge pull request #88 from datastax/config-and-peers
Multiple proxies can be configured to work together for:
* Multi-region failover in Astra DB.
* ~Bypassing drivers that require at least replication factor number of
nodes in a cluster for token-aware load balancing.~
Also, added a feature to configure the proxy using a YAML configuration
file. This is necessary for configuring multiple proxies for the `peers`
value. All keys match their CLI counterparts:
```yaml
astra-bundle: path/to/secure-connect-bundle.zip
username: <username>
password: <password>
bind: 127.0.0.1:9042
rpc-address: 127.0.0.1
peers:
- rpc-address: 127.0.0.1
data-center: dc-1
- rpc-address: 127.0.0.2
data-center: dc-2
```
`peers` is not available via CLI option because it's a complex,
composite value. It's possible to configure everything on the CLI other
than `peers` and put only that in a configuration file.
Copy file name to clipboardExpand all lines: README.md
+88-22Lines changed: 88 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,29 +38,34 @@ $ ./cql-proxy -h
38
38
Usage: cql-proxy
39
39
40
40
Flags:
41
-
-h, --help Show context-sensitive help.
42
-
-b, --astra-bundle=STRING Path to secure connect bundle for an Astra database. Requires '--username' and '--password'. Ignored if using the token or contact points option
43
-
($ASTRA_BUNDLE).
44
-
-t, --astra-token=STRING Token used to authenticate to an Astra database. Requires '--astra-database-id'. Ignored if using the bundle path or contact points option
45
-
($ASTRA_TOKEN).
46
-
-i, --astra-database-id=STRING Database ID of the Astra database. Requires '--astra-token' ($ASTRA_DATABASE_ID)
47
-
-c, --contact-points=CONTACT-POINTS,... Contact points for cluster. Ignored if using the bundle path or token option ($CONTACT_POINTS).
48
-
-u, --username=STRING Username to use for authentication ($USERNAME)
49
-
-p, --password=STRING Password to use for authentication ($PASSWORD)
50
-
-r, --port=9042 Default port to use when connecting to cluster ($PORT)
51
-
-n, --protocol-version="v4" Initial protocol version to use when connecting to the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2) ($PROTOCOL_VERSION)
52
-
-m, --max-protocol-version="v4" Max protocol version supported by the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2) ($MAX_PROTOCOL_VERSION)
53
-
-a, --bind=":9042" Address to use to bind server ($BIND)
54
-
--debug Show debug logging ($DEBUG)
55
-
--health-check Enable liveness and readiness checks ($HEALTH_CHECK)
56
-
--http-bind=":8000" Address to use to bind HTTP server used for health checks ($HTTP_BIND)
57
-
--heartbeat-interval=30s Interval between performing heartbeats to the cluster ($HEARTBEAT_INTERVAL)
58
-
--idle-timeout=60s Duration between successful heartbeats before a connection to the cluster is considered unresponsive and closed ($IDLE_TIMEOUT)
59
-
--readiness-timeout=30s Duration the proxy is unable to connect to the backend cluster before it is considered not ready ($READINESS_TIMEOUT)
60
-
--num-conns=1 Number of connection to create to each node of the backend cluster ($NUM_CONNS)
41
+
-h, --help Show context-sensitive help.
42
+
-b, --astra-bundle=STRING Path to secure connect bundle for an Astra database. Requires '--username' and '--password'. Ignored if using the token or contact points option
43
+
($ASTRA_BUNDLE).
44
+
-t, --astra-token=STRING Token used to authenticate to an Astra database. Requires '--astra-database-id'. Ignored if using the bundle path or contact points option
45
+
($ASTRA_TOKEN).
46
+
-i, --astra-database-id=STRING Database ID of the Astra database. Requires '--astra-token' ($ASTRA_DATABASE_ID)
47
+
--astra-api-url="https://api.astra.datastax.com" URL for the Astra API ($ASTRA_API_URL)
48
+
-c, --contact-points=CONTACT-POINTS,... Contact points for cluster. Ignored if using the bundle path or token option ($CONTACT_POINTS).
49
+
-u, --username=STRING Username to use for authentication ($USERNAME)
50
+
-p, --password=STRING Password to use for authentication ($PASSWORD)
51
+
-r, --port=9042 Default port to use when connecting to cluster ($PORT)
52
+
-n, --protocol-version="v4" Initial protocol version to use when connecting to the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2) ($PROTOCOL_VERSION)
53
+
-m, --max-protocol-version="v4" Max protocol version supported by the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2) ($MAX_PROTOCOL_VERSION)
54
+
-a, --bind=":9042" Address to use to bind server ($BIND)
--health-check Enable liveness and readiness checks ($HEALTH_CHECK)
58
+
--http-bind=":8000" Address to use to bind HTTP server used for health checks ($HTTP_BIND)
59
+
--heartbeat-interval=30s Interval between performing heartbeats to the cluster ($HEARTBEAT_INTERVAL)
60
+
--idle-timeout=60s Duration between successful heartbeats before a connection to the cluster is considered unresponsive and closed ($IDLE_TIMEOUT)
61
+
--readiness-timeout=30s Duration the proxy is unable to connect to the backend cluster before it is considered not ready ($READINESS_TIMEOUT)
62
+
--num-conns=1 Number of connection to create to each node of the backend cluster ($NUM_CONNS)
63
+
--rpc-address=STRING Address to advertise in the 'system.local' table for'rpc_address'. It must be setif configuring peer proxies ($RPC_ADDRESS)
64
+
--data-center=STRING Data center to use in system tables ($DATA_CENTER)
65
+
--tokens=TOKENS,... Tokens to use in the system tables. It's not recommended ($TOKENS)
61
66
```
62
67
63
-
To pass configuration to `cql-proxy`, either command-line flags or environment variables can be used. Using the `docker` method as an example, the following samples show how the token and database ID are defined with each method.
68
+
To pass configuration to `cql-proxy`, either command-line flags, environment variables, or a configuration file can be used. Using the `docker` method as an example, the following samples show how the token and database ID are defined with each method.
Proxy settings can also be passed using a configuration file with the `--config /path/to/proxy.yaml` flag. This can be mixed and matched with command-line flags and environment variables. Here are some example configuration files:
88
+
89
+
```yaml
90
+
contact-points:
91
+
- 127.0.0.1
92
+
username: cassandra
93
+
password: cassandra
94
+
port: 9042
95
+
bind: 127.0.0.1:9042
96
+
# ...
97
+
```
98
+
99
+
or with a Astra token:
100
+
101
+
```yaml
102
+
astra-token: <astra-token>
103
+
astra-database-id: <astra-database-id>
104
+
bind: 127.0.0.1:9042
105
+
# ...
106
+
```
107
+
108
+
All configuration keys match their command-line flag counterpart, e.g. `--astra-bundle` is
109
+
`astra-bundle:`, `--contact-points` is `contact-points:` etc.
110
+
111
+
#### Setting up peer proxies
112
+
113
+
Multi-region failover with DC-aware load balancing policy is the most useful case for a multiple proxy setup.
114
+
115
+
When configuring `peers:` it is required to set `--rpc-address` (or `rpc-address:` in the yaml) for each proxy and it must match is corresponding `peers:` entry. Also, `peers:` is only available in the configuration file and cannot be set using a command-line flag.
116
+
117
+
##### Multi-region setup
118
+
119
+
Here's an example of configuring multi-region failover with two proxies. A proxy is started for each region of the cluster connecting to it using that region's bundle. They all share a common configuration file that contains the full list of proxies.
120
+
121
+
*Note:* Only bundles are supported for multi-region setups.
The peers settings are configured using a yaml file. It's a good idea to explicitly provide the `--data-center` flag, otherwise; these values are pulled from the backend cluster and would need to be pulled from the `system.local` and `system.peers` table to properly setup the peers `data-center:` values. Here's an example `proxy.yaml`:
134
+
135
+
```yaml
136
+
peers:
137
+
- rpc-address: 127.0.0.1
138
+
data-center: dc-1
139
+
- rpc-address: 127.0.0.2
140
+
data-center: dc-2
141
+
```
142
+
143
+
*Note:* It's okay for the `peers:` to contain entries for the current proxy itself because they'll just be omitted.
144
+
79
145
## Getting started
80
146
81
147
There are three methods for using `cql-proxy`:
@@ -102,7 +168,7 @@ There are three methods for using `cql-proxy`:
102
168
The `<astra-token>` can be generated using these [instructions]. The proxy also supports using the [Astra Secure Connect Bundle][bundle] along with a client ID and secret generated using these [instructions]:
0 commit comments