sample-spring-microservices-kubernetes shows Spring Cloud wired to a local cluster

A demo project, not a framework

The repository description calls it a sample Spring Boot application that uses some features provided by Spring Cloud Kubernetes, Spring Cloud OpenFeign and Spring Cloud Gateway, deployed on Kubernetes. The README is more precise about the intent. The author says the project demonstrates the most interesting features of the Spring Cloud Project for building microservice-based architecture deployed on Kubernetes, and that all the samples may be easily deployed on a local Kubernetes single-node cluster, Minikube. The audience is therefore someone learning the integration points, not someone shipping a system. The homepage is piotrminkowski.com, and the author also links to a book, Hands-On Java with Kubernetes, sold through Leanpub, which suggests the project is the companion code for a longer course on the subject. There is no licence recorded in the repository metadata, which is worth noting if you plan to lift code from it rather than read it.

The modules and how they call each other

The architecture is five Spring Boot modules. The gateway-service uses Spring Cloud Netflix Zuul and acts as a proxy or gateway in the architecture. The employee-service performs CRUD operations on a Mongo repository of employees. The department-service does the same for departments, and it communicates with employee-service. The organization-service is the third microservice, with CRUD on a Mongo repository of organizations, and it communicates with both employee-service and department-service. The admin-service embeds a Spring Boot Admin Server used for monitoring the Spring Boot microservices running on Kubernetes. So the call graph is a small tree: the gateway fronts everything, and the organisation service is the one that reaches into the other two. The repository layout mirrors that exactly, with a top-level directory per module plus the shared pom.xml, a k8s directory, a skaffold.yaml and renovate.json.

Running it: Minikube, Maven, Docker, kubectl

The usage section is a five-step sequence, and it is worth following in order because each step depends on the last.

minikube start --vm-driver=virtualbox --memory='4000mb'
mvn clean install
docker build -t piomin/employee:1.1 .
kubectl get pods

The Minikube command starts a single-node cluster with 4GB of memory. The Maven command builds the project, and the Docker command builds one image per module, the example given being the employee service tagged 1.1. Then you change into the kubernetes directory in the repository, apply the templates with kubectl apply, and check the result with kubectl get pods. The README also mentions that you can easily deploy all applications using the skaffold dev command, and the repository carries a skaffold.yaml, so there is a live-reload path for people who would rather not rebuild images by hand.

The k8s directory and what must be applied first

Before the applications run, the README says to go to the k8s directory, where you will find several YAML scripts you need to apply before running the applications, and to apply those scripts using kubectl apply. Four are named. privileges.yaml holds the Role and RoleBinding that allow Spring Cloud Kubernetes to access the Kubernetes API from a pod, which is the piece that makes service discovery and ConfigMap injection work at all. mongo-secret.yaml holds credentials for MongoDB, and mongo-configmap.yaml holds the user for MongoDB. mongo-deployment.yaml is the Deployment for MongoDB itself. The separation of secret and configmap for what is conceptually the same database credential is a small but instructive detail, since it maps onto how Kubernetes expects sensitive and non-sensitive data to be delivered to a pod. The services in this sample store their state in MongoDB rather than in a relational database, and the manifests here are what stand up that database inside the cluster.

Three branches, three articles, three levels of Kubernetes integration

The examples are divided into branches and each is described in a separate article on the author's blog, which is the clearest way to understand the progression. The master branch is the base example, using Spring Boot and Spring Cloud to build microservices that can be deployed on Kubernetes, described in the article Quick Guide to Microservices with Kubernetes, Spring Boot 2.0 and Docker. The hybrid branch is an introduction to the Spring Cloud Kubernetes project itself, showing features such as discovery across many namespaces and Spring Boot property sources based on ConfigMap and Secret, described in Microservices with Spring Cloud Kubernetes. The master branch also carries a third example, Spring Boot Admin on Kubernetes, which uses Spring Boot Admin to monitor Spring Boot applications running on Kubernetes. The repository topics confirm the direction of travel: configmap, docker, kubernetes, microservices, minikube, openshift, ribbon, spring-boot, spring-cloud, spring-cloud-kubernetes, swagger2 and zuul. Discovery across namespaces is the genuinely interesting part, since it uses the Spring Cloud Kubernetes DiscoveryClient and Ribbon for inter-service communication, and it is the piece that a simple Eureka-based setup does not give you.

Where this sample is the wrong thing to copy

The honest problem is the vintage of the stack. The gateway is Spring Cloud Netflix Zuul, and Zuul has been in maintenance for years with no announced successor in the same project, and the client-side load balancing is Ribbon, which is likewise no longer where the Spring Cloud load balancing work lives. The repository description mentions Spring Cloud Gateway and Spring Cloud OpenFeign, so the branches have been updated over time to use them, but the module descriptions still describe Zuul, and the topics list still carries zuul and ribbon, so the codebase is a mix of generations. A second limit is that everything runs against MongoDB with no transaction boundaries, no schema, and no concern about how three services coordinating reads look when one of them is unavailable, so the sample is a demonstration of routing and configuration rather than of distributed data design. The third limit is the Minikube dependency. The whole thing assumes a local cluster with 4GB of memory allocated to a virtual machine driver, which is fine for a laptop and irrelevant on a managed cluster. The project is MIT unlisted in metadata, has no GitHub releases, and the last push was on 2026-10-14, so treat it as a living tutorial rather than a maintained product.

Editorial conclusion

Adopt this repository as a teaching reference if you want a small Spring Cloud system you can deploy to Minikube in one sitting, especially since each branch is paired with an article explaining it. Skip it as a starting point for production work, because the gateway is Spring Cloud Netflix Zuul and the load balancer is Ribbon, both of which are well past their supported life. Before you copy anything, check which Spring Cloud release the branch you are looking at was written against.

Frequently asked questions

Official sources

1. Issues
2. piomin/sample-spring-microservices-kubernetes on GitHub
3. Project website
4. README