- Introduction
- Requirements
- Installation
- Configuration
- Developer
This is a demo deployment of an API server which is an implementation of a jumble word algorithm.
FastAPI Python's framework was used for the creation of the API server and it has been prepared to be deployed to minikube
Kubernetes cluster by Helm chart.
The API consist of two endpoints:
/api/jumble?word=<word>
Query passed to the above endpoint (were the <word> is the actual word to be jumbled) will result in a jumbled word.
eg. /api/jumble?word=test
will return JSON object: {"jumbled_word":"etst"}
/api/audit
Accessing the above endpoint will return last 10 queries as JSON objects to the server including access path and the actual query (eg.{"url":"/api/audit","query":null}
).
eg.:
[...]
{"audit":{"log":{"level":"INFO","type":"access","timestamp":"2023-01-24 01:47:14,668","message":"GET /api/audit"},"req":{"url":"/api/audit","query":null},"res":{"statusCode":200,"body":{"statusCode":200,"status":"OK"}}}
[...]
Documentation for the used packages:
Configuration has been created and tested with the following packages:
python3 (v3.11)
docker (engine v20.10.23)
pip install fastapi
pip install "uvicorn[standard]"
pip install httpx
pip install pytest
helm (v3.11.0)
minikube (v1.28.0)
jq (v.1.6)
Application requires helm and minikube applications to be installed on the system for the deployment. jq is an additional package helping to pretty JSON output.
Once installed clone the application files from the git repository and use helm to deploy it to the minikube cluster.
git clone https://github.com/FrantzT/jumbleapi.git
# minikube
minikube start
# Helm chart deployment
cd jumbleapi
cd helm/jumbleapi
helm install jumbleapi .
# Verify instalation
helm ls
To verify successful installation test the endpoints with the following commands:
# retrive the service URL for jumbleapi service
MINIKUBE_SVC_URL=$(minikube service jumbleapi --url)
# test for endpoint /api/jumble/
curl $MINIKUBE_SVC_URL/api/jumble/?word=test -H "Accept: application/json" | jq .
{
"jumbled_word": "tets"
}
# test for endpoint /api/audit
curl $MINIKUBE_SVC_URL/api/audit -H "Accept: application/json" | jq .
[
{
"audit": {
"log": {
"level": "INFO",
"type": "access",
"timestamp": "2023-01-24 01:47:07,734",
"message": "GET /api/audit"
},
"req": {
"url": "/api/audit",
"query": null
},
"res": {
"statusCode": 200,
"body": {
"statusCode": 200,
"status": "OK"
}
}
}
}
[...]
]
cd jumbleapi/test
# execute
pytest
pytest will run set of 4 tests checking the connectivity and server response.
Development requires installation of the packages (paragraph Requirements of this document) as well as installation of applications required for the JumbleAPI server itself (previous paragraph).
Docker is an additional required package.
Once the packages have been installed clone the application files from the git repository.
git clone https://github.com/FrantzT/jumbleapi.git
cd jumbleapi
$ tree
.
├── Dockerfile
├── README.md
├── app
│ ├── __init__.py
│ ├── audit_logger.py
│ ├── audit_logger_formatter.py
│ ├── favicon.ico
│ └── main.py
├── helm
│ └── jumbleapi
│ ├── Chart.yaml
│ ├── templates
│ │ ├── NOTES.txt
│ │ ├── _helpers.tpl
│ │ ├── deployment.yaml
│ │ ├── service.yaml
│ │ └── serviceaccount.yaml
│ └── values.yaml
├── log
│ └── audit.log
├── requirements.txt
└── test
├── __init__.py
├── log
│ └── audit.log
└── test_main.py
app/
app/main.py
Main module of the application containing core functions.
app/audit_logger.py
Module containing functions responsible for managing log file and stream.
app/audit_logger_formatter.py
Module containing functions responsible for formating the JSON output for the log objects.
helm/
helm/templates/deployment.yaml
Helm chart template containing definitions of the deployment variables.
helm/templates/service.yaml
Helm chart template containing definitions of the service variables.
helm/values.yaml
Default values for the chart deployment.
test/test_main.py
pytest test units
All the necessary development and test of the application can be performed in your local python environment (preferably python venv). You can start the local server locally and it will deliver your changes instantly to the endpoints.
cd jumbleapi
# run the uvicorn server in the --reload development mode
# to instantly apply your code changes to the application
uvicorn app.main:app --reload
The server API document tools (openapi) can be accessed in the browse at the URL:
http://127.0.0.1:8000/docs
After the code changes has been completed create Docker image and push it to the docker repository. The Dockerfile file consists instructions for the docker image build. All aditional packages required durning development need to be added to the requirments.txt file or specifed in the Dockerfile itself.
cd jumbleapi # location of the Dockerfile build instructions file
docker build -t jumbleapi .
docker tag jumbleapi <repository>/<application_name>:<tag>
docker login # connect to the repository
docker push <repository>/<application_name>:<tag>
Once the images have been created
and successfully delivered follow instructions from the paragraph
Installation > Jumbled API server > Prerequisite
to test your changes.
The configuration is a basic framework and as such has simplified structure. There are some matters needed to be explained.
The setup uses a file to collect logs for the audit.
The file itself is located in directory jumbleapi/log/audit.log
The minikube
provides a mount point for the cluster node
and allow pods to mount it as Directory and share the file access between them.
The volume configuration is hardcoded within the file
jumbleapi/helm/jumbleapi/templates/deployment.yaml
. Keep that in mind in case you would like to move it to a different location.
As such the method of storage is insecure and should not be used in the production environment.
It is set up this way just for the ease of test within local environment.
[...]
volumeMounts:
- name: audit-log
mountPath: /code/log
[...]
volumes:
- name: audit-log
hostPath:
path: /data
type: Directory
[...]
The minikube
deployment has default value of the replicaCount: 2
.
You can increase and decrease the value depending on your scalability needs.
repository: pawelzaatdocker/jumbleapi
is a hardcoded value for the v1.0.1 of the application.
Please contact me would you have any questions or comments.