initial commit
Change-Id: I9c68c43e939d2c1a3b95a68b71ecc5ba861a4df5
This commit is contained in:
Scaffolder
252
README.md
Normal file
252
README.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Maven build
|
||||
./mvnw clean package
|
||||
|
||||
# Output: target/online-boutique-1.0.0-SNAPSHOT.jar
|
||||
```
|
||||
|
||||
### Test
|
||||
|
||||
```bash
|
||||
./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/`:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```java
|
||||
@GetMapping("/api/hello")
|
||||
public String hello() {
|
||||
return "Hello, World!";
|
||||
}
|
||||
```
|
||||
|
||||
### Adding Custom Metrics
|
||||
|
||||
Inject `MeterRegistry` and create custom metrics:
|
||||
|
||||
```java
|
||||
@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`:
|
||||
|
||||
```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:
|
||||
|
||||
```yaml
|
||||
resources:
|
||||
database:
|
||||
type: postgres
|
||||
properties:
|
||||
version: "15"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user