# Cluster Proxy

**Notice: This repo has been merged into https://github.com/tidbcloud/infra-provider/tree/main/clusterproxy for easier maintenance.**

The cluster proxy routes requests to different backends in the Kubernetes cluster.

## APIs

The proxy itself is a HTTP server, and it serves HTTPS with the flag `--tls-dir` specified.

All Urls start with the base of `/proxy/cluster/{clusterID}`

- `/v1/pd` which proxies the requests directly to the `pd` service of the TiDB cluster

- `/v1/prometheus`  which proxies the requests directly to the `prometheus` service of the TiDB cluster

- `/v1/kubernetes_dashboard`  which proxies the requests directly to the kubernetes dashboard of the Kubernetes cluster.

- `/v1/terminal` which provides a SQL shell on the browser.

- `/v1/change_password` which alters the root user password.

- `/v1beta1/create_admin` create the cloud_admin user at initialization time when the root password is empty. This API can be called repeatedly (in case of an error during operations) until the root password is set (by change_password)

- `/v1beta1/execute` which execute the given SQL statements on the TiDB cluster.

- `/v1beta1/query` runs the query and returns the resulting data.

Execute and query support run ad-hoc SQL. Some common queries are hard-coded into the API as alternatives to sending raw ad-hoc SQL (look at the parameters). Hard-coding the SQL at the clusterproxy improves security.

The version `v1beta1` in the `execute` route marks the version of the API. The versions and other information including the schema of the route path can be found in the file `service.lock.yaml`. The version of an API represents the maturity of the API: `v1alpha1` and `v1beta1` mean the schema and the path of the API are subject to changes, and version `v1` suggests a stable API schema. More details can be found in the design doc: http://go/improve-cluster-proxy

## Development 

### Build
To build the binary, simply run 

```bash
make build
```

The following command will build a container image tagged `cluster-proxy:local`.

```bash
make docker-build
```

### Verification 

To verify the functionality of the proxy, you may want to deploy the proxy on a Kubernetes cluster along with a TiDB cluster. The script `cluster.sh` provides a quick start for a local deployment on a Kind cluster:

```bash
./scripts/cluster.sh up
```

The above command will start a local Kind cluster and a local container image registry, build the proxy image and push the image to the registry, and deploy the proxy to the created cluster.

When you make a change, you can deploy with

```bash
./scripts/cluster.sh deploy
```

When you no longer need it, run the command to delete the cluster and the registry
```bash
./scripts/cluster.sh down
```

### Testing

For unit tests, run the following command:
```bash
make test
```

For end-to-end tests, run the following command:
```bash
make e2e
```

The command uses the aforementioned script `cluster.sh` to make a deployment, and run the Ginkgo tests defined in the `test` directory against the cluster.

### CI

The CI workflow is defined in `.github/workflows/test.yml`. 

- When a PR is created, github action will trigger a job that verifies the versions of the APIs, build the container image and run the unit tests.


### CD

- When a commit is merged into the `main` branch, or a git tag is pushed, the GitHub Action `.github/workflows/container-ci.yml` will be triggered to build & push docker image to AWS ECR and GCP GCR.

- When a commit is merged into the `main` branch, or a git tag is pushed, the GitHub Action `.github/workflows/cd.yml` and `.github/workflows/release.yml` will be triggered to create PRs to bump the image tag in `infra-cd` and `aws-shared-cd` repos. Make sure they are merged.  

- If the git tag is `release-vX.Y.Z`, the image tag will be `vX.Y.Z`, otherwise it will be the git hash.