Release v0.5.1

.github/workflows/validate-pr.yaml

@@ -25,9 +25,9 @@ jobs:
       - name: Run golangci-lint
         uses: golangci/golangci-lint-action@v8
         with:
+          version: v2.6.2
           only-new-issues: true
           args: --whole-files
-          version: v2.1
 
   call-unit-tests:
     name: Go Unit tests

CLAUDE.md

@@ -0,0 +1,188 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+**ClusterIQ** is an inventory and cost estimation platform for OpenShift clusters across multi-cloud environments (currently AWS only). It provides automated discovery, cost tracking, and lifecycle management.
+
+**Architecture Components:**
+1. **Scanner**: CronJob that discovers cloud resources using "Stocker" pattern
+2. **API Server**: REST API (Gin framework) for inventory queries and cluster operations
+3. **Agent**: gRPC service handling cluster power operations (instant, scheduled, recurring)
+
+**Repository Structure:**
+```
+cmd/                    # Application entry points (api, scanner, agent)
+internal/
+  ├── actions/          # Action system (instant, scheduled, cron)
+  ├── cloud_providers/  # AWS, GCP, Azure abstractions
+  ├── cloud_executors/  # Action execution
+  ├── stocker/          # Resource discovery
+  ├── repositories/     # Data access layer
+  ├── services/         # Business logic
+  ├── api/handlers/     # HTTP handlers
+  └── models/           # DTO, DB, domain models
+db/sql/                 # Schema definitions (init.sql, cron.sql)
+test/integration/       # Integration tests
+```
+
+## Essential Commands
+
+**CRITICAL**: Always use Makefile. Never use direct `go build`, `go test`, or `go run`.
+This includes compilation checks after code changes — use `make local-build` instead of `go build ./...`.
+
+```bash
+# Development
+make check-dependencies  # Check before building
+make all                # Stop, build, start dev environment
+make start-dev          # Start services
+make stop-dev           # Stop services
+
+# Building
+make build              # All container images
+make local-build        # All local binaries
+
+# Testing
+make go-unit-tests
+make go-integration-tests
+make go-tests           # All tests
+make lint               # Lint entire project
+make lint-staged        # Lint staged files only
+
+# Code Generation
+make generate-converters  # Goverter (DB to DTO)
+make swagger-doc         # OpenAPI docs
+```
+
+## Architecture Patterns
+
+**Layered Architecture:**
+- Handlers → Services → Repositories → Database
+- Each layer has interfaces for testability
+- Repository returns `repositories.ErrNotFound` for missing resources
+- Repository returns `repositories.ErrNoClustersInAccount` when an account exists but has no clusters
+- Services wrap all errors with `fmt.Errorf` context before returning to handlers
+- Handlers map errors to HTTP status codes (404, 400, 500)
+
+**Key Patterns:**
+- **Repository Pattern**: Data access abstraction
+- **Service Layer**: Business logic with dependency injection
+- **Stocker Pattern**: Cloud resource discovery via `MakeStock()`
+- **Action Channel**: Unbuffered channel for decoupled action dispatch
+- **Event Tracker**: Audit logging with `EventService.StartTracking()`
+- **Functional Options**: AWS connections use `WithEC2()`, `WithRoute53()`, etc.
+
+## Testing Guidelines
+
+**Service Layer Mocking:**
+```go
+// Mock repositories with function pointers
+type mockClusterRepository struct {
+    getClusterByIDFn func(ctx context.Context, clusterID string) (*db.ClusterDBResponse, error)
+}
+
+func (m *mockClusterRepository) GetClusterByID(ctx context.Context, clusterID string) (*db.ClusterDBResponse, error) {
+    if m.getClusterByIDFn != nil {
+        return m.getClusterByIDFn(ctx, clusterID)
+    }
+    return nil, nil
+}
+```
+
+**gRPC Mocking:**
+- Mock the underlying `pb.AgentServiceClient` interface, not the wrapper
+- Return actual Go errors: `return nil, errTest`
+- DON'T use response error codes for Go errors: `&pb.Response{Error: 1}` returns `nil` error
+
+**Test Organization:**
+- Group by method: `TestServiceName_MethodName(t *testing.T)`
+- Use sub-tests: `t.Run("success", func(t *testing.T) { ... })`
+- Naming: `testServiceName_MethodName_Scenario`
+- All interface methods must be implemented in mocks (even if unused)
+
+**Coverage Analysis:**
+```bash
+go test -coverprofile=coverage.out ./internal/services/...
+go tool cover -func=coverage.out | grep -v "100.0%"  # Find uncovered
+go tool cover -html=coverage.out -o coverage.html    # Visual
+```
+
+## Development Workflow
+
+1. Make code changes
+2. Run `make lint-staged` before committing
+3. Run relevant tests: `make go-unit-tests`
+4. For API changes: update Swagger with `make swagger-doc`
+5. For DB changes: update `db/sql/init.sql` or add data migration in `doc/releases/`
+6. For protobuf changes: `make local-build-agent`
+7. For goverter changes: `make generate-converters`
+
+**Commit Convention:**
+- Use conventional commits format: `type(scope): brief description`
+- Keep messages to single line
+- Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+- Examples:
+  - `feat(api): implement PATCH endpoint for accounts`
+  - `fix(aws): continue processing instances on conversion error`
+  - `test(dto): add error handling tests for converters`
+
+## Critical Implementation Notes
+
+**Cloud Support:**
+- AWS: Fully implemented ✅
+- GCP/Azure: Interface stubs only ❌
+
+**Data Consistency:**
+- Each repository method = separate transaction
+- No distributed transactions
+- Eventual consistency for action status updates
+
+**PATCH Endpoints:**
+- Use pointer fields in DTOs to distinguish null from empty
+- Dynamic SQL query building with positional parameters
+- Verify resource exists before updating
+- Refresh materialized views after successful update
+- Return updated resource with HTTP 200
+
+## Configuration
+
+Environment variables:
+- `CIQ_AGENT_URL` - Agent gRPC endpoint (default: "agent:50051")
+- `CIQ_API_URL` - API endpoint used by Scanner and Agent (not by the API server itself)
+- `CIQ_DB_URL` - PostgreSQL connection (default: "postgresql://pgsql:5432/clusteriq")
+- `CIQ_CREDS_FILE` - Cloud provider credentials file
+- `CIQ_LOG_LEVEL` - Log verbosity (default: "INFO")
+
+## AWS Integration Details
+
+**Cluster Discovery:**
+- OpenShift tags: `kubernetes.io/cluster/<cluster-name>-<infraID>`
+- Console URLs via Route53 DNS: `console-openshift-console.apps.*`
+
+**Instance Timestamps:**
+- Primary: Root EBS volume `AttachTime` (via `instance.RootDeviceName`)
+- Fallback: Instance `LaunchTime`
+- NEVER hardcode device names (varies by instance type)
+
+**Cost Explorer:**
+- 14-day rolling window, DAILY granularity
+- Metric: UnblendedCost
+- One Expense object per instance per day
+
+**EC2 Operations:**
+- Start: Only targets `stopped` instances
+- Stop: Only targets `running` instances
+- Prevents idempotency errors
+
+## Code Generation
+
+**Goverter**: Type-safe DB ↔ DTO converters
+- Definitions: `internal/models/convert/`
+- Generated: `internal/models/convert/generated.go`
+
+**Swagger**: OpenAPI from Go comments
+- Annotations in handlers and `cmd/api/server.go`
+
+**Protobuf**: gRPC code from `cmd/agent/proto/agent.proto`
+- Auto-generated during `make local-build-agent`

