Skip to content

Local Providers

Jump to bottom
Eric Mann edited this page Jan 7, 2026 · 5 revisions

Local Providers

Local providers in Displace enable development and testing on your local machine using lightweight Kubernetes clusters. This is perfect for developing applications, testing configurations, and learning Kubernetes without cloud costs.

Overview

The local provider uses k3d (k3s in Docker) to create lightweight Kubernetes clusters on your local machine. These clusters are:

  • Always Free: No cost, no limits for local development
  • Fast Setup: Clusters start in seconds
  • Full Kubernetes: Complete Kubernetes API compatibility
  • Persistent: Data persists between restarts
  • Isolated: Each project can have its own cluster if needed

The Default Local Provider

Displace automatically configures a local provider that cannot be removed. This provider:

  • Uses k3d to create a cluster named displace-local
  • Includes ingress controller for local access
  • Comes with monitoring stack (Prometheus, Grafana, Alertmanager)
  • Maps to localhost ports for easy access

Installation and Setup

The local provider is set up automatically when you run:

displace install

This creates:

  • Local k3d cluster named displace-local
  • Kubernetes context configured in ~/.kube/config
  • Monitoring stack with Grafana, Prometheus, and Alertmanager
  • Ingress controller for local application access

Manual Local Cluster Setup

If you need to recreate or customize the local cluster:

# Check local cluster status
displace cluster status displace-local

# Note: Local cluster management is handled through k3d directly:
# k3d cluster start displace-local
# k3d cluster stop displace-local
# k3d cluster delete displace-local

Using the Local Provider

Basic Usage

The local provider is automatically available and ready to use:

# List providers (local is always present)
displace provider list

# Test local provider connectivity
displace provider test local

# Deploy to local cluster (uses displace-local cluster)
displace project deploy --cluster displace-local

Project Development Workflow

  1. Initialize Project

    mkdir my-app && cd my-app
displace project init wordpress

  2. Deploy Locally

    displace project deploy --cluster displace-local

  3. Access Application

    # Get project info with access URLs
displace project info

# Port forward for direct access
kubectl port-forward service/my-app-wordpress 8080:80

  4. Monitor and Debug

    # Check pod status
kubectl get pods

# View logs
kubectl logs deployment/my-app-wordpress

# Access monitoring
kubectl port-forward -n monitoring svc/grafana 3000:80

Local Cluster Features

Ingress Controller

The local cluster includes an ingress controller that allows you to access applications via hostnames:

# Applications can be accessed via ingress automatically
curl http://myapp.local.displace.tech

Applications are automatically accessible via the wildcard DNS:

  • http://myapp.local.displace.tech
  • http://wordpress.local.displace.tech
  • http://<your-app-name>.local.displace.tech

Persistent Storage

Local clusters support persistent volumes:

  • Default Storage Class: Local path provisioner
  • Data Location: ~/.displace/clusters/local/storage/
  • Persistence: Data survives cluster restarts
  • Backup: Simply backup the storage directory

Load Balancer Simulation

k3d includes a load balancer with wildcard DNS support:

  • HTTP: Port 80 accessible via *.local.displace.tech
  • HTTPS: Port 443 accessible via https://*.local.displace.tech
  • Custom Ports: Additional ports can be mapped as needed

Monitoring Stack

Every local cluster includes a complete monitoring stack:

Grafana Dashboards

# Access Grafana (admin/admin)
kubectl port-forward -n monitoring service/grafana 3000:80
# Visit http://grafana.local.displace.tech:3000

Pre-configured dashboards for:

  • Kubernetes cluster metrics
  • Application performance
  • Resource utilization
  • Custom application metrics

Prometheus Metrics

# Access Prometheus directly
kubectl port-forward -n monitoring service/prometheus-server 9090:80
# Visit http://prometheus.local.displace.tech:9090

Application Logs

# View logs directly from pods/deployments
kubectl logs deployment/<deployment-name>
kubectl logs -f pod/<pod-name>

# View logs in Grafana
# Grafana includes basic log viewing capabilities

Configuration

Cluster Configuration

The local cluster can be customized:

# Custom node count (for testing)
displace cluster create local --nodes 3

# Custom Kubernetes version
displace cluster create local --k8s-version v1.28.0

# Additional ports
displace cluster create local --port 8080:80 --port 8443:443

Resource Limits

Local clusters respect Docker resource limits:

# Check Docker resources
docker system info

# Monitor cluster resource usage
kubectl top nodes
kubectl top pods --all-namespaces

Advanced Features

Multiple Local Clusters

While the default local provider is always available, you can create additional local clusters:

# Create additional local cluster
k3d cluster create my-test-cluster

# Configure kubectl context
kubectl config use-context k3d-my-test-cluster

# Deploy to specific cluster
kubectl apply -f my-manifests/

Development Tools Integration

The local environment integrates with common development tools:

# k9s for cluster management
k9s

# Helm for package management
helm list

# Docker for container inspection
docker ps

Volume Mounts

For development, you can mount local directories:

# In your Kubernetes manifests
apiVersion: v1
kind: Pod
spec:
  volumes:
  - name: source-code
    hostPath:
      path: /host/path/to/code
  containers:
  - name: app
    volumeMounts:
    - name: source-code
      mountPath: /app/src

Troubleshooting

Common Issues

Cluster won't start:

# Check Docker is running
docker version

# Check k3d status
k3d cluster list

# Recreate cluster if needed
k3d cluster delete displace-local
displace cluster create local

Port conflicts:

# Check what's using ports 80/443
lsof -i :80
lsof -i :443

# Use alternative ports
k3d cluster create displace-local --port 8080:80 --port 8443:443

Storage issues:

# Check storage location
ls -la ~/.displace/clusters/local/storage/

# Clean up old data (if safe)
rm -rf ~/.displace/clusters/local/storage/*

Memory/CPU limits:

# Check Docker resource limits
docker system info

# Monitor cluster resource usage
kubectl top nodes

Debugging Commands

# Check cluster health
kubectl get nodes
kubectl get pods --all-namespaces

# Check system pods
kubectl get pods -n kube-system

# View cluster events
kubectl get events --all-namespaces --sort-by='.lastTimestamp'

# Check ingress controller
kubectl get pods -n kube-system -l app.kubernetes.io/name=traefik

Performance Considerations

Resource Usage

Local clusters are lightweight but still consume resources:

  • Memory: ~500MB baseline + your applications
  • CPU: Minimal when idle, scales with workload
  • Disk: ~200MB for cluster + your application data
  • Network: Uses Docker networking (no external traffic)

Optimization Tips

  1. Stop unused clusters: k3d cluster stop <name>
  2. Clean up old images: docker system prune
  3. Monitor resource usage: docker stats
  4. Use resource limits in your manifests

Development Best Practices

  1. Use namespace separation for different projects
  2. Implement readiness/liveness probes for proper testing
  3. Test with realistic resource limits
  4. Use persistent volumes for databases and file storage
  5. Monitor logs and metrics during development

Related Documentation:

Home

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally