Template repository showing how to be a good Java Spring Boot citizen in a k8s cluster.
Below is a set of recommendations for being a good service. The recommendations are not tied to a specific language or framework.
- Configuration through environment variables.
- Expose readiness endpoint
- Expose endpoint that Prometheus can scrape
- Be stateless
- Support multiple instances
- Always be in a releasable state
- Automate build and deployment.
Some of above recommendations are heavily inspired by https://12factor.net/. It is recommended read https://12factor.net/ for more inspiration and further details. Some points go further than just being a good service and also touches areas like operations.
Run ./setup.sh GIT_REPOSITORY_NAME.
Above does a search/replace in relevant files.
The service is listening for connections on port 8080.
Spring boot actuator is listening for connections on port 8081. This is used as prometheus scrape endpoint and health monitoring.
Prometheus scrape endpoint: http://localhost:8081/actuator/prometheus
Health URL that can be used for readiness probe: http://localhost:8081/actuator/health
Documentation of the API is build as a separate Docker image. Documentation is build using Swagger. The documentation
image is post-fixed with -documentation. The file documentation/docker/compose/docker-compose.yml contains a setup
that starts both the service and documentation image. The documentation can be accessed at http://localhost/test
and the service can be called through the Swagger UI.
In the docker-compose setup is also an example on how to set custom endpoints for the Swagger documentation service.
| Environment variable | Description | Required |
|---|---|---|
| LOG_LEVEL | Log Level for applikation log. Defaults to INFO. | No |
| LOG_LEVEL_FRAMEWORK | Log level for framework. Defaults to INFO. | No |
| CORRELATION_ID | HTTP header to take correlation id from. Used to correlate log messages. Defaults to "x-request-id". | No |
| STS_URL_WSDL | URL for STS WSDL. | Yes |
| STS_TRUST_CERT | Pat h to STS signing certificate. |
Yes |
| STS_CLIENT_CERT | Path to STS Client certificate. | Yes |
| STS_CLIENT_KEY | Path to STS Client key. | Yes |
| VIDEOAPI_ENDPOINT | Video API endpoint | Yes |
| HEALTHCHECK_RATE | Rate of healthcheck in java.time.Duration compliant format. | Yes |
| SMS_ENDPOINT | SMS Api endpoint | Yes |
To run the service from your favourite IDE you can start the TestApplication class. This requires a Java Keystore named client.jks to be placed in the same folder as this file.
Below is the requirements to the JKS file.
- Password must be
Test1234 - It must contain client certificate and key.
- Client alias must be
client - It must contain the STS signing certificate.
After building the solution you can also run it with below docker command. Volume mappings etc. is just an example.
docker run --rm -p 8080:8080 -v /home/jonas/kit.crt:/kit.cer:ro -v /home/jonas/kit.key:/kit.key:ro -v /home/jonas/sts.cer:/sts.cer:ro -e STS_URL_WSDL=https://sts.vconf-stage.dk/sts/sts.wsdl -e VIDEOAPI_ENDPOINT=https://videoapi.vconf-stage.dk/videoapi -e STS_TRUST_CERT=/sts.cer -e STS_CLIENT_CERT=/kit.cer -e STS_CLIENT_KEY=/kit.key kvalitetsit/medcom-vdx-healthcheck:latest