OpenEMR on EKS Version Awareness System Guide

This document describes the comprehensive version awareness and notification system for the OpenEMR on EKS project. The system provides read-only awareness of available updates without automatically applying any changes.

📋 Table of Contents

🎯 Overview

The version awareness system provides:

Automated version checking for all project components
GitHub issue notifications when updates are available
Comprehensive monitoring of all dependencies
GitHub Actions integration for continuous awareness
Centralized configuration for all version dependencies
Manual control - no automatic updates applied
AWS CLI integration for accurate version checking when credentials are available (prefers OIDC authentication)
Graceful fallback when AWS credentials are not available
Comprehensive codebase search to locate version strings in files
Dual run modes for both automated monthly and manual on-demand checks

Dependency Management Approach

This project uses a manual approach to dependency management:

Version Manager (Awareness & Tracking)
- Monthly version checking across all components
- Creates GitHub issues for awareness
- Tracks versions in versions.yaml
- No automatic changes - read-only awareness
- Manual review and approval of all updates

📁 System Components

1. Centralized Configuration (`versions.yaml`)

The versions.yaml file serves as the single source of truth for all version information:

# Core Application Versions
applications:
  openemr:
    current: "8.0.0"
    registry: "openemr/openemr"

2. Version Manager Script (`scripts/version-manager.sh`)

The main script for checking and updating versions:

# Check for available updates
./scripts/version-manager.sh check

# Show current status
./scripts/version-manager.sh status

Capabilities:

Queries Docker Hub, Helm repositories, and AWS APIs
Respects update policies (stable vs latest)
Generates detailed update reports
Provides version awareness for CI/CD workflows

3. GitHub Actions Workflow (`.github/workflows/monthly-version-check.yml`)

Automated CI/CD integration with dual run support:

Triggers:

Monthly scheduled checks (1st of every month at 9:00 AM UTC)
Manual workflow dispatch with component selection (defaults to "all")

Features:

Dual run modes: Monthly automated and manual timestamped runs
Component selection: Choose specific component types for manual runs if desired or use the default of "all"
Flexible reporting: Option to run checks without creating issues
Timestamped issues: Manual runs create unique timestamped issues
Duplicate prevention: Monthly runs check for existing issues
Comprehensive search: Includes codebase search for version locations
Artifact storage: Version check logs and reports
Notification system: Success/failure notifications
AWS CLI integration: Uses AWS credentials when available for accurate version checking (prefers OIDC authentication)
Graceful fallback: Works without AWS credentials with clear reporting

🚀 Quick Start

1. Initial Setup

# Install dependencies
sudo apt-get update
sudo apt-get install -y curl jq yq kubectl terraform

# Make version manager script executable
chmod +x scripts/version-manager.sh

# Check current status
./scripts/version-manager.sh status

2. Check for Updates

# Check all components
./scripts/version-manager.sh check

# Check specific component types
./scripts/version-manager.sh check --components applications
./scripts/version-manager.sh check --components infrastructure
./scripts/version-manager.sh check --components terraform_modules
./scripts/version-manager.sh check --components github_workflows
./scripts/version-manager.sh check --components monitoring
./scripts/version-manager.sh check --components eks_addons

📋 Component Management

OpenEMR Application

Version Source: Docker Hub (openemr/openemr) Update Policy: Stable (recommended for production) Files Updated:

terraform/terraform.tfvars
k8s/deployment.yaml
versions.yaml

# Check OpenEMR versions
./scripts/check-openemr-versions.sh --latest

# Check for OpenEMR updates
./scripts/version-manager.sh check --components applications

Kubernetes Version

Version Source: AWS EKS supported versions Current Version: 1.35 (Latest stable) Release Notes: Kubernetes v1.35 "Timbernetes (The World Tree Release)" Release Blog

Files Updated:

terraform/terraform.tfvars
terraform/terraform.tfvars.example
terraform/variables.tf
terraform/eks.tf
versions.yaml
Documentation files (README.md, DEPLOYMENT_GUIDE.md, TROUBLESHOOTING.md)

Monitoring Stack

Components:

Prometheus Operator (Helm chart: kube-prometheus-stack)
Loki (Helm chart: loki, repository: grafana)
Tempo (Helm chart: tempo, repository: grafana, replaces Jaeger)
Mimir (Helm chart: mimir-distributed, repository: grafana)
OTeBPF (DaemonSet deployment, not a Helm chart)

Files Updated:

monitoring/prometheus-values.yaml
versions.yaml

Infrastructure Components

Components:

