|
| 1 | +# Bigtable proxy |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +A simple server meant to be used as a sidecar to maintain a persistent connection to Bigtable and |
| 6 | +collect metrics. The primary purpose is to support applications that can't maintain a longlived |
| 7 | +gRPC connection (ie. php in apache). |
| 8 | + |
| 9 | +The proxy is intended to be used as a local sidecar process. The proxy is intended to be shared by |
| 10 | +all processes on the VM that it is running on. It's listening address is hardcoded to `localhost`. |
| 11 | +The proxy will use [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials) |
| 12 | +for all outbound RPCs. |
| 13 | + |
| 14 | +The proxy will accept local unencrypted connections from Bigtable clients, and: |
| 15 | +- attach credentials |
| 16 | +- export metrics |
| 17 | +- send the RPC over an encrypted channel pool to Bigtable service |
| 18 | + |
| 19 | +## Features |
| 20 | + |
| 21 | +* Metrics - The proxy will track RPC metrics and export them to Google Cloud Monitoring |
| 22 | +* Multi tenant - The proxy can be used to connect to many different Bigtable instances |
| 23 | +* Credential handling - The proxy has its own set of credentials. It will ignore any inbound |
| 24 | + credentials from the client |
| 25 | +* Channel pooling - The proxy will maintain and autosize the outbound channel pool to properly |
| 26 | + load balance RPCs. |
| 27 | + |
| 28 | +## Metrics |
| 29 | + |
| 30 | +The proxy is instrumented with Opentelemtry and will export those metrics to Google Cloud Monitoring |
| 31 | +in a project your choosing. The metrics will be published under the namespace |
| 32 | +`workload.googleapis.com`. Available metrics: |
| 33 | + |
| 34 | +* `bigtableproxy.server.call.started` The total number of RPCs started, including those that have |
| 35 | + not completed. |
| 36 | +* `bigtableproxy.client.call.credential.duration` Latency of getting credentials |
| 37 | +* `bigtableproxy.client.call.queue.duration` Duration of how long the outbound side of the proxy had |
| 38 | + the RPC queued |
| 39 | +* `bigtableproxy.client.call.sent_total_message_size` Total bytes sent per call to Bigtable service |
| 40 | + (excluding metadata, grpc and transport framing bytes |
| 41 | +* `bigtableproxy.client.call.rcvd_total_message_size` Total bytes received per call from Bigtable |
| 42 | + service (excluding metadata, grpc and transport framing bytes) |
| 43 | +* `bigtableproxy.client.gfe.duration` Latency as measured by Google load balancer from the time it |
| 44 | + received the first byte of the request until it received the first byte of the response from the |
| 45 | + Cloud Bigtable service. |
| 46 | +* `bigtableproxy.client.gfe.duration_missing.count` Count of calls missing gfe response headers |
| 47 | +* `bigtableproxy.client.call.duration` Total duration of how long the outbound call took |
| 48 | +* `bigtableproxy.client.channel.count` Number of open channels |
| 49 | +* `bigtableproxy.client.call.max_outstanding_count` Maximum number of concurrent RPCs in a single |
| 50 | + minute window |
| 51 | +* `bigtableproxy.presence` Counts number of proxy processes (emit 1 per process). |
| 52 | + |
| 53 | +## Requirements |
| 54 | + |
| 55 | +* JVM >= 11 |
| 56 | +* Ensure that the service account includes the IAM roles: |
| 57 | + * `Monitoring Metric Writer` |
| 58 | + * `Bigtable User` |
| 59 | +* Ensure that the metrics project has `Stackdriver Monitoring API` enabled |
| 60 | + |
| 61 | +## Expected usage |
| 62 | + |
| 63 | +```sh |
| 64 | +# Build the binary |
| 65 | +mvn package |
| 66 | + |
| 67 | +# unpack the binary on the proxy host |
| 68 | +unzip target/bigtable-proxy-0.0.1-SNAPSHOT-bin.zip |
| 69 | +cd bigtable-proxy-0.0.1-SNAPSHOT |
| 70 | + |
| 71 | +# Verify that the proxy has require permissions using an existing table. Please note that the table |
| 72 | +# data will not be modified, however a test metric will be written. |
| 73 | +./bigtable-verify.sh \ |
| 74 | + --bigtable-project-id=$BIGTABLE_PROJECT_ID \ |
| 75 | + --bigtable-instance-id=$BIGTABLE_INSTANCE_ID \ |
| 76 | + --bigtable-table-id=$BIGTABLE_TABLE_ID \ |
| 77 | + --metrics-project-id=$METRICS_PROJECT_ID |
| 78 | + |
| 79 | +# Then start the proxy on the specified port. The proxy can forward requests for multiple |
| 80 | +# Bigtable projects/instances/tables. However it will export health metrics to a single project |
| 81 | +# specified by `metrics-project-id`. |
| 82 | +./bigtable-proxy.sh \ |
| 83 | + --listen-port=1234 \ |
| 84 | + --metrics-project-id=SOME_GCP_PROJECT |
| 85 | + |
| 86 | +# Start your application, and redirect the bigtable client to connect to the local proxy. |
| 87 | +export BIGTABLE_EMULATOR_HOST="localhost:1234" |
| 88 | +path/to/application/with/bigtable/client |
| 89 | +``` |
| 90 | + |
| 91 | +## Configuration |
| 92 | + |
| 93 | +Required options: |
| 94 | +* `--listen-port=<port>` The local port to listen for Bigtable client connections. This needs to |
| 95 | + match port in the `BIGTABLE_EMULATOR_HOST="localhost:<port>` environment variable passed to your |
| 96 | + application. |
| 97 | +* `--metrics-project-id=<projectid>` The Google Cloud project that should be used to collect metrics |
| 98 | + emitted from the proxy. |
| 99 | + |
| 100 | +Optional configuration: |
| 101 | +* The environment variable `GOOGLE_APPLICATION_CREDENTIALS` can be used to use a non-default service |
| 102 | + account. More details can be found here: https://cloud.google.com/docs/authentication/application-default-credentials |
0 commit comments