README.md

@@ -45,6 +45,11 @@ available for every cloud provider:
 The following graph shows the architecture of this project:
 ![ClusterIQ architecture diagram](./doc/architecture.png)
 
+### Secrets Management (Optional)
+
+By default, Cluster IQ uses standard Kubernetes Secrets. For production environments, you can integrate with HashiCorp Vault.
+See [Vault Integration Guide](doc/vault/README.md) for detailed setup instructions.
+
 ## Installation
 ClusterIQ was designed to run in K8s/Openshift platforms, but it can also run in
 local using `podman-compose`.
@@ -152,7 +157,7 @@ For deploying ClusterIQ in local for development purposes, check the following
 
 ## DB Backup
 For backing up or restoring the ClusterIQ database, check the following
-[document](./doc/db-backup.md)
+[document](./doc/developers/db-backup.md)
 This document also describes how to manage data migration when a new release of
 ClusterIQ changes DB data structure.
 
@@ -165,8 +170,7 @@ Available configuration via Env Vars:
 | CIQ_AGENT_POLLING_SECONDS_INTERVAL   | integer (Default: 30)                                 | ClusterIQ Agent polling time (seconds)    |
 | CIQ_AGENT_URL                        | string (Default: "agent:50051")                       | ClusterIQ Agent listen URL                |
 | CIQ_API_LISTEN_URL                   | string (Default: "0.0.0.0:8080")                      | ClusterIQ API listen URL                  |
