Example API service in Go

This is an example of an API service application written in Go. The application uses Gin for the REST API framework.

The application designed keeping in mind the 12-factor app principles.

Docker image

The application is available as a Docker image on Docker Hub. To build one locally, clone the repository and run make command:

make image

Deployment

This application us deployable to Kubernetes cluster using Pulumi IaaC (Infrastructure as Code). To deploy the application using Pulumi, you need to have Pulumi installed on your machine.

After installing Pulumi, run the following commands to deploy the application:

pulumi up --stack dev --config "api:kube-context=kubernetes-admin@kubernetes"

Use the --config flag and specify the Kubernetes context to use for deployment.

The kubernetes-admin@kubernetes default k8s context which is used in the above command is deploying the application to the Kubernetes cluster running in raspberry pi configured using ansible script @binodluitel/rpi-ansible.

Run using Docker

If you wish to run using Docker, you can do that too. Simply docker run the image.

docker run bluitel/api:latest
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)
[GIN-debug] Listening and serving HTTP on :8080
{"level":"info","ts":1719970919.3356018,"caller":"api/main.go:32","msg":" ----- Welcome to the API service example ----- "}
{"level":"debug","ts":1719970919.3363056,"caller":"api/main.go:39","msg":"Application build information","name":"api-service","version":"5ce1db0","build_time":"2024-07-02T23:16:14Z","ref_name":"main","ref_sha":"5ce1db0d5d6ab557ed35756f53edba06ebe137fd"}
[GIN-debug] Listening and serving HTTP on :9090

Metrics

The application exposes metrics on /metrics endpoint. The metrics are exposed in Prometheus format.

$ curl -s http://127.0.0.1:9090/metrics

418 (I'm a teapot)

Currently, all REST verbs for / (Base) URL returns 418 (I'm a teapot) status code with no content because base route does not have any implementation and is not intended to be used.

$ curl -s -v http://127.0.0.1:8080
*   Trying 127.0.0.1:8080...
* Connected to 127.0.0.1 (127.0.0.1) port 8080
> GET / HTTP/1.1
> Host: 127.0.0.1:8080
> User-Agent: curl/8.6.0
> Accept: */*
>
< HTTP/1.1 418 I'm a teapot
< Date: Mon, 01 Jul 2024 18:12:30 GMT
< Content-Length: 0
<
* Connection #0 to host 127.0.0.1 left intact

API Endpoints

The application has the following REST API endpoints:

• GET v1/pods/:pod_name/logs?follow=false - Gets or stream (set follow=true) logs from the k8s pod(s)
• GET/POST/PATCH/DELETE v1/users - CRUD operations for users are placeholders and does not have any implementation yet

Port Forwarding

To access the application running in the Kubernetes cluster, you can use port forwarding since/if there is no Ingress or LoadBalancer configured.

Application API is exposed on port 8080.

kubectl port-forward --namespace api svc/api 8080

Application metrics are exposed on port 9090.

kubectl port-forward --namespace api svc/api 9090