Fluent Bit (Docker image)
Aurora MySQL (AWS RDS)
Terraform AWS Provider

Terraform Modules

Components:

EKS Module (terraform-aws-modules/eks/aws)
EKS Pod Identity Module (terraform-aws-modules/eks-pod-identity/aws)
VPC Module (terraform-aws-modules/vpc/aws)
AWS Provider (hashicorp/aws)
Kubernetes Provider (hashicorp/kubernetes)

GitHub Workflows

Components:

GitHub Actions dependencies and versions
Pre-commit hooks
CI/CD pipeline components

EKS Add-ons

Components:

EFS CSI Driver
Metrics Server

🔧 Configuration

AWS IAM Permissions

The version checking workflow uses AWS CLI commands to fetch the latest versions of AWS services when credentials are available. The workflow gracefully handles missing credentials by falling back to documentation scraping.

⚠️ IMPORTANT: This repository now prefers GitHub OIDC → AWS IAM role for AWS authentication in GitHub Actions workflows.

Use OIDC whenever possible. Static AWS access keys are still supported for backward compatibility.

See GITHUB_AWS_CREDENTIALS.md for complete setup instructions, or use the automated setup in oidc_provider/.

Required AWS Services

The workflow interacts with the following AWS services:

EKS (Elastic Kubernetes Service) - For Kubernetes and add-on version information
RDS (Relational Database Service) - For Aurora MySQL version information
STS (Security Token Service) - For credential validation

Minimum IAM Policy

Here's the minimum IAM policy that provides read-only access to the required services:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VersionCheckEKSReadOnly",
            "Effect": "Allow",
            "Action": [
                "eks:DescribeAddonVersions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VersionCheckRDSReadOnly",
            "Effect": "Allow",
            "Action": [
                "rds:DescribeDBEngineVersions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VersionCheckSTSReadOnly",
            "Effect": "Allow",
            "Action": [
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        }
    ]
}

Option 1: GitHub OIDC (Recommended)

Preferred method - No long-lived credentials stored in GitHub:

Deploy OIDC provider using the Terraform module:

cd oidc_provider
terraform init
terraform apply

Configure GitHub Secret:
- Add AWS_OIDC_ROLE_ARN secret with the role ARN from Terraform outputs
- The role ARN is displayed in the Terraform outputs after deployment
The workflow automatically uses OIDC - no access keys needed!

The OIDC provider creates an IAM role with the exact minimum permissions shown above. See GITHUB_AWS_CREDENTIALS.md for detailed setup instructions.

Option 2: IAM User with Static Credentials (Legacy/Fallback)

For backward compatibility - Only use if OIDC cannot be configured:

Create IAM User:

aws iam create-user --user-name openemr-version-check

Attach Policy:

# Save the policy above as version-check-policy.json
aws iam put-user-policy \
    --user-name openemr-version-check \
    --policy-name VersionCheckReadOnly \
    --policy-document file://version-check-policy.json

Create Access Keys:

aws iam create-access-key --user-name openemr-version-check

Configure GitHub Secrets: Add the following secrets to your GitHub repository:
- AWS_ACCESS_KEY_ID: The access key ID from step 3
- AWS_SECRET_ACCESS_KEY: The secret access key from step 3
- AWS_REGION: The AWS region (optional, defaults to us-west-2)

Note: The workflow will automatically prefer OIDC if configured, falling back to static credentials if needed.

Security Considerations

Read-only access only: No write, create, update, or delete permissions
Fallback behavior: Workflow continues to function without AWS credentials
OIDC preferred: Short-lived tokens reduce exposure risk compared to static access keys

Testing Permissions

You can test the permissions with these commands:

# Test EKS permissions
aws eks describe-addon-versions --addon-name aws-ebs-csi-driver --query 'addons[0].addonVersions[].compatibilities[].clusterVersion' --output text

# Test RDS permissions
aws rds describe-db-engine-versions --engine aurora-mysql --query 'DBEngineVersions[?contains(EngineVersion, `8.0.mysql_aurora.3`)].EngineVersion' --output text

# Test STS permissions
aws sts get-caller-identity

🔄 Workflow Examples

Monthly Update Process

Automated Check (1st of every month at 9:00 AM UTC)

# GitHub Actions runs automatically
# Creates monthly issue: "Version Check Report for Month of [Month Year]"

Review Updates

# Check the generated GitHub issue
# Review comprehensive update report with codebase search results
# Each report includes locations (files and line numbers in said files) where old version strings are found

Test in Development

# Check what updates are available
./scripts/version-manager.sh check

