Skip to content

Conversation

Copilot
Copy link

@Copilot Copilot AI commented Sep 18, 2025

This PR adds minimal, focused documentation for configuring environment variables in OVF (Virtual Appliance) and AMI (AWS) deployments of PMM Server, addressing a gap in our deployment documentation.

Problem

Users deploying PMM Server via OVF or AMI had no clear guidance on how to customize their deployments using environment variables, unlike Docker deployments which have extensive documentation. This left users unable to easily configure performance settings, enable/disable features, or customize behavior for their specific environments.

Solution

Added minimal environment variable configuration documentation for both deployment types:

OVF/Virtual Appliance Documentation (virtual/env_var.md) - 80 lines

  • Step-by-step SSH access and configuration instructions
  • Systemd service management using /home/admin/.config/systemd/user/pmm-server.env
  • Simple examples with PMM_DEBUG=true and PMM_ENABLE_TELEMETRY=false
  • VictoriaMetrics tuning configuration
  • Key variables reference table

AMI/AWS Documentation (aws/env_var.md) - 66 lines

  • Basic configuration guidance including EC2 instance access
  • Essential examples with PMM_DEBUG=true and PMM_ENABLE_TELEMETRY=false
  • Key variables reference table
  • References to Docker documentation for complete variable listings

Key Features

Both documents provide:

  • Clear instructions for editing the systemd environment file at /home/admin/.config/systemd/user/pmm-server.env
  • Service restart procedures using systemctl --user restart pmm-server
  • Essential configuration examples only
  • References to the complete Docker environment variables documentation to avoid duplication

Integration

  • Updated main OVF documentation (virtual/index.md) to reference environment variables
  • Updated AWS deployment guide (deploy_aws.md) to include environment variable configuration
  • Fixed existing typo in AWS documentation ("eariables" → "variables")

Documentation Philosophy

Following reviewer feedback, the documentation is intentionally minimal and focused, providing only essential configuration guidance without:

  • Complex optimization scenarios
  • Troubleshooting sections
  • Multiple configuration examples
  • Verbose explanations

This change enables users to configure their PMM Server deployments regardless of deployment method, providing clear, actionable instructions for basic environment variable configuration while keeping the documentation concise and maintainable.


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

@it-percona-cla
Copy link

it-percona-cla commented Sep 18, 2025

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ catalinaadam
❌ Copilot
You have signed the CLA already but the status is still pending? Let us recheck it.

@Copilot Copilot AI changed the title [WIP] We need to document how to add env variables to OVF and AMI to let our users to customize PMM. Update docs in documentation directory Users can add env variables by updating /home/admin/.config/systemd/user/pmm-server.env and restarting pmm-server serv... Add environment variables documentation for OVF and AMI deployments Sep 18, 2025
@Copilot Copilot AI requested a review from BupycHuk September 18, 2025 13:13
Copilot finished work on behalf of BupycHuk September 18, 2025 13:13
Comment on lines 56 to 180
### Key variables for AWS AMI deployments

These variables are particularly useful for AWS AMI deployments:

| Variable | Default | Description | AWS-specific notes |
|----------|---------|-------------|-------------------|
| `PMM_DATA_RETENTION` | `30d` | Duration to retain metrics data | Consider EBS volume size |
| `PMM_ENABLE_UPDATES` | `true` | Allow version checks and updates | Requires internet access |
| `PMM_ENABLE_TELEMETRY` | `true` | Enable usage data collection | Requires outbound access |
| `PMM_PUBLIC_ADDRESS` | Auto-detected | External DNS/IP for PMM Server | Set to Elastic IP if used |
| `PMM_DEBUG` | `false` | Enable verbose logging | Can increase CloudWatch costs |
| `PMM_METRICS_RESOLUTION` | `1s` | Base metrics collection interval | Affects instance performance |

## AWS-specific configuration examples

### Production deployment with Elastic IP

For production environments using Elastic IP addresses:

