WordPress – Operations­Guide

Overview

WordPress runs on a single-node K3s cluster on AlmaLinux 9. The entire infrastructure is built and managed with an Ansible playbook (blog.yml). The playbook is idempotent – it can be re-run at any time without modifying data or unnecessarily interrupting services.

Architecture

Overall Overview

Why This Approach?

WordPress Pod in Detail

Storage & Data

Why are app and database separate volumes?

• Database data (/srv/wordpress-db) can be backed up independently
• WordPress files are supplemented during an update by the new image (the entrypoint updates core files in-place)
• Both volumes survive a pod restart or image update unharmed

Ownership and Permissions

WordPress-FPM runs as www-data (UID 33 in the container). The HostPath directory must be writable by this user:

# Set ownership for WordPress files (from the host):
chown -R 33:33 /srv/wordpress-www

# Database data belongs to root (MariaDB in the container uses root internally):
ls -la /srv/wordpress-db

Network & TLS

IP Address Ranges

Required DNS Records

The DNS record must be created at the domain registrar before the first playbook run. cert-manager needs it for the Let's Encrypt HTTP-01 challenge – without a valid record the certificate issuance will fail.

TLS and Proxy Chain

Internet
  → nginx-ingress F5 (Port 443, TLS terminated, sets X-Forwarded-For / -Proto)
    → nginx sidecar (Port 80, plain HTTP)
      → PHP-FPM (Port 9000, FastCGI)

nginx-ingress forwards requests from its pod namespace (10.42.x.x). The nginx sidecar is configured to read the real client IP from the X-Forwarded-For header:

# nginx ConfigMap (nginx-cm.yml.j2):
set_real_ip_from 10.42.0.0/16;   # Pod CIDR – ingress packets originate from here
real_ip_header   X-Forwarded-For;
real_ip_recursive on;

Rate Limiting and Security at the Ingress

Security measures are defined directly in the Ingress via nginx.org/ annotations:

Important Files in the Repository

Inventory & Variables

Ansible Roles (WordPress-specific)

Templates (generate the K8s manifests)

Variables & Secrets

Where Credentials Are Stored

All passwords are stored in inventory/host_vars/www.apt-upgrade.me/vault.yml, encrypted with Ansible Vault. This file must never be committed unencrypted to git.

# Encrypt before committing:
ansible-vault encrypt inventory/host_vars/www.apt-upgrade.me/vault.yml

# Open directly in editor (preferred):
ansible-vault edit inventory/host_vars/www.apt-upgrade.me/vault.yml

Typical vault.yml Contents

blog_db_root_pass: "..."       # MariaDB root password
blog_db_pass:      "..."       # WordPress DB user password
blog_admin_pass:   "..."       # WordPress admin password
mail_smtppass:     "..."       # SMTP password for mail delivery
grafana_admin_pass: "..."      # Grafana admin password

Secrets in the K8s Cluster

The vault variables flow into the K8s secret wordpress-secrets in the namespace wordpress during the playbook run.

# Show secret (decoded):
k3s kubectl get secret wordpress-secrets -n wordpress \
  -o jsonpath='{.data}' | python3 -c \
  "import sys,json,base64; [print(k,base64.b64decode(v).decode()) \
   for k,v in json.load(sys.stdin).items()]"

Container Images & Versions

All image tags are centrally defined in inventory/group_vars/all.yml. K3s automatically pulls a new image only when the tag in the manifest has changed (imagePullPolicy: IfNotPresent).

# inventory/group_vars/all.yml
blog_image_wordpress: "wordpress:6.9-fpm"   # WordPress PHP-FPM
blog_image_mariadb:   "mariadb:10.11"       # MariaDB LTS
blog_image_nginx:     "nginx:1.30-alpine"   # nginx Sidecar

Tag Strategy

Check for New Versions

crictl pull docker.io/library/wordpress:6.9-fpm
k3s kubectl rollout restart deployment/wordpress -n wordpress

WordPress Configuration

wp-config.php

The wp-config.php is automatically generated by the WordPress Docker entrypoint from the environment variables on first start. Important generated entries:

define('DB_HOST',     'mariadb');          // K8s service name in the namespace
define('DB_NAME',     'wordpress_db');
define('DB_USER',     'wordpress');
define('DB_PASSWORD', '...');              // from K8s Secret

// WordPress's own cron is disabled (K8s CronJob takes over):
define('DISABLE_WP_CRON', true);

// URL settings (set by Ansible):
define('WP_HOME',    'https://www.apt-upgrade.me');
define('WP_SITEURL', 'https://www.apt-upgrade.me');

