gitea_admin/propertysettings-v2-chart
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
propertysettings-v2-chart/CLAUDE.md
Vaibhav Pathak 36648be466 helm chart added
2026-01-05 11:55:00 +05:30

16 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains a Helm chart for deploying the Property Settings Service V2 on Kubernetes. The chart name is property-settings-svc-v2-chart and follows standard Helm chart structure and conventions.

Application Details:

  • Java/Tomcat-based service
  • Docker Image: localhost:5001/prj-onlinesales-prod-01/os-docker-images/onlinesales/prod/services/java/propertysettingssvcv2:1752740345878
  • Service Port: 8080
  • Context Path: /propertySettingsSvcV2
  • Database: MySQL 5.7 (bundled or external)
  • Source Code: /Volumes/Os/onlinesales/infrastructure/apps/propertySettingsSvcV2/release_kubernetes_2.0

Helm Chart Commands

Update dependencies (required before first install)

cd ./property-settings-svc-v2-chart
helm dependency update
cd ..

Install the chart

helm install <release-name> ./property-settings-svc-v2-chart

Install with custom values

helm install <release-name> ./property-settings-svc-v2-chart -f custom-values.yaml

Upgrade an existing release

helm upgrade <release-name> ./property-settings-svc-v2-chart

Dry run to preview rendered templates

helm install <release-name> ./property-settings-svc-v2-chart --dry-run --debug

Lint the chart

helm lint ./property-settings-svc-v2-chart

Package the chart

helm package ./property-settings-svc-v2-chart

Uninstall a release

helm uninstall <release-name>

Template rendering (output YAML without deploying)

helm template <release-name> ./property-settings-svc-v2-chart

Architecture

Chart Structure

property-settings-svc-v2-chart/
├── Chart.yaml              # Chart metadata with MySQL dependency
├── values.yaml             # Default configuration values
├── sql/                    # SQL migration scripts (5 files)
│   ├── 000_create_property_settings_db.sql      # Creates database
│   ├── 001_properties_table.sql                 # Creates tables & triggers
│   ├── 002_populate_properties_table.sql        # V1→V2 migration (unused)
│   ├── 003_alter_column_property_value.sql      # Alters column type
│   └── 004_property_settings_db_v2.sql          # Complete dump with data (79KB)
├── charts/                 # Dependent charts (MySQL)
│   └── mysql-*.tgz        # WSO2 MySQL chart
└── templates/
    ├── _helpers.tpl                     # Template helpers and named templates
    ├── _db-helpers.tpl                  # Database connection helpers
    ├── deployment.yaml                  # Main application deployment
    ├── service.yaml                     # Kubernetes service (ClusterIP on port 8080)
    ├── serviceaccount.yaml              # Service account configuration
    ├── configmap.yaml                   # Application configuration files
    ├── configmap-sql-migrations.yaml    # ConfigMap with SQL files (auto-loaded)
    ├── job-dbinit.yaml                  # Database initialization Job (Helm hook)
    ├── secret.yaml                      # Database configuration (Hibernate with dynamic DB config)
    ├── ingress.yaml                     # Optional Ingress resource
    ├── httproute.yaml                   # Optional Gateway API HTTPRoute
    ├── hpa.yaml                        # Horizontal Pod Autoscaler (enabled by default)
    └── tests/
        └── test-connection.yaml

Key Template Helpers

The _helpers.tpl file defines reusable template functions:

  • property-settings-svc-v2-chart.name - Chart name with override support
  • property-settings-svc-v2-chart.fullname - Fully qualified app name (max 63 chars)
  • property-settings-svc-v2-chart.chart - Chart name and version label
  • property-settings-svc-v2-chart.labels - Common labels for all resources
  • property-settings-svc-v2-chart.selectorLabels - Labels for selecting pods
  • property-settings-svc-v2-chart.serviceAccountName - Service account name resolution

Routing Options

The chart supports two routing mechanisms (both disabled by default):

  1. Traditional Ingress (ingress.enabled: false) - Standard Kubernetes Ingress using networking.k8s.io/v1
  2. Gateway API HTTPRoute (httpRoute.enabled: false) - Modern Gateway API routing with advanced traffic management

Default Configuration

  • Image: localhost:5001/prj-onlinesales-prod-01/os-docker-images/onlinesales/prod/services/java/propertysettingssvcv2:1752740345878
  • Service Type: ClusterIP on port 8080
  • Replicas: 3 (minimum when autoscaling is enabled)
  • Probes: HTTP health checks on /propertySettingsSvcV2/properties endpoint with specific query parameters
  • Autoscaling: Enabled by default (3-10 replicas, CPU target 200%, Memory target 80%)
  • Resources: CPU request 500m, Memory request 512Mi
  • Configuration Volumes:
    • ConfigMap mounted at /etc/onlinesales/config/propertySettingsSvcV2
    • Secret mounted at /etc/onlinesales/db

Working with Templates

