Deploy Spring Cloud Kubernetes Microservices on Minikube – A Step‑by‑Step Guide

1. Overview

When building microservice solutions, Spring Cloud and Kubernetes are top choices. If Kubernetes is used as the primary container manager, Spring Cloud features can still be accessed via the Spring Cloud Kubernetes project, which integrates Spring Boot applications seamlessly with Kubernetes. This tutorial shows how to deploy a Spring Boot application on a local Minikube cluster.

Install Minikube on the local machine.

Develop a sample microservice architecture where two independent Spring Boot applications communicate via REST.

Set up the applications on a single‑node Minikube cluster.

Deploy the applications using YAML configuration files.

2. Scenario

The example simulates a travel agency offering various deals to customers who query the service. It demonstrates service discovery, configuration management, and load balancing using Spring Cloud Kubernetes.

3. Environment Setup

Install Minikube with a VirtualBox driver and switch the kubectl context to the Minikube cluster.

minikube start --vm-driver=virtualbox

kubectl config use-context minikube

minikube dashboard

3.1 Deployment

Clone the example repository and build the Docker images inside Minikube.

# Build the repository
mvn clean install
# Set Docker environment
eval $(minikube docker-env)
# Build Docker images
cd travel-agency-service && docker build -t travel-agency-service .
cd ../travel-client-service && docker build -t travel-client-service .

4. Service Discovery

Spring Cloud Kubernetes provides a ServiceDiscovery implementation that exposes Kubernetes services as a set of endpoints. Adding the spring-cloud-starter-kubernetes dependency enables automatic discovery and client‑side load balancing.

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-kubernetes</artifactId>
</dependency>

Annotate the application with @EnableDiscoveryClient and inject DiscoveryClient into the controller.

@SpringBootApplication
@EnableDiscoveryClient
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
public class ClientController {
    @Autowired
    private DiscoveryClient discoveryClient;
}

5. ConfigMaps

Use Kubernetes ConfigMaps for non‑sensitive configuration. Create a client-config.yaml ConfigMap that matches the Spring Boot application name and apply it.

apiVersion: v1
kind: ConfigMap
metadata:
  name: client-service

data:
  application.properties: |
    bean.message=Testing reload! Message from backend is: %s Services: %s

kubectl create -f client-config.yaml

Bind the ConfigMap to the client service using @Configuration and @ConfigurationProperties.

@Configuration
@ConfigurationProperties(prefix="bean")
public class ClientConfig {
    private String message = "Message from backend is: %s <br/> Services : %s";
    // getters and setters
}

6. Secrets

Create a Kubernetes Secret to store MongoDB credentials, apply it, and reference it in the deployment.

apiVersion: v1
kind: Secret
metadata:
  name: db-secret

data:
  username: dXNlcg==
  password: cDQ1NXcwcmQ=

kubectl apply -f db-secret.yaml

Define a MongoDB Deployment that consumes the secret values as environment variables.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mongo
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: mongo
        image: mongo:latest
        env:
        - name: MONGO_INITDB_ROOT_USERNAME
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: username
        - name: MONGO_INITDB_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: password

Configure the travel‑agency service to read the username and password from the secret.

spring.cloud.kubernetes.secrets.name=db-secret
spring.data.mongodb.host=mongodb-service
spring.data.mongodb.port=27017
spring.data.mongodb.database=admin
spring.data.mongodb.username=${MONGO_USERNAME}
spring.data.mongodb.password=${MONGO_PASSWORD}

7. Ribbon Communication

Add the spring-cloud-starter-kubernetes-ribbon dependency and annotate the client with @RibbonClient(name="travel-agency-service"). Enable the Ribbon client in application.properties. ribbon.http.client.enabled=true Use RestTemplate to call the travel‑agency service, with a fallback method defined via Hystrix.

8. Additional Features

8.1 Hystrix

Enable circuit breaking with @EnableCircuitBreaker and annotate methods with @HystrixCommand specifying a fallback.

@HystrixCommand(fallbackMethod="getFallbackName", commandProperties={@HystrixProperty(name="execution.isolation.thread.timeoutInMilliseconds", value="1000")})
public String getDeals() { ... }

private String getFallbackName() { return "Fallback"; }

8.2 Health Checks

Expose Kubernetes health information via Spring Boot Actuator and the Spring Cloud Kubernetes health indicator, which provides pod name, IP, namespace, service account, node name, and a flag indicating whether the application runs inside Kubernetes.

9. Conclusion

The article provides a comprehensive overview of the Spring Cloud Kubernetes project, demonstrating how to combine Kubernetes as a microservice platform with Spring Cloud features such as service discovery, configuration, load balancing, circuit breaking, and health monitoring.