NGINX Deployment Example in Kubernetes

In this example, we’ll create a simple NGINX deployment in Kubernetes using a ConfigMap to serve custom HTML content. This demonstrates how to use ConfigMaps to inject configuration and static content into your containers.

Learn more about Deployments Learn more about ConfigMaps

Overview

The ConfigMap nginx-config is created with the HTML contents of the index page. The Deployment nginx-deployment is then created, which uses the stock nginx image and mounts the ConfigMap as a volume at /usr/share/nginx/html. This means that the contents of the ConfigMap will be available to the nginx container and serve as the index page for the website.

Step 1: Create a ConfigMap

First, create a ConfigMap with an index.html file. This will be mounted into the nginx static directory.

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
data:
  index.html: |
    <html>
      <head>
        <title>My NGINX Page</title>
      </head>
      <body>
        <h1>Welcome to my NGINX Page</h1>
        <p>This page is served from a Kubernetes ConfigMap!</p>
      </body>
    </html>

Apply the ConfigMap with:

kubectl apply -f configmap.yaml

Learn more about NGINX

Step 2: Create the Deployment

Then, create a Deployment file like so, and apply it with kubectl as above.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /usr/share/nginx/html
      volumes:
      - name: config-volume
        configMap:
          name: nginx-config

Apply the deployment with:

kubectl apply -f deployment.yaml

Step 3: Create a Service

To make the NGINX deployment accessible, create a Service:

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80
  type: ClusterIP

Apply the service with:

kubectl apply -f service.yaml

Step 4: Verify the Deployment

Check that everything is running correctly:

# Check the deployment status
kubectl get deployments

# Check the pods
kubectl get pods

# Check the service
kubectl get services

# Test the deployment
kubectl port-forward service/nginx-service 8080:80

Then visit http://localhost:8080 in your browser to see your custom NGINX page.

Additional Configuration Options

Using LoadBalancer Service Type

For external access, you can change the service type to LoadBalancer:

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

Adding Resource Limits

You can add resource requests and limits to your deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"
        volumeMounts:
        - name: config-volume
          mountPath: /usr/share/nginx/html
      volumes:
      - name: config-volume
        configMap:
          name: nginx-config

Troubleshooting

If you encounter issues:

  1. Check pod status: kubectl describe pod <pod-name>
  2. Check pod logs: kubectl logs <pod-name>
  3. Verify ConfigMap: kubectl get configmap nginx-config -o yaml
  4. Check service endpoints: kubectl get endpoints nginx-service

Learn more about troubleshooting

Next Steps

This example demonstrates basic Kubernetes concepts. You can extend it by:

  • Adding an Ingress for external access
  • Implementing health checks with liveness and readiness probes
  • Setting up horizontal pod autoscaling
  • Adding persistent storage for logs
  • Implementing rolling updates

For more examples and tutorials, visit the official Kubernetes documentation and the NGINX documentation.