online-boutique

Java microservice via Golden Path

Overview

This service was scaffolded using the Java Golden Path template in Backstage. It provides:

• ✅ Production-ready Spring Boot 3.2 application
• ✅ Prometheus metrics integration
• ✅ Health checks and readiness probes
• ✅ Humanitec deployment orchestration
• ✅ GitOps-ready Kubernetes manifests
• ✅ CI/CD via GitHub Actions
• ✅ Grafana dashboard integration

Quick Start

Local Development

# Build and run locally
./mvnw spring-boot:run

# Or with Docker
docker build -t online-boutique:latest .
docker run -p 8080:8080 online-boutique:latest

Access the application:

• Application: http://localhost:8080
• Health: http://localhost:8080/actuator/health
• Metrics: http://localhost:8080/actuator/prometheus

Build

# Maven build
./mvnw clean package

# Output: target/online-boutique-1.0.0-SNAPSHOT.jar

Test

./mvnw test

Deployment

Humanitec (Primary)

Deployments are automatically triggered on push to main branch via GitHub Actions:

1. Build: Maven builds the JAR
2. Container: Docker image built and pushed to ACR
3. Deploy: Humanitec CLI deploys using score.yaml

View deployment status:

• Humanitec Console: https://app.humanitec.io/orgs/kyn-cjot/apps/online-boutique

ArgoCD (Fallback)

If Humanitec is unavailable, deploy via ArgoCD using manifests in deploy/:

kubectl apply -k deploy/

Monitoring

Grafana Dashboard

View real-time metrics:

• URL: https://grafana.kyndemo.live/d/spring-boot-dashboard?var-app=online-boutique

Metrics include:

• HTTP request rate and latency
• Error rates (4xx, 5xx)
• JVM memory and GC
• CPU usage
• Thread pools

Prometheus Metrics

Exposed at /actuator/prometheus:

• http_server_requests_seconds - Request metrics
• jvm_memory_used_bytes - Memory usage
• process_cpu_usage - CPU utilization

Health Checks

• Liveness: /actuator/health/liveness
• Readiness: /actuator/health/readiness
• Overall: /actuator/health

API Endpoints

Endpoint	Method	Description
/	GET	Welcome message
/api/status	GET	Service status
/actuator/health	GET	Health check
/actuator/prometheus	GET	Prometheus metrics
/actuator/info	GET	Application info

Configuration

Environment Variables

• SPRING_PROFILES_ACTIVE - Active profile (dev, staging, production)
• SERVER_PORT - HTTP port (default: 8080)

Profiles

• development: Local dev settings
• production: Production optimized settings

Architecture

┌─────────────────────────────────────────┐
│         GitHub Actions (CI/CD)          │
│  - Build with Maven                     │
│  - Push to ACR                          │
│  - Deploy via Humanitec                 │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Humanitec Orchestrator          │
│  - Interprets score.yaml                │
│  - Provisions resources                 │
│  - Deploys to AKS                       │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Azure AKS Cluster               │
│  - Running application pods             │
│  - Prometheus scraping metrics          │
│  - Ingress routing traffic              │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Grafana Dashboard               │
│  - Visualizing metrics                  │
│  - Alerting on issues                   │
└─────────────────────────────────────────┘

Development

Adding New Endpoints

Edit src/main/java/com/kyndryl/goldenpath/GoldenPathApplication.java:

@GetMapping("/api/hello")
public String hello() {
    return "Hello, World!";
}

Adding Custom Metrics

Inject MeterRegistry and create custom metrics:

@RestController
public class MyController {
    private final Counter myCounter;
    
    public MyController(MeterRegistry registry) {
        this.myCounter = Counter.builder("my_custom_counter")
            .tag("service", "online-boutique")
            .register(registry);
    }
    
    @GetMapping("/api/data")
    public String getData() {
        myCounter.increment();
        return "data";
    }
}

Database Integration

Add dependency in pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

Update score.yaml to provision PostgreSQL via Humanitec:

resources:
  database:
    type: postgres
    properties:
      version: "15"

Troubleshooting

Build Fails

# Clean and rebuild
./mvnw clean install

# Check dependencies
./mvnw dependency:tree

Metrics Not Showing

1. Verify endpoint: curl localhost:8080/actuator/prometheus
2. Check pod annotations in deploy/deployment.yaml
3. Verify Prometheus targets in Grafana

Deployment Fails

1. Check GitHub Actions logs
2. Review Humanitec deployment logs
3. Check pod status: kubectl get pods -n demo-apps

Links

• Repository: https://gitea.kyndemo.live/validate/online-boutique
• Humanitec: https://app.humanitec.io/orgs/kyn-cjot/apps/online-boutique
• Grafana: https://grafana.kyndemo.live/d/spring-boot-dashboard?var-app=online-boutique
• Backstage Catalog: https://backstage.kyndemo.live/catalog/default/component/online-boutique

Support

For issues or questions:

1. Check documentation in docs/
2. Review Backstage TechDocs
3. Contact Platform Engineering team