# Apply updates manually in development environment

Deploy to Production

# After testing, apply updates manually to production

Manual On-Demand Checks

Trigger Manual Check

# Via GitHub Actions UI:
# 1. Go to Actions → Version Check & Awareness
# 2. Click "Run workflow"
# 3. Select component type (all, applications, infrastructure, etc.)
# 4. Choose whether to create issue (default: true)
# 5. Click "Run workflow"

Component-Specific Checks

# Check only applications
./scripts/version-manager.sh check --components applications

# Check only EKS add-ons
./scripts/version-manager.sh check --components eks_addons

# Check only monitoring stack
./scripts/version-manager.sh check --components monitoring

Review Timestamped Issues

# Manual runs create timestamped issues:
# "Manual Version Check Report - 2025-01-15 14:30:25 UTC"
# Each manual run creates a new unique issue

Emergency Update Process

Identify Issue

# Check for security updates
./scripts/version-manager.sh check

Quick Update

# Apply critical updates immediately (manual process)
# Review GitHub issue for specific update instructions

Verify and Monitor

# Check deployment version status
./scripts/version-manager.sh status

✨ Enhanced Features

Dual Run Modes

The version checker supports two distinct run modes:

Monthly Automated Runs

Schedule: 1st of every month at 9:00 AM UTC
Issue Title: "Version Check Report for Month of [Month Year]"
Labels: version-check, automated, monthly, maintenance, dependencies, awareness
Behavior: Checks for existing monthly issues to prevent duplicates
Purpose: Regular awareness and maintenance planning

Manual On-Demand Runs

Trigger: Manual workflow dispatch via GitHub Actions UI
Issue Title: "Manual Version Check Report - [YYYY-MM-DD HH:MM:SS UTC]"
Labels: version-check, manual, maintenance, dependencies, awareness
Behavior: Always creates new timestamped issues (no duplicate checking)
Purpose: Ad-hoc checking, targeted analysis, emergency assessments

Comprehensive Codebase Search

When updates are found, the system automatically searches the entire codebase for the current version string:

Search Scope

Comprehensive coverage: Searches all files in the project
Smart exclusions: Excludes build artifacts, temporary files, and logs
Categorized results: Groups findings by file type (Configuration, Documentation, Script, Terraform, Other)

Search Results Format

### 📍 Version Locations for [Component]

**Current Version:** `1.2.3`
**Latest Version:** `1.3.0`

**Files containing current version:**

#### 🔧 Configuration Files
versions.yaml:    current: "1.2.3"
deployment.yaml:  image: openemr:1.2.3

#### 📚 Documentation Files
README.md:        OpenEMR version 1.2.3
CHANGELOG.md:     - Updated to version 1.2.3

#### 🐚 Script Files
deploy.sh:        VERSION="1.2.3"
update.sh:        check_version "1.2.3"

Component Selection

Manual runs support targeted component checking:

Available Component Types

all - Check all components (default)
applications - OpenEMR, Fluent Bit
infrastructure - Kubernetes, Terraform, AWS Provider
terraform_modules - EKS, VPC, RDS modules
github_workflows - GitHub Actions dependencies
monitoring - Prometheus, AlertManager, Grafana Loki, Grafana Tempo, Grafana Mimir, OTeBPF
eks_addons - EFS CSI Driver, Metrics Server

Use Cases

Targeted updates: Check only specific component types
Focused analysis: Investigate particular areas of concern
Quick checks: Fast verification of specific components

Flexible Reporting

The system provides multiple reporting options:

Issue Creation Options

Create issue: Generate a GitHub issue with full report (default)
No issue: Run checks without creating issues (useful for testing)

Report Content

Comprehensive updates: All available updates with details
Codebase search results: Exact locations of version strings

Report Formats

GitHub Issues: Rich markdown with formatting and links
Console Output: Terminal-friendly text format
Log Files: Detailed logs for debugging and analysis
Artifacts: Downloadable reports from GitHub Actions

🛡️ Safety Features

Awareness and Notifications

GitHub Issues: Automatic issue creation for updates
Detailed Reports: Comprehensive update information
Component Filtering: Can choose to check only specific component types
Priority Management: Configurable priority thresholds

Monitoring

Comprehensive Coverage: All dependencies tracked
Regular Checks: Monthly automated checking
Access Control: GitHub Actions with properly scoped permissions

📊 Monitoring and Reporting

Update Reports

Generated reports include:

Available updates for each component
Risk assessment and recommendations
File locations where versions are found
Priority-based update recommendations

