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
-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
41
-
($ASTRA_BUNDLE).
42
-
-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
43
-
($ASTRA_TOKEN).
44
-
-i, --astra-database-id=STRING Database ID of the Astra database. Requires '--astra-token' ($ASTRA_DATABASE_ID)
45
-
-c, --contact-points=CONTACT-POINTS,... Contact points for cluster. Ignored if using the bundle path or token option ($CONTACT_POINTS).
46
-
-u, --username=STRING Username to use for authentication ($USERNAME)
47
-
-p, --password=STRING Password to use for authentication ($PASSWORD)
48
-
-r, --port=9042 Default port to use when connecting to cluster ($PORT)
49
-
-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)
50
-
-m, --max-protocol-version="v4" Max protocol version supported by the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2) ($MAX_PROTOCOL_VERSION)
51
-
-a, --bind=":9042" Address to use to bind server ($BIND)
52
-
--debug Show debug logging ($DEBUG)
53
-
--health-check Enable liveness and readiness checks ($HEALTH_CHECK)
54
-
--http-bind=":8000" Address to use to bind HTTP server used for health checks ($HTTP_BIND)
55
-
--heartbeat-interval=30s Interval between performing heartbeats to the cluster ($HEARTBEAT_INTERVAL)
56
-
--idle-timeout=60s Duration between successful heartbeats before a connection to the cluster is considered unresponsive and closed ($IDLE_TIMEOUT)
57
-
--readiness-timeout=30s Duration the proxy is unable to connect to the backend cluster before it is considered not ready ($READINESS_TIMEOUT)
58
-
--num-conns=1 Number of connection to create to each node of the backend cluster ($NUM_CONNS)
39
+
-h, --help Show context-sensitive help.
40
+
-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
41
+
($ASTRA_BUNDLE).
42
+
-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
43
+
($ASTRA_TOKEN).
44
+
-i, --astra-database-id=STRING Database ID of the Astra database. Requires '--astra-token' ($ASTRA_DATABASE_ID)
45
+
--astra-api-url="https://api.astra.datastax.com" URL for the Astra API ($ASTRA_API_URL)
46
+
-c, --contact-points=CONTACT-POINTS,... Contact points for cluster. Ignored if using the bundle path or token option ($CONTACT_POINTS).
47
+
-u, --username=STRING Username to use for authentication ($USERNAME)
48
+
-p, --password=STRING Password to use for authentication ($PASSWORD)
49
+
-r, --port=9042 Default port to use when connecting to cluster ($PORT)
50
+
-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)
51
+
-m, --max-protocol-version="v4" Max protocol version supported by the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2) ($MAX_PROTOCOL_VERSION)
52
+
-a, --bind=":9042" Address to use to bind server ($BIND)
--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)
61
+
--rpc-address=STRING Address to advertise in the 'system.local' table for'rpc_address'. It must be setif configuring peer proxies ($RPC_ADDRESS)
62
+
--data-center=STRING Data center to use in system tables ($DATA_CENTER)
63
+
--tokens=TOKENS,... Tokens to use in the system tables. It's not recommended ($TOKENS)
59
64
```
60
65
61
-
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.
66
+
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:
86
+
87
+
```yaml
88
+
contact-points:
89
+
- 127.0.0.1
90
+
username: cassandra
91
+
password: cassandra
92
+
port: 9042
93
+
bind: 127.0.0.1:9042
94
+
# ...
95
+
```
96
+
97
+
or with a Astra token:
98
+
99
+
```yaml
100
+
astra-token: <astra-token>
101
+
astra-database-id: <astra-database-id>
102
+
bind: 127.0.0.1:9042
103
+
# ...
104
+
```
105
+
106
+
All configuration keys match their command-line flag counterpart, e.g. `--astra-bundle` is
107
+
`astra-bundle`, `--contact-points` is `contact-points` etc.
108
+
109
+
#### Setting up peer proxies
110
+
111
+
There a couple cases when it is useful to setup multiple proxies:
112
+
* Multi-region failover with DC-aware load balancing policy.
113
+
* Compatibility with drivers that require a replication factor number of nodes (proxies) in a cluster for token-aware load balancing. This is not a problem for most drivers as they print a warning when there's less than replication factor nodes, and fallback to round-robin load balancing. The `gocql` driver is a notable exception, it panics when there's not enough proxies. In this case, it is best to configure the round-robin load balancing policy, but if that can't be donethen multiple proxies should be used.
114
+
115
+
When configuration `peers:` it is required to set`--rpc-address` (or `rpc-address:`in the yaml) foreach proxy and it must match is correspond `peers:` entry. Also, `peers:` is only availablein 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 in the cluster and connects 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
+
145
+
##### Token-aware bypass setup
146
+
147
+
This setup is similar to the multi-region setup but is simpler because all proxy instances share the same data center value which can just use the default value (`dc1`). Replication factor is often set to `3`, so it will require creating three instances of the proxy, but this may be different for your application.
@@ -100,7 +194,7 @@ There are three methods for using `cql-proxy`:
100
194
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]:
Copy file name to clipboardExpand all lines: proxy/run.go
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -57,7 +57,7 @@ var config struct {
57
57
IdleTimeout time.Duration`yaml:"idle-timeout" help:"Duration between successful heartbeats before a connection to the cluster is considered unresponsive and closed" default:"60s" env:"IDLE_TIMEOUT"`
58
58
ReadinessTimeout time.Duration`yaml:"readiness-timeout" help:"Duration the proxy is unable to connect to the backend cluster before it is considered not ready" default:"30s" env:"READINESS_TIMEOUT"`
59
59
NumConnsint`yaml:"num-conns" help:"Number of connection to create to each node of the backend cluster" default:"1" env:"NUM_CONNS"`
60
-
RpcAddressstring`yaml:"rpc-address" help:"Address to advertise in the 'system.local' table for 'rpc_address'" env:"RPC_ADDRESS"`
60
+
RpcAddressstring`yaml:"rpc-address" help:"Address to advertise in the 'system.local' table for 'rpc_address'. It must be set if configuring peer proxies" env:"RPC_ADDRESS"`
61
61
DataCenterstring`yaml:"data-center" help:"Data center to use in system tables" env:"DATA_CENTER"`
62
62
Tokens []string`yaml:"tokens" help:"Tokens to use in the system tables. It's not recommended" env:"TOKENS"`
63
63
Peers []PeerConfig`yaml:"peers" kong:"-"`// Not available as a CLI flag
0 commit comments