Troubleshooting Nginx and PHP-FPM Volume Mount Issues

Problem Statement

#

We encountered an issue with our Nginx and PHP-FPM setup on the Kubernetes cluster this morning, which halted its functionality. The task is to investigate and rectify the issue.

Environment Details:

• Pod name: nginx-phpfpm
• ConfigMap name: nginx-config
• Goal: Copy /home/thor/index.php from jump host to nginx-container and make the website accessible

Note: Despite the appearance of a volume mount issue, the root cause is actually the incorrect nginx configuration in the configmap, specifically the path to where the web server files are stored.

Investigation

#

1. Inspect the Pod

#

kubectl describe pod nginx-phpfpm

Key Observations from the output:

• The pod has 2 containers: php-fpm-container and nginx-container
• Both containers share an emptyDir volume named shared-files for website files
• nginx-container has an additional volume mounted from the configmap containing nginx config
• Critical Issue Identified:
  • php-fpm-container mounts shared-files at /var/www/html
  • nginx-container mounts shared-files at /usr/share/nginx/html
  • These paths don’t match! The containers can’t share files if they’re looking in different locations

2. Understanding the Default Paths

#

Important distinction:

• Nginx default: /usr/share/nginx/html
• Apache default: /var/www/html

The PHP container assumes the nginx default path, but the nginx container configuration doesn’t match.

Solution

#

Step 1: Fix the ConfigMap

#

The nginx configuration needs to point to the correct document root.

kubectl edit configmap nginx-config

Update the root path:

# Set nginx to serve files from the shared volume!
root /usr/share/nginx/html;

Step 2: Update the Pod Volume Mount

#

Since pod properties are immutable, we need to recreate the pod. From the kubectl describe output, we can see:

• nginx-container already mounts at /usr/share/nginx/html ✅
• php-fpm-container mounts at /var/www/html ❌

We need to fix the PHP-FPM container mount path:

kubectl get pod nginx-phpfpm -o yaml > pod.yaml
vi pod.yaml

Update the volume mount in the php-fpm-container:

  - image: php:7.2-fpm-alpine
    imagePullPolicy: Always
    name: php-fpm-container
    resources: {}
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    volumeMounts:
    - mountPath: /usr/share/nginx/html    # <- Changed from /var/www/html
      name: shared-files

Recreate the pod:

kubectl replace --force -f pod.yaml

Verify the pod is running:

kubectl get pod nginx-phpfpm

Step 3: Copy the PHP File

#

Copy index.php to the correct location in the nginx container:

kubectl cp -c nginx-container index.php nginx-phpfpm:/usr/share/nginx/html/index.php

Step 4: Verify

#

Access the website using the Website button. You should now see the PHP application running successfully.

Key Takeaways

#

1. Path consistency is critical: All mount paths must align:

   • Volume mount in php-fpm-container
   • Volume mount in nginx-container
   • Root directive in nginx configuration

2. Know your defaults: Different web servers use different default paths

   • Nginx: /usr/share/nginx/html
   • Apache: /var/www/html

3. Pod immutability: You cannot edit certain pod properties in-place; recreation is required

4. EmptyDir volumes: Perfect for sharing files between containers in the same pod, but all mount paths must be synchronized : Changed from /var/www/html to /usr/share/nginx/html

• Nginx container mount path: Already correct at /usr/share/nginx/html
• Nginx configuration root directive: Updated to /usr/share/nginx/html

This alignment allowed both containers to properly share the web files through the emptyDir volume, enabling the website to function correctly.

Final Configuration Summary

#

# Both containers now mount the shared volume at the same path
php-fpm-container:
  volumeMounts:
  - mountPath: /usr/share/nginx/html
    name: shared-files

nginx-container:
  volumeMounts:
  - mountPath: /usr/share/nginx/html
    name: shared-files

# nginx.conf (in configmap)
root /usr/share/nginx/html;

• Nginx container mount path
• Nginx configuration root directive

This alignment allowed both containers to properly share the web files through the emptyDir volume, enabling the website to function correctly.