GitHub Integration

Issues: Automatic issue creation for updates
Artifacts: Logs and reports stored as artifacts
Dual Run Modes: Monthly automated and manual timestamped runs

Logging

Detailed Logs: All operations logged with timestamps
Error Tracking: Comprehensive error reporting

🚨 Troubleshooting

Common Issues

1. Version Check Fails

# Check dependencies
./scripts/version-manager.sh check --log-level DEBUG

# Verify network connectivity
curl -I https://registry.hub.docker.com

Debug Mode

Enable detailed logging:

export LOG_LEVEL=DEBUG
./scripts/version-manager.sh check

# or 

./scripts/version-manager.sh check --log-level DEBUG

🔗 Integration Points

CI/CD Pipeline

The version management system integrates with:

GitHub Actions: Automated checking and reporting
Terraform: Infrastructure version management
Kubernetes: Application deployment updates
Docker Hub: Container image version tracking
AWS APIs: EKS and RDS version checking

External Services

Docker Hub API: Image version checking
Helm Repositories: Chart version checking
AWS APIs: Service version checking
GitHub API: Issue creation and management

📈 Best Practices

Update Strategy

Staged Rollouts: Test in dev before production
Regular Updates: Monthly checks, monthly updates
Security First: Prioritize security updates
Documentation: Keep release notes updated
Manual Review: Review and test all updates before applying
Update versions.yaml: Keep centralized version tracking current

Risk Management

Backup Everything: Always create backups
Test Thoroughly: Comprehensive testing before production
Monitor Closely: Watch for issues after updates
Have Rollback Plan: Know how to revert changes
Review Breaking Changes: Check release notes before updates

Maintenance

Regular Cleanup: Remove old backups and logs
Update Dependencies: Keep tools and scripts current
Review Policies: Adjust update policies as needed
Monitor Performance: Track update success rates

🆘 Support

Getting Help

Documentation: Check this guide and others in this repository
Logs: Review log files for detailed information
GitHub Issues: Report problems via GitHub issues
Community: OpenEMR community forums

Emergency Contacts

Critical Issues: Create GitHub issues with urgent label
Rollback Help: Have rollback procedures planned and ready to execute when performing updates

This version management system is designed to keep your OpenEMR EKS deployment secure, up-to-date, and reliable. Regular maintenance and following best practices will ensure optimal performance and security.

FilesExpand file tree

VERSION_MANAGEMENT.md

Latest commit

History

VERSION_MANAGEMENT.md

File metadata and controls

OpenEMR on EKS Version Awareness System Guide

📋 Table of Contents

🎯 Getting Started

📋 Component Management

🔧 Configuration

🔄 Workflow Examples

✨ Enhanced Features

🛡️ Safety & Monitoring

🚨 Troubleshooting & Support

🎯 Overview

Dependency Management Approach

📁 System Components

1. Centralized Configuration (versions.yaml)

2. Version Manager Script (scripts/version-manager.sh)

3. GitHub Actions Workflow (.github/workflows/monthly-version-check.yml)

🚀 Quick Start

1. Initial Setup

2. Check for Updates

📋 Component Management

OpenEMR Application

Kubernetes Version

Monitoring Stack

Infrastructure Components

Terraform Modules

GitHub Workflows

EKS Add-ons

🔧 Configuration

AWS IAM Permissions

Required AWS Services

Minimum IAM Policy

Option 1: GitHub OIDC (Recommended)

Option 2: IAM User with Static Credentials (Legacy/Fallback)

Security Considerations

Testing Permissions

🔄 Workflow Examples

Monthly Update Process

Manual On-Demand Checks

Emergency Update Process

✨ Enhanced Features

Dual Run Modes

Monthly Automated Runs

Manual On-Demand Runs

Comprehensive Codebase Search

Search Scope

Search Results Format

Component Selection

Available Component Types

Use Cases

Flexible Reporting

Issue Creation Options

Report Content

Report Formats

🛡️ Safety Features

Awareness and Notifications

Monitoring

📊 Monitoring and Reporting

Update Reports

GitHub Integration

Logging

🚨 Troubleshooting

Common Issues

Debug Mode

🔗 Integration Points

CI/CD Pipeline

External Services

📈 Best Practices

Update Strategy

Risk Management

Maintenance

🆘 Support

Getting Help

Emergency Contacts

1. Centralized Configuration (`versions.yaml`)

2. Version Manager Script (`scripts/version-manager.sh`)

3. GitHub Actions Workflow (`.github/workflows/monthly-version-check.yml`)