When modifying templates, remember:

  • All resource names use the property-settings-svc-v2-chart.fullname helper
  • Labels should use the property-settings-svc-v2-chart.labels helper for consistency
  • Container port in deployment.yaml references service.port from values
  • The deployment uses conditional logic for autoscaling (.Values.autoscaling.enabled)
  • HTTPRoute template includes advanced features like filters and header manipulation

MySQL Database Configuration

The chart includes MySQL as an optional dependency using the WSO2 MySQL Helm chart (version 1.6.9).

Bundled MySQL (Default)

By default, the chart deploys MySQL alongside the application:

  • Version: MySQL 5.7.30
  • Database Name: property_settings_db_v2
  • Username: propertysettings
  • Password: changeme (should be changed for production)
  • Persistence: 8Gi storage (configurable)
  • Initialization: Automatically creates database schema and tables

To deploy with bundled MySQL:

helm install property-settings-v2 ./property-settings-svc-v2-chart

External MySQL

To use an external MySQL database, disable the bundled MySQL and configure connection details:

# values.yaml or custom-values.yaml
mysql:
  enabled: false

externalDatabase:
  host: "your-mysql-host.example.com"
  port: 3306
  database: "property_settings_db_v2"
  username: "propertysettings"
  password: "your-secure-password"

Deploy with external MySQL:

helm install property-settings-v2 ./property-settings-svc-v2-chart \
  --set mysql.enabled=false \
  --set externalDatabase.host=your-mysql-host.example.com \
  --set externalDatabase.password=your-secure-password

Important: When using external MySQL, ensure the database schema is initialized manually using the SQL scripts from sql/ directory.

Database Schema and Initialization

The chart uses a Helm Job with ConfigMap approach for database initialization (same pattern as hades-service):

How It Works

  1. SQL Files in sql/ Directory: All SQL migration scripts are stored as separate files
  2. Auto-Loading via ConfigMap: The configmap-sql-migrations.yaml template uses .Files.Glob "sql/**.sql" to automatically load all SQL files
  3. Execution via Helm Job: The job-dbinit.yaml runs as a post-install/post-upgrade hook that:
    • Waits for MySQL to be ready
    • Executes SQL files in alphabetical order (000, 001, 002, etc.)
    • Provides detailed logging and error handling
    • Fails if any migration fails

Advantages of this approach:

  • ✅ No need to embed SQL in values.yaml
  • ✅ SQL files remain separate and version-controlled
  • ✅ Automatic file discovery - just add/remove files in sql/ directory
  • ✅ Clean execution logs with success/failure reporting
  • ✅ Runs automatically on install and upgrade

Available SQL Files

The sql/ directory contains 5 files:

  1. 000_create_property_settings_db.sql - Creates the database
  2. 001_properties_table.sql - Creates properties table with triggers
  3. 002_populate_properties_table.sql - V1→V2 migration (commented out, not used)
  4. 003_alter_column_property_value.sql - Alters property_value column to TEXT
  5. 004_property_settings_db_v2.sql (79KB) - Complete database dump with staging data

OPTION 1: Clean Installation (Default)

For production deployments with an empty database:

Files to keep active:

  • 000, 001, 003 (002 is commented out)

To configure:

# Rename or remove the complete dump file
mv sql/004_property_settings_db_v2.sql sql/004_property_settings_db_v2.sql.bak

Result:

  • Empty properties table with proper schema
  • Triggers for automatic timestamp tracking
  • TEXT column type for property_value
  • Ready for production use

OPTION 2: Complete Database Dump (With Seed Data)

For development/testing with sample data from staging:

File to keep active:

  • 004 only

To configure:

# Rename the incremental files and keep only the dump
cd sql/
mv 000_create_property_settings_db.sql 000_create_property_settings_db.sql.bak
mv 001_properties_table.sql 001_properties_table.sql.bak
mv 002_populate_properties_table.sql 002_populate_properties_table.sql.bak
mv 003_alter_column_property_value.sql 003_alter_column_property_value.sql.bak
# Keep 004_property_settings_db_v2.sql active

Result:

  • Complete database with real staging data
  • 4 Agency records (TVING staging, TVING QA, etc.)
  • 24+ Client records with configurations
  • Moloco account details, payment modes
  • Schema_info table with migration tracking

⚠️ WARNING: Do NOT use both options together. The dump file (004) drops and recreates tables, conflicting with incremental files (000-003).

Schema Details

Table: properties

  • Primary Key: (entity_type, entity_value, property_type)
  • Columns: entity_type (VARCHAR 200), entity_value (VARCHAR 200), property_type (VARCHAR 200), property_value (TEXT), is_active (BOOLEAN), creation_date (DATETIME), last_update (DATETIME), last_updated_by (VARCHAR 150)
  • Triggers: Automatic timestamp and user tracking on INSERT/UPDATE
  • Character Set: UTF-8
  • Engine: InnoDB

Controlling Database Initialization

To disable automatic database initialization:

# values.yaml
dbInit:
  enabled: false

This is useful when:

  • Using an external database with existing schema
  • Managing schema separately
  • Running in environments where Jobs/Hooks are restricted

Hibernate Configuration

