k8s API Proxy

A Basic Go API that provides an Interface to Kubernetes API with a limited set of actions

Overview, Design and Architecture

API Specification

---

Purpose: Health Check to verify connectivity to the k8s API server. This endpoint essentially proxies the /healthz endpoint of the k8s API server, with the addition of a status field in the response body, which will be ok if the API server is healthy.
Method: GET
Path: /healthz
Example Response:

{
  "status": "ok",
}

---

Purpose: List available deployments in the cluster (and if specified- in the given namespace) Method: GET
Path: /deployments?namespace={namespace}
Query Params:

• namespace (optional). If not specified, will return all deployments in the cluster. If specified, will return all deployments in the given namespace.

Example Response:

[
  {
    "name": "foo",
    "namespace": "default",
  },
  {
    "name": "bar",
    "namespace": "baz",
  }
]

---

Purpose: Get the number of replicas for a given deployment
Method: GET
Path: /deployments/{namespace}/{deployment}/replicas
Example Response:

{
  "deployment": "foo",
  "namespace": "default",
  "replicas": 3
}

---

Purpose: Set the number of replicas for a given deployment
Method: PUT
Path: /deployments/{namespace}/{deployment}/replicas
Body:

{
  "replicas": 3
}

Example Response:

{
  "deployment": "foo",
  "namespace": "default",
  "replicas": 3
}

---

Security

The API server is secured using TLS and supports mTLS authentication. By default, the API server will use a self-signed certificate, but it is possible to provide a custom certificate and key.

Development / Build / Deploy / Test

Prerequisites

• Go
• Docker
• Helm
• Kubectl with a configured context and access to a k8s cluster
• OpenSSL (optional, for generating a self-signed certificate)

Primary Makefile Targets

build

Build the API server binary. Will be stored in the bin directory as api.

run

Run the API server locally. This will use the kubeconfig file that is stored in the ~/.kube/config directory by default (can be overridden through the $KUBECONFIG variable). Make sure to follow the instructions in the config/README.md file for more details.

generate-certs

Generate the self-signed set of certificates for the API server (CA, server, client). The certificates will be stored in a local directory, from which the Helm chart will read them. Note that by default, the CN (Canonical Name) of the certificates will be MyCA for the CA, and localhost for the client/server certs, but they can be overridden by setting the CA_CN, SERVER_CN and CLIENT_CN environment variables. For example:

CA_CN=ca.foo SERVER_CN=my.server.com CLIENT_CN=my.client.com make generate-certs

IMPORTANT: Make sure NOT to modify the original path (/certs relative to the root directory) for two main reasons:

1. The go binary (when running locally) will look for the certificates in that path if using the Makefile target run
2. The .gitignore file will ignore that path, so that the certificates will not be committed to the repository

docker-build-push

Build the docker image for the API server.

NOTE: IMG environment variable should be set for this target, i.e. registry/repo:tag.

deploy

Deploy the Helm chart to the cluster. Make sure to follow the Helm Chart's values.yaml file for the configuration. Most importantly- populate the base64 encoded certificates and keys in the values.yaml file. You can use the Makefile target generate-certs to generate the certificates and keys, and then use the base64 command to encode them. For example (on macOS)):

make generate-certs
base64 -i certs/ca.crt | pbcopy

Then paste the output into mTLS.caCert field in the values.yaml file. Repeat the process for server.crt and server.key into mTLS.serverCert and mTLS.serverKey fields respectively.

undeploy

Uninstall the Helm chart from the cluster including the release name and namespace.

test

Run the unit tests

ci

Run the CI tests (unit tests, linting, etc.)

Accessing the API

Networking / Ingress

From a networking standpoint, you can either use an Ingress Controller (Ingress Resource can be generated by the Helm chart, see ingress stanza in the values.yaml for more details), or use kubectl port-forward to forward the API server port to your local machine. You can follow these instructions for more info. You may also see the below example for a quick start. This will forward the API server port to your local machine on port 8443:

kubectl -n <namespace> port-forward svc/k8s-api-proxy 8443:443