-| CIQ_API_URL                          | string (Default: "")                                  | ClusterIQ API public endpoint             |
-| CIQ_AGENT_LISTEN_URL                 | string (Default: "0.0.0.0:50051")                     | ClusterIQ Agent listen URL                |
+| CIQ_API_URL                          | string (Default: "")                                  | ClusterIQ API endpoint (used by Scanner)  |
 | CIQ_DB_URL                           | string (Default: "postgresql://pgsql:5432/clusteriq") | ClusterIQ DB URL                          |
 | CIQ_CREDS_FILE                       | string (Default: "")                                  | Cloud providers accounts credentials file |
 | CIQ_LOG_LEVEL                        | string (Default: "INFO")                              | ClusterIQ Logs verbosity mode             |

cmd/agent/agent.go

@@ -106,14 +106,13 @@ func NewAgent(cfg *config.AgentConfig, logger *zap.Logger) (*Agent, error) {
 
 // StartAgentServices starts every AgentService on a separate thread(go-routine)
 func (a *Agent) StartAgentServices() error {
-	var err error
 	errChan := make(chan error, AgentServicesCount)
 
 	// Starting InstantAgentService
 	a.wg.Add(1)
 	go func() {
 		defer a.wg.Done()
-		if err = a.ias.Start(); err != nil {
+		if err := a.ias.Start(); err != nil {
 			errChan <- fmt.Errorf("instant AgentService (gRPC) failed: %w", err)
 			return
 		}
@@ -124,7 +123,7 @@ func (a *Agent) StartAgentServices() error {
 	a.wg.Add(1)
 	go func() {
 		defer a.wg.Done()
-		if err = a.sas.Start(); err != nil {
+		if err := a.sas.Start(); err != nil {
 			errChan <- fmt.Errorf("scheduled Agent Service failed: %w", err)
 			return
 		}
@@ -135,7 +134,7 @@ func (a *Agent) StartAgentServices() error {
 	a.wg.Add(1)
 	go func() {
 		defer a.wg.Done()
-		if err = a.eas.Start(); err != nil {
+		if err := a.eas.Start(); err != nil {
 			errChan <- fmt.Errorf("executor Agent Service failed: %w", err)
 			return
 		}
@@ -221,7 +220,16 @@ func (a Agent) signalHandler(signal os.Signal) error {
 		a.logger.Warn("Shutting down server...", zap.String("signal", signal.String()))
 	}
 
-	for _, item := range a.sas.schedule {
+	// Copy schedule map under lock to avoid race condition during iteration
+	a.sas.mutex.Lock()
+	scheduleCopy := make(map[string]scheduleItem, len(a.sas.schedule))
+	for k, v := range a.sas.schedule {
+		scheduleCopy[k] = v
+	}
+	a.sas.mutex.Unlock()
+
+	// Iterate over the copy (without holding lock) to cancel all scheduled actions
+	for _, item := range scheduleCopy {
 		cancel := item.cancel
 		action := item.action
 		a.logger.Warn("Cancelling ScheduledAction", zap.String("action_id", action.GetID()))