Overview

This guide provides comprehensive instructions for configuring LILT to utilize Amazon Relational Database Service (RDS) as a managed database solution in place of locally deployed MySQL instances within your Kubernetes cluster. Implementing RDS offers significant advantages including enhanced scalability, automated backup management, built-in high availability, and reduced operational overhead for database administration.

Prerequisites

The following prerequisites must be satisfied before proceeding with the RDS configuration:
  1. AWS Account Access: An active AWS account with appropriate IAM permissions to create and manage RDS instances
  2. RDS Instance: A properly configured RDS MySQL instance deployed within the same Virtual Private Cloud (VPC) as your LILT deployment
  3. SSL Certificate Bundle: The Amazon RDS Certificate Authority (CA) certificate bundle (global-bundle.pem) for establishing secure SSL connections
  4. Kubernetes Secrets: Pre-configured Kubernetes secrets containing your RDS database credentials

Configuration Steps

1. Prepare RDS Connection Details

Collect and document the following information from your RDS instance configuration:
  • RDS Endpoint: The fully qualified domain name (FQDN) of your RDS instance
  • Port Number: Database connection port (default: 3306)
  • Database Name: The target database schema name
  • Authentication Credentials: Master username and corresponding password

2. Create Kubernetes Secrets

RDS credentials must be securely stored within Kubernetes secrets. The following example demonstrates the standard approach, though your organization may employ alternative secret management solutions such as External Secrets Operator or HashiCorp Vault.
kubectl create secret generic lilt-rds-creds \
  --from-literal=username=your-rds-username \
  --from-literal=password=your-rds-password \
  --from-literal=endpoint=your-rds-endpoint
Note: The endpoint parameter may alternatively be configured directly within the overlay configuration file, depending on your organizational requirements and deployment preferences.

3. Configure SSL Certificates

Secure database connections require proper SSL certificate configuration. The RDS CA certificate bundle must be uploaded to a Kubernetes secret for authentication purposes. The required certificates can be obtained from the AWS RDS SSL/TLS Documentation. Important: LILT currently requires the global certificate bundle. If utilizing regional certificates, ensure the certificate files are renamed to match the expected global-bundle naming convention.
kubectl create secret generic rds-tls-ca-cert \
  --from-file=global-bundle.pem \
  --from-file=global-bundle.p7b
A convenience script is added to the installer. You can update the bundle files in <installer_dir>/mysql/rds_ca/ and set the option to generate the secret file in install_scripts/run-mysql-migrations.sh set option BOOTSTRAP_DB_CA accordingly. If BOOTSTRAP_DB_CA="true" The installer then will generate the secret in the required namespace. If you would like to provide the secret from a different process, you should generate the file as mentioned before.

4. Update Overlay Configuration

The overlay configuration file, located at lilt/environments/seed_custom_values/database.yaml within the installer directory, serves as the central configuration point for all database-related components. Note: If this overlay is not required for your deployment, ensure the file is cleared to prevent unintended configuration conflicts. Configure the overlay YAML file with the following settings:

Database Connection Settings

Configure the following RDS connection parameters within your overlay file:
  • rds_host: The RDS endpoint URL (optional if configured within the secret)
  • rds_port: Database connection port (default: 3306)
  • rds_database_name: Database schema name (currently limited to ‘lilt_dev’)
  • rds_db_secret_name: Reference to the Kubernetes secret containing database credentials (must exist in the deployment namespace)
  • rds_db_username_key: Secret key containing the database username
  • rds_db_password_key: Secret key containing the database password
  • rds_db_host_key: Secret key containing the RDS endpoint
  • rds_ca_secret: Reference to the secret containing CA certificates (global-bundle)

Component Configuration

The overlay configuration applies RDS settings across all LILT platform components:
  • Frontend Services: Web application and API interfaces
  • Neural Services: Including tag-projection, alignment, and automqm modules
  • Connectors: Integration and synchronization services
  • Core Services: Converter, quality assurance, search, and processing modules
  • Core API: Primary application programming interface
  • Dataflow: Data pipeline and processing infrastructure
Each component references the existing Kubernetes secret for database authentication rather than generating new credentials. Configuration parameters may be specified either through secret key references or explicit values, providing flexibility in deployment approaches. The provided example configuration utilizes a unified secret containing username, password, and endpoint values. Organizations requiring alternative configurations should review and adjust component-specific settings accordingly.

5. Apply Configuration

Execute the LILT installation procedure with the RDS overlay configuration:
./install-lilt.sh
This command applies the overlay configuration to your LILT deployment, establishing connections to the RDS instance for all configured components.

6. Upgrade Considerations

While the LILT development team implements rigorous testing procedures, database upgrades inherently carry potential risks. Organizations must implement comprehensive backup strategies before initiating any upgrade procedures to ensure data recovery capabilities in the event of unexpected issues. Critical Recommendations:
  • Perform complete database backups before upgrades
  • Test upgrade procedures in non-production environments
  • Maintain documented rollback procedures
  • Verify backup restoration processes regularly