Plugins (managed via Ansible)

Plugins are defined as a list in inventory/host_vars/www.apt-upgrade.me/vars.yml and automatically installed and activated by the blog_wordpress playbook:

blog_wordpress_plugins:
  - all-in-one-wp-migration       # Import/export for backups
  - classic-editor                # Classic editor instead of Gutenberg
  - limit-login-attempts-reloaded # Additional brute-force protection

Query the Database Directly

# In the MariaDB pod (no root password needed, socket auth):
k3s kubectl exec -n wordpress deployment/mariadb -- \
  mysql -u wordpress -p wordpress_db

# Or with explicit password:
k3s kubectl exec -n wordpress deployment/mariadb -- \
  mysql -u wordpress -p'<password>' wordpress_db -e "SHOW TABLES;"

Run Playbook

Full Initial Run (new server installation)

1. Set SSH port to 22 in inventory/host_vars/www.apt-upgrade.me/vars.yml: ansible_port: 22
2. Enter vault passwords in vault.yml and encrypt
3. Install collections: ansible-galaxy collection install -r requirements.yml
4. Run playbook:

   ansible-playbook blog.yml --limit www.apt-upgrade.me --ask-vault-pass

5. Change SSH port in vars.yml to 10022 (after SSH hardening by common_ssh)

Idempotent Re-run (e.g. after config change)

ansible-playbook blog.yml --limit www.apt-upgrade.me --ask-vault-pass

Run Only Specific Roles

# Update only K8s deployments
ansible-playbook blog.yml --limit www.apt-upgrade.me --tags blog_k3s_deploy --ask-vault-pass

# Only WordPress configuration (plugins, admin, settings)
ansible-playbook blog.yml --limit www.apt-upgrade.me --tags blog_wordpress --ask-vault-pass

Important Operations Commands

Pod Status

# All pods in the wordpress namespace
k3s kubectl get pods -n wordpress

# Detailed status
k3s kubectl describe pod -l app=wordpress -n wordpress

# Logs WordPress-FPM
k3s kubectl logs deployment/wordpress -c wordpress-fpm -n wordpress --tail=50

# Logs nginx sidecar
k3s kubectl logs deployment/wordpress -c nginx -n wordpress --tail=50

# Logs MariaDB
k3s kubectl logs deployment/mariadb -n wordpress --tail=50

WP-CLI Commands

# Prefix for all WP-CLI commands:
k3s kubectl exec -n wordpress deployment/wordpress -c wordpress-fpm -- \
  wp --allow-root <COMMAND>

# Examples:
... wp core version
... wp core check-update
... wp plugin list
... wp plugin update --all
... wp theme list
... wp cache flush
... wp cron event list
... wp user list
... wp db check
... wp search-replace 'http://www.apt-upgrade.me' 'https://www.apt-upgrade.me' --dry-run

Restart Pod

# WordPress
k3s kubectl rollout restart deployment/wordpress -n wordpress
k3s kubectl rollout status  deployment/wordpress -n wordpress --timeout=300s

# MariaDB (Caution: brief DB downtime!)
k3s kubectl rollout restart deployment/mariadb -n wordpress

Namespace Overview

k3s kubectl get all -n wordpress

Check Ingress and Certificate

# Ingress resource
k3s kubectl get ingress -n wordpress
k3s kubectl describe ingress wordpress -n wordpress

# TLS certificate
k3s kubectl get certificate -n wordpress
k3s kubectl describe certificate wordpress-tls -n wordpress

Monitoring

The monitoring stack (Prometheus + Grafana + Node Exporter + mysqld_exporter + php-fpm_exporter) runs partly as host services, partly as sidecar containers in K3s pods. Grafana is accessible via the ingress at the blog hostname under /grafana/.

MariaDB Slow Query Log

The MariaDB pod writes slow queries (≥ 1 second) to /var/lib/mysql/slow.log – this resides on the HostPath volume and is readable on the host at /srv/wordpress-db/slow.log. (Background: /dev/stderr is not writable in the MariaDB container under K3s – the mysql process runs as uid 999 and has no access to the fd.)

# Read slow queries on the host
tail -f /srv/wordpress-db/slow.log

# Or directly in the pod
k3s kubectl exec -n wordpress deployment/mariadb -c mariadb -- \
  tail -f /var/lib/mysql/slow.log

Configuration: MariaDB pod args --slow-query-log=1 --slow-query-log-file=/var/lib/mysql/slow.log --long-query-time=1