The Hibernate configuration in secret.yaml is dynamically generated based on MySQL settings:

  • Uses _db-helpers.tpl to determine connection details
  • Automatically configures JDBC URL, username, and password
  • Supports both internal and external MySQL seamlessly

Database Service Name Convention

When using bundled MySQL, the service is named <release-name>-mysql:

  • Example: With release name prop, MySQL service is prop-mysql
  • The database initialization Job and Hibernate config automatically use the correct service name
  • Connection string format: jdbc:mysql://<release-name>-mysql:3306/property_settings_db_v2

Configuration Management

ConfigMap (configmap.yaml)

The chart creates a ConfigMap containing application configuration files:

  • propertySettingsService.cfg - Main service configuration (prod/test environments)
  • log.cfg - Logging configuration
  • prodRestAccessor.cfg - Production REST accessor settings
  • testRestAccessor.cfg - Test REST accessor settings
  • authConfig.cfg - Authentication configuration
  • statsLogging.cfg - Statistics logging configuration

Important: These files contain placeholder content and must be updated with actual configuration before deployment.

Secret (secret.yaml)

The chart creates a Secret for sensitive database configuration:

  • propertySettingsV2.hbm.xml - Hibernate mapping file for database access

Important: This file contains placeholder XML and must be updated with actual database mapping before deployment.

Health Check Configuration

The service uses a comprehensive health check endpoint:

/propertySettingsSvcV2/properties?jsonQuery={encoded-json}

This endpoint validates:

  • Service availability
  • Database connectivity
  • Property retrieval functionality

The query is URL-encoded and checks for BUSINESS_SEGMENT_SET properties for AGENCY entity type.

Values Configuration

Key values.yaml sections (already configured):

  • image.repository and image.tag - Set to Property Settings V2 image
  • service.port - Set to 8080 (Tomcat default)
  • replicaCount - Set to 3 replicas
  • resources - CPU: 500m, Memory: 512Mi
  • autoscaling - Enabled (3-10 replicas, CPU: 200%, Memory: 80%)
  • livenessProbe and readinessProbe - Configured for Property Settings endpoint

Optional values to configure:

  • ingress or httpRoute - Enable one for external access
  • nodeSelector, tolerations, affinity - For pod scheduling preferences

Deployment Workflow

  1. Update Chart Dependencies (Required before first deployment):

    cd ./property-settings-svc-v2-chart
helm dependency update
cd ..

  2. Update Configuration Files (Required before first deployment):

    # Edit the ConfigMap template with actual configuration
vim ./property-settings-svc-v2-chart/templates/configmap.yaml

# Update MySQL credentials (if needed)
vim ./property-settings-svc-v2-chart/values.yaml
# Change mysql.mysqlRootPassword and mysql.mysqlPassword

  3. Validate the Chart:

    helm lint ./property-settings-svc-v2-chart
helm template test ./property-settings-svc-v2-chart --debug

  4. Deploy to Kubernetes (with bundled MySQL):

    helm install property-settings-v2 ./property-settings-svc-v2-chart \
  --set mysql.mysqlRootPassword=your-root-password \
  --set mysql.mysqlPassword=your-user-password

  5. Deploy to Kubernetes (with external MySQL):

    helm install property-settings-v2 ./property-settings-svc-v2-chart \
  --set mysql.enabled=false \
  --set externalDatabase.host=your-mysql-host \
  --set externalDatabase.password=your-password

  6. Verify Deployment:

    # Check all pods (application + MySQL if enabled)
kubectl get pods -l app.kubernetes.io/instance=property-settings-v2

# Check application logs
kubectl logs -l app.kubernetes.io/name=property-settings-svc-v2-chart

# Check MySQL logs (if bundled)
kubectl logs -l app.kubernetes.io/name=mysql

# Verify database connection
kubectl exec -it <property-settings-pod> -- sh
# Test connection to MySQL

Important Notes

  • The chart uses modern Kubernetes API versions (apps/v1, networking.k8s.io/v1)
  • Service account is created by default with API credentials auto-mounted
  • MySQL dependency must be updated - Run helm dependency update before first deployment
  • Database passwords should be changed - Default passwords are insecure and meant for development only
  • Configuration files must be updated before deployment - The ConfigMap contains placeholder content
  • The deployment automatically mounts configuration volumes - no need to modify deployment.yaml for config changes
  • The Hibernate configuration is dynamically generated based on MySQL settings (internal or external)
  • Database initialization uses Helm Job - SQL files are auto-loaded from sql/ directory and executed via a post-install/post-upgrade hook
  • When enabling HTTPRoute, ensure Gateway API CRDs are installed in the cluster
  • The image registry (localhost:5001) suggests a local registry - ensure it's accessible from your cluster
  • For external MySQL, the database schema must be initialized manually using scripts in sql/ directory

MySQL Dependency Details

Chart: WSO2 MySQL (version 1.6.9) Repository: https://helm.wso2.com Condition: mysql.enabled

The MySQL chart is conditionally deployed based on the mysql.enabled value. When enabled, it creates:

  • MySQL StatefulSet
  • PersistentVolumeClaim for data storage
  • Service for database access
  • ConfigMap for initialization scripts