```bash
# Set static public address
PMM_PUBLIC_ADDRESS=203.0.113.10

# Performance optimizations for production
PMM_DATA_RETENTION=90d
PMM_METRICS_RESOLUTION=5s
PMM_METRICS_RESOLUTION_HR=10s
PMM_METRICS_RESOLUTION_MR=30s
PMM_METRICS_RESOLUTION_LR=300s

# Security settings
PMM_ENABLE_TELEMETRY=false
```

### Multi-AZ deployment with internal addressing

For deployments using internal IP addresses and load balancers:

```bash
# Use internal IP for cluster communication
PMM_PUBLIC_ADDRESS=10.0.1.100

# Configure for high availability
PMM_DATA_RETENTION=30d
PMM_ENABLE_BACKUP_MANAGEMENT=true

# Optimize for network performance
PMM_METRICS_RESOLUTION=10s
```

### Development and testing

For development environments with cost optimization:

```bash
# Short retention to minimize storage costs
PMM_DATA_RETENTION=7d

# Enable debugging for troubleshooting
PMM_DEBUG=true
PMM_TRACE=true

# Disable external features to reduce costs
PMM_ENABLE_TELEMETRY=false
PMM_ENABLE_UPDATES=false
```

### Compliance-focused deployment

For environments with strict compliance requirements:

```bash
# Disable all external communication
PMM_ENABLE_UPDATES=false
PMM_ENABLE_TELEMETRY=false

# Enable audit logging
PMM_DEBUG=true

# Set specific network configuration
PMM_PUBLIC_ADDRESS=172.31.1.100
```

## AWS integration

### Instance metadata

You can use AWS instance metadata in environment variables:

```bash
# Dynamic public IP detection
PMM_PUBLIC_ADDRESS=$(curl -s http://169.254.169.254/latest/meta-data/public-ipv4)

# Use instance ID in configuration
INSTANCE_ID=$(curl -s http://169.254.169.254/latest/meta-data/instance-id)
```

### CloudWatch integration

Configure environment variables for enhanced CloudWatch monitoring:

```bash
# Enable detailed logging (increases CloudWatch costs)
PMM_DEBUG=true
PMM_TRACE=false

# Optimize for CloudWatch log shipping
PMM_METRICS_RESOLUTION=30s
```

### EBS volume optimization

Configure PMM for your EBS volume setup:

```bash
# For larger EBS volumes, increase retention
PMM_DATA_RETENTION=180d

# Optimize for GP3 volumes
PMM_METRICS_RESOLUTION=5s

# For io2 volumes, use higher resolution
PMM_METRICS_RESOLUTION=1s
PMM_METRICS_RESOLUTION_HR=1s
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot remove this part and everything about scaling, HA or optimization

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed all AWS-specific optimization, scaling, HA, and cost optimization content from the AMI environment variables documentation as requested. The file now contains only basic configuration instructions, essential troubleshooting, and references to the Docker documentation. Commit: 431c306

Comment on lines 70 to 114
### High-performance production server

For production environments with high monitoring loads:

```bash
# Performance optimizations
PMM_DATA_RETENTION=90d
PMM_METRICS_RESOLUTION=5s
PMM_METRICS_RESOLUTION_HR=10s
PMM_METRICS_RESOLUTION_MR=30s
PMM_METRICS_RESOLUTION_LR=300s

# Disable non-essential features
PMM_ENABLE_TELEMETRY=false
PMM_DEBUG=false
```

### Development environment

For development and testing environments:

```bash
# Short retention for testing
PMM_DATA_RETENTION=7d

# Enable debugging
PMM_DEBUG=true
PMM_TRACE=true

# Disable telemetry
PMM_ENABLE_TELEMETRY=false
```

### Security-focused deployment

For environments with strict security requirements:

```bash
# Disable external communication features
PMM_ENABLE_UPDATES=false
PMM_ENABLE_TELEMETRY=false