Overlay File Structure

The overlay configuration file employs a structured approach to managing RDS settings across the LILT platform:

1. Global Configuration Variables

The file utilizes YAML anchors (&) and aliases (*) to define reusable configuration parameters:
  • Database connection specifications (host, port, database name)
  • Kubernetes secret references and key mappings
  • SSL/TLS certificate configurations
  • Shared connection string templates

2. Component-Specific Sections

Each platform component maintains its own configuration section with inherited global settings:
  • Frontend Services (Lines 26-70): Web application and API configurations
  • Neural Services (Lines 74-117): Machine learning and processing modules
  • Connectors (Lines 121-150): Integration service configurations
  • Core Services (Lines 154-231): Primary processing and business logic
  • Core API (Lines 235-255): API service configurations
  • Dataflow (Lines 260-302): Data pipeline settings

3. Configuration Patterns

The overlay implements consistent configuration patterns across all components:
  • useExistingSecret.enabled: true: Enforces the use of existing Kubernetes secrets for authentication
  • createSecret: false: Prevents automatic generation of new database credentials
  • SSL Certificate Volumes: Properly configured volume mounts for TLS certificate access
  • Environment Variables: Standardized database connection parameters
  • YAML Anchors: Ensures configuration consistency and reduces redundancy

4. Security Features

The configuration prioritizes security through several mechanisms:
  • Credential Isolation: Database credentials are never stored directly in configuration files
  • SSL/TLS Enforcement: Mandatory encrypted connections to RDS instances
  • Secret Management: Integration with Kubernetes native secret handling
  • Template-based Connection Strings: Prevents hardcoding of sensitive connection details

Configuration Example

The following excerpt demonstrates the overlay configuration structure and implementation:
# RDS Database Configuration Overlay
# This overlay configures endpoint, username, and password parameters for RDS database connectivity
# across all LILT platform component charts
# Secret Configuration References
rds_db_secret_name: &rds_db_secret_name "lilt-rds-creds"  # Kubernetes secret containing RDS credentials
rds_db_username_key: &rds_db_username_key "username"      # Key for database username within the secret
rds_db_password_key: &rds_db_password_key "password"      # Key for database password within the secret
rds_db_host_key: &rds_db_host_key "endpoint"              # Key for RDS endpoint URL within the secret

# Database Connection Parameters
rds_host: &rds_host null                                  # RDS endpoint (null if provided via secret)
rds_port: &rds_port "3306"                                # Database connection port
rds_database_name: &rds_db_name "lilt"                    # Target database schema name

# SSL/TLS Certificate Configuration
rds_ca_secret: &rds_ca_secret "rds-tls-ca-cert"           # Secret containing RDS CA certificates
# Note: LILT expects certificate keys to be named 'global-bundle.pem' and 'global-bundle.p7b'

# ==================================================
# Template Definitions (Do not modify unless required)
# ==================================================
x-rds_ca_certificate_path: &x-rds_ca_certificate_path /rds_cacerts/global-bundle.pem
x-rds_ca_mount_path: &x-rds_ca_mount_path /rds_cacerts
x-rds_jdbc_connection_string: &x-rds_jdbc_connection_string "jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}"

# Component-Specific Configurations
front:
  onpremValues:
    init:
      enabled: true
    config:
      database:
        useExistingSecret:
          enabled: true
          existingSecretRef: *rds_db_secret_name
          # Key mappings within the referenced secret
          # Falls back to front_secret_values/front_configmap_values if unspecified
          userKey: *rds_db_username_key
          passKey: *rds_db_password_key
          hostKey: *rds_db_host_key
          # portKey: (optional - uses default port if unspecified)
          # databaseKey: (optional - uses default database if unspecified)
        createSecret: false  # Prevents creation of new secrets

      front_secret_values:
        dbPwd: null  # Null when using existing secret
      front_configmap_values:
        dbHost: *rds_host
        dbPort: *rds_port
        dbUser: null  # Null when using existing secret
        dbName: *rds_db_name
    env:
      SSL_MYSQL_PATH_TO_CA: *x-rds_ca_certificate_path
      SSL_MYSQL_PATH_TO_CERT: null  # Client certificate (optional)
      SSL_MYSQL_PATH_TO_KEY: null   # Client key (optional)
    
    # Volume configuration for SSL certificates
    sslCertSecretVolumes:
      - name: tls-client-certificates
        secret:
          secretName: "tls-client-certificates"
      - name: *rds_ca_secret
        secret:
          secretName: *rds_ca_secret
    
    # Volume mount configuration for SSL certificates
    sslCertSecretVolumeMounts:
      - name: tls-client-certificates
        mountPath: /etc/ssl/client-certs
        readOnly: true
      - name: *rds_ca_secret
        mountPath: *x-rds_ca_mount_path
        readOnly: true