PHP-FPM Slow Log

PHP-FPM logs requests that take longer than 5 seconds to /proc/1/fd/2 (corresponding to stderr of the pod's main process). Since ptrace is not available in containers, no stack traces are written – only the request timestamp and execution time.

# Monitor slow FPM requests
k3s kubectl logs -n wordpress deployment/wordpress -c wordpress-fpm -f | grep -i "slow"

Configuration: ConfigMap wordpress-fpm-pool-config → pm.status_path = /fpm-status, slowlog = /proc/1/fd/2, request_slowlog_timeout = 5s

Grafana Dashboards

Node Exporter Full (ID 1860) – Host Metrics

Shows the health of the entire server in real time.

MySQL Overview (ID 7362) – MariaDB Database Metrics

Shows the performance of the WordPress database (MariaDB sidecar in K3s pod, NodePort 30104).

PHP-FPM (ID 4912) – PHP Process Pool

Shows how well PHP-FPM processes WordPress requests (K3s pod, NodePort 30253).

mysqld_exporter – Configuration Note

Prometheus Scrape Targets

# Check active scrape targets (in browser or curl)
curl -s http://127.0.0.1:9090/api/v1/targets | python3 -m json.tool | grep -E '"job"|"state"|"scrapeUrl"'

WP-Cron

WordPress requires a regular cron call for scheduled tasks: plugin updates, email delivery, publishing scheduled posts, etc. In this setup a Kubernetes CronJob handles this task.

Check CronJob Status

# Status and last run
k3s kubectl get cronjob wordpress-cron -n wordpress

# The last 5 jobs (completed pods)
k3s kubectl get jobs -n wordpress --sort-by=.metadata.creationTimestamp | tail -5

# Logs of a CronJob pod (ID from previous command):
k3s kubectl logs -n wordpress -l job-name=wordpress-cron-<id>

Manual Execution (for testing)

k3s kubectl exec -n wordpress deployment/wordpress -c wordpress-fpm -- \
  php /var/www/html/wp-cron.php

Updates

Operating System (AlmaLinux 9)

Security updates are applied automatically daily by dnf-automatic. For a full system update:

1. ssh -p 10022 root@217.154.101.78
   dnf upgrade -y

2. Check whether a reboot is necessary:

   needs-restarting -r

3. If needed: reboot the server. K3s starts automatically, all pods come back up on their own.

   reboot
   # Then check:
   k3s kubectl get pods -n wordpress

WordPress Update: Patch Within the Same Tag

When Docker Hub updates wordpress:6.9-fpm to 6.9.1 and the tag in Ansible remains unchanged:

1. Manually pull the new image:

   crictl pull docker.io/library/wordpress:6.9-fpm

2. Restart the pod:

   k3s kubectl rollout restart deployment/wordpress -n wordpress
   k3s kubectl rollout status  deployment/wordpress -n wordpress --timeout=300s

WordPress Update: Minor Version Jump (e.g. 6.9 → 7.0)

1. Change the tag in inventory/group_vars/all.yml:

   blog_image_wordpress: "wordpress:7.0-fpm"

2. Run the playbook – K3s pulls the new image and rolls out the pod:

   ansible-playbook blog.yml --limit www.apt-upgrade.me --ask-vault-pass

3. Check for WordPress DB update (sometimes needed for major versions):

   k3s kubectl exec -n wordpress deployment/wordpress -c wordpress-fpm -- \
     wp --allow-root core update-db

MariaDB Update

Patch updates within 10.11:

crictl pull docker.io/library/mariadb:10.11
k3s kubectl rollout restart deployment/mariadb -n wordpress

Backup & Restore

What Is Backed Up

Run Backup

The backup script has no environment argument – it always backs up www.apt-upgrade.me to /data/wordpress/www.apt-upgrade.me/.

# Call from the repository directory:
cd ~/www_k3s
./scripts/wordpress-backup.sh

# Process:
# 1. WP-CLI maintenance-mode activate  (in the wordpress-fpm container)
# 2. kubectl exec → mysqldump          (in the mariadb container, password from K8s secret)
# 3. rsync /srv/wordpress-www/         → /data/wordpress/www.apt-upgrade.me/wordpress/
# 4. WP-CLI maintenance-mode deactivate

Restore Workflow

1. Set up server (infrastructure):

   ansible-playbook blog.yml --limit www.apt-upgrade.me --ask-vault-pass

2. Run restore script:

   cd ~/www_k3s
   ./scripts/wordpress-restore.sh

   Process: maintenance on → stop WordPress + MariaDB → rsync WordPress files → clear MariaDB data dir → start MariaDB (re-initialization from K8s secret) → import SQL dump → fix ownership → start WordPress → maintenance off

3. Run Ansible again (ensures plugin list and WP config):

   ansible-playbook blog.yml --limit www.apt-upgrade.me --ask-vault-pass

Manual Individual Commands (Reference)

# mysqldump from the MariaDB pod (MARIADB_ROOT_PASSWORD from K8s secret)
k3s kubectl exec -n wordpress deployment/mariadb -c mariadb -- \
  sh -c 'mysqldump --single-transaction wordpress_db \
    -u root -p"$MARIADB_ROOT_PASSWORD"'

# Import SQL dump into a running MariaDB pod
k3s kubectl exec -n wordpress deployment/mariadb -c mariadb -- \
  sh -c 'mysql wordpress_db -u root -p"$MARIADB_ROOT_PASSWORD" < /tmp/dump.sql'

# WP-CLI Maintenance
k3s kubectl exec -n wordpress deployment/wordpress -c wordpress-fpm -- \
  php /var/www/html/wp-cli.phar maintenance-mode activate --path=/var/www/html --allow-root

Troubleshooting

WordPress Pod Does Not Start / CrashLoopBackOff

k3s kubectl describe pod -l app=wordpress -n wordpress
k3s kubectl logs deployment/wordpress -c wordpress-fpm -n wordpress --previous

Common causes:

• Database not reachable: MariaDB pod is not running. Check k3s kubectl get pods -n wordpress.
• Wrong DB password: Secret wordpress-secrets does not match the MariaDB user. Re-run the playbook.
• Volume permissions: chown -R 33:33 /srv/wordpress-www and restart the pod.

MariaDB Pod Does Not Start

k3s kubectl logs deployment/mariadb -n wordpress --previous

• Database files corrupted: MariaDB attempts a recovery. In the worst case the data must be restored from backup.
• Volume permissions: MariaDB expects /srv/wordpress-db to be writable by the internal mysql user (UID 999). Ansible sets the permissions automatically.

WordPress Site Shows 502 Bad Gateway

nginx sidecar cannot reach PHP-FPM. Check:

# Is PHP-FPM running?
k3s kubectl logs deployment/wordpress -c wordpress-fpm -n wordpress --tail=20

# Are both containers in the pod Ready?
k3s kubectl get pod -l app=wordpress -n wordpress

WordPress Admin Backend: "Database Update Required"

k3s kubectl exec -n wordpress deployment/wordpress -c wordpress-fpm -- \
  wp --allow-root core update-db

Certificate Is Not Being Issued

# cert-manager logs:
k3s kubectl logs -n cert-manager deployment/cert-manager --tail=50

# Certificate object:
k3s kubectl describe certificate wordpress-tls -n wordpress

# ClusterIssuer status:
k3s kubectl describe clusterissuer letsencrypt-prod

Common cause: port 80 is blocked by iptables or the provider. cert-manager requires port 80 for the HTTP-01 challenge (even if the site should only be reachable via HTTPS).

Rate Limiting Too Aggressive (Own IP Blocked)

# Check ingress logs (nginx-ingress controller):
k3s kubectl logs -n ingress-nginx daemonset/ingress-nginx-nginx-ingress-controller --tail=50

# Temporarily: redeploy ingress without rate limit (for emergencies):
# → remove nginx.org/server-snippets annotation in the ingress and run the playbook

WP-Cron Is Not Running

# CronJob status:
k3s kubectl get cronjob wordpress-cron -n wordpress

# Last job pod (should be "Completed"):
k3s kubectl get pods -n wordpress --sort-by=.metadata.creationTimestamp | tail -5

# Trigger manually (for testing):
k3s kubectl exec -n wordpress deployment/wordpress -c wordpress-fpm -- \
  php /var/www/html/wp-cron.php

Security

Multi-Layered Protection Strategy

Firewall in Detail

The script /root/fw/fw_ipv4.sh (from common_firewall) is applied via an @reboot cron job after every restart. K3s then inserts its own KUBE-* chains at the top of the INPUT/OUTPUT chains.

# Monitor dropped packets live
journalctl -k -f --grep "IPTables-Dropped"

# Show port scan blocklist
cat /proc/net/xt_recent/portscan | awk '{print $1}'

# Reload firewall rules (happens automatically after reboot)
/root/fw/fw_ipv4.sh && /root/fw/fw_ipv6.sh

Important Security Notes