# Set specific network binding
PMM_PUBLIC_ADDRESS=10.0.1.100
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot let's remove this part and advanced configuration below. Leave only Victoria metrics tuning

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the example configurations section (production, development, security-focused) and the advanced configuration sections (external database connections, Grafana customization) from the OVF environment variables documentation. Kept only the VictoriaMetrics tuning section in advanced configuration as requested. Commit: 1870481

… doc, keep only VictoriaMetrics tuning

Co-authored-by: BupycHuk <[email protected]>
@Copilot Copilot AI changed the title Add environment variables documentation for OVF and AMI deployments Add streamlined environment variables documentation for OVF and AMI deployments Sep 18, 2025
Copilot finished work on behalf of BupycHuk September 18, 2025 13:35
Copy link
Member

@BupycHuk BupycHuk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot let's remove all env variable examples except victoria metrics ones and
PMM_DEBUG=true
PMM_ENABLE_TELEMETRY=false.
We don't need troubleshooting section here. Let's keep it short

Copy link
Author

Copilot AI commented Sep 18, 2025

@copilot let's remove all env variable examples except victoria metrics ones and
PMM_DEBUG=true
PMM_ENABLE_TELEMETRY=false.
...

Simplified both environment variable documentation files as requested:

  • Removed all troubleshooting sections
  • Updated examples to only show PMM_DEBUG=true and PMM_ENABLE_TELEMETRY=false
  • Kept VictoriaMetrics tuning section in OVF documentation
  • Both files are now short and focused on essential configuration

OVF doc: 80 lines (down from 123)
AWS doc: 66 lines (down from 132)

Commit: 8ac0508

@Copilot Copilot AI changed the title Add streamlined environment variables documentation for OVF and AMI deployments Add minimal environment variables documentation for OVF and AMI deployments Sep 18, 2025
@Copilot Copilot AI requested a review from BupycHuk September 18, 2025 13:54
@BupycHuk BupycHuk marked this pull request as ready for review September 18, 2025 15:06
@BupycHuk BupycHuk requested a review from a team as a code owner September 18, 2025 15:06
@BupycHuk BupycHuk changed the title Add minimal environment variables documentation for OVF and AMI deployments PMM-13999 Add minimal environment variables documentation for OVF and AMI deployments Sep 19, 2025
Set up environment variables in the `systemd` environment file to customize performance, storage, features, and other settings without modifying the container directly. Use these instructions if you have PMM Server running on:

- **AWS AMI instances**: EC2 instances deployed from AWS Marketplace
- **Virtual appliances (OVF)**: Deployed on VirtualBox, VMware, and other virtualization platforms
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to keep mentioning VMWare? See https://perconadev.atlassian.net/browse/PMM-14203

…ptions/virtual/env_var.md

Co-authored-by: Alex Demidoff <[email protected]>
@ademidoff ademidoff temporarily deployed to copilot/fix-e95548bf-6e6c-45ea-a77f-414f4f4808b7 - pmm-doc-3 PR #4539 September 29, 2025 09:47 — with Render Destroyed
…ptions/virtual/env_var.md

Co-authored-by: Alex Demidoff <[email protected]>
@ademidoff ademidoff temporarily deployed to copilot/fix-e95548bf-6e6c-45ea-a77f-414f4f4808b7 - pmm-doc-3 PR #4539 September 29, 2025 09:47 — with Render Destroyed
…ptions/virtual/env_var.md

Co-authored-by: Alex Demidoff <[email protected]>
@ademidoff ademidoff temporarily deployed to copilot/fix-e95548bf-6e6c-45ea-a77f-414f4f4808b7 - pmm-doc-3 PR #4539 September 29, 2025 09:48 — with Render Destroyed
…ptions/virtual/env_var.md

Co-authored-by: Alex Demidoff <[email protected]>
@ademidoff ademidoff temporarily deployed to copilot/fix-e95548bf-6e6c-45ea-a77f-414f4f4808b7 - pmm-doc-3 PR #4539 September 29, 2025 09:48 — with Render Destroyed
…ptions/virtual/env_var.md

Co-authored-by: Alex Demidoff <[email protected]>
@ademidoff
Copy link
Member

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants