Migrate PHP (laravel) app to Kubernetes

Introduction

Migrating a PHP (Laravel) application to Kubernetes offers numerous benefits such as scalability, high availability, and self-healing capabilities. In this guide, we will walk you through the process of containerizing your Laravel app using Docker and deploying it to Kubernetes.

Preparing your Laravel app

Before we start, ensure that your Laravel application is ready for containerization. For optimal performance, configure your app to use environment variables for settings like database connections and caching.

.env.example

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mydatabase
DB_USERNAME=myuser
DB_PASSWORD=mypassword

Creating a Dockerfile

To containerize your Laravel app, you will need a Dockerfile. This file describes the environment required to run your application, including the base image, dependencies, and necessary configurations.

Dockerfile

FROM php:8.2-fpm

# Install dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpng-dev \
    libjpeg62-turbo-dev \
    libfreetype6-dev \
    libwebp-dev \
    libonig-dev \
    libzip-dev \
    zip \
    unzip

# Configure GD library
RUN docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp
RUN docker-php-ext-install -j$(nproc) gd

# Install PHP extensions
RUN docker-php-ext-install pdo_mysql mbstring zip exif pcntl

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www

# Copy existing application directory
COPY . .

# Install app dependencies
RUN composer install

# Change ownership of app files
RUN chown -R www-data:www-data /var/www

# Expose port
EXPOSE 9000

CMD ["php-fpm"]

Building and pushing Docker images to the registry

Once you have created the Dockerfile, build the Docker image for your Laravel app.

docker build -t my-registry/my-laravel-app:latest .

Push the image to your container registry (e.g., Docker Hub, Google Container Registry, or AWS Elastic Container Registry).

docker push my-registry/my-laravel-app:latest

Kubernetes manifests

Next, you need to create Kubernetes manifest files. These files describe the desired state of your application and its infrastructure components.

deployment.yml

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-laravel-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-laravel-app
  template:
    metadata:
      labels:
        app: my-laravel-app
    spec:
      containers:
      - name: my-laravel-app
        image: my-registry/my-laravel-app:latest
        ports:
        - containerPort: 9000
        envFrom:
        - configMapRef:
            name: my-laravel-app-config

configmap.yml

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-laravel-app-config
data:
  DB_CONNECTION: mysql
  DB_HOST: my-laravel-db-service
  DB_PORT: "3306"
  DB_DATABASE: mydatabase
  DB_USERNAME: myuser
  DB_PASSWORD: mypassword

service.yml

---
apiVersion: v1
kind: Service
metadata:
  name: my-laravel-app-service
spec:
  selector:
    app: my-laravel-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 9000
  type: LoadBalancer

Deploying the application to Kubernetes

After creating the necessary manifest files, you can deploy your application to a Kubernetes cluster. First, apply the ConfigMap:

kubectl apply -f configmap.yml

Next, deploy the Laravel app using the Deployment manifest:

kubectl apply -f deployment.yml

Finally, create a LoadBalancer service to expose your application:

kubectl apply -f service.yml

You can now access your Laravel app through the LoadBalancer's external IP address.

Conclusion

In this guide, we demonstrated how to migrate a PHP (Laravel) application to Kubernetes. We covered containerizing the Laravel app using Docker, pushing the Docker image to a registry, creating Kubernetes manifest files, and deploying the application to a Kubernetes cluster. By following these steps, you can harness the power of Kubernetes to manage your Laravel application efficiently and effectively.

---

Need help with your Kubernetes infrastructure? Talk to our team — we've managed 1,350+ production servers and the first conversation is free.

Frequently Asked Questions

How do I handle Laravel queue workers in Kubernetes?

Deploy queue workers as a separate Deployment with php artisan queue:work as the container command. Set replicas based on queue depth, and add HPA based on a custom metric from Redis or SQS queue length. Use --tries=3 and --timeout=90 flags to prevent stuck jobs from consuming workers indefinitely.

Should I store Laravel sessions in Kubernetes pods or use Redis?

Use Redis or a database — never local file sessions. Kubernetes pods are ephemeral and traffic gets load-balanced across replicas, so file-based sessions break immediately with more than one pod. Set SESSION_DRIVER=redis in your environment config.

How do I run Laravel migrations during Kubernetes deployments?

Use a Kubernetes Job or init container that runs php artisan migrate --force before the main deployment rolls out. Never run migrations from inside application pods — multiple replicas would race to apply the same migration simultaneously.

What base Docker image should I use for Laravel on Kubernetes?

Start with php:8.2-fpm-alpine for the smallest image size (roughly 80MB vs 500MB for the Debian-based php:8.2-fpm). Pair it with an Nginx sidecar container or use a separate Nginx Deployment as a reverse proxy. Install only the PHP extensions your app needs — pdo_mysql, redis, gd, and zip cover most Laravel applications without bloating the image.

Related Reading

• Migrate NodeJS GraphQL app to Kubernetes
• Migrate PHP (lamp) app to Kubernetes
• Migrate ReactJS app to Kubernetes