Meshery Installation Guide

Meshery can be deployed on various platforms including Docker, Kubernetes, and multiple cloud providers. This guide provides detailed installation instructions for each supported platform.

Prerequisites

System Requirements

2+ CPU cores
4GB+ RAM
10GB+ disk space

Required Software

Docker 20.10+ or Kubernetes 1.21+
kubectl (for Kubernetes deployments)
Helm 3.0+ (optional)

Meshery runs as a set of containers inside or outside of your Kubernetes clusters. Choose the installation method that best fits your environment.

Quick Installation

Using mesheryctl (Recommended)

The fastest way to install Meshery is using mesheryctl, the official CLI:

Install mesheryctl

macOS / Linux
Windows (WSL2)
Homebrew
Scoop (Windows)

curl -L https://meshery.io/install | bash -

curl -L https://meshery.io/install | bash -

brew install mesheryctl

scoop bucket add mesheryctl https://github.com/meshery/scoop-bucket.git
scoop install mesheryctl

Start Meshery

mesheryctl system start

By default, Meshery deploys using Docker. Access the UI at:

http://localhost:9081

Platform-Specific Installation

Docker

mesheryctl
Docker Compose
Docker Extension

Deploy Meshery on Docker using mesheryctl:

mesheryctl system start --platform docker

This will:

Download the latest Meshery images
Start Meshery Server on port 9081
Configure networking and volumes
Mount your kubeconfig for cluster access

Configuration:

Meshery Server: http://localhost:9081
Config directory: ~/.meshery
Kubeconfig: ~/.kube/config (mounted automatically)

Install using Docker Compose directly:

Download docker-compose.yaml

curl -L -o docker-compose.yaml \
  https://raw.githubusercontent.com/meshery/meshery/master/install/docker/docker-compose.yaml

Start Meshery

docker-compose up -d

Verify deployment

docker-compose ps

docker-compose.yaml configuration:

services:
  meshery:
    image: meshery/meshery:stable-latest
    environment:
      - "PROVIDER_BASE_URLS=https://cloud.layer5.io"
      - "EVENT=mesheryLocal"
      - "KUBECONFIG_FOLDER=/home/appuser/.kube"
      - "PORT=9081"
    volumes:
      - $HOME/.kube:/home/appuser/.kube:ro
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "9081:9081"

Install Meshery as a Docker Desktop extension:

Install from Docker Desktop

Open Docker Desktop
Navigate to Extensions → Marketplace
Search for “Meshery”
Click Install

Alternative: CLI Installation

docker extension install meshery/docker-extension-meshery

The Docker Extension provides a seamless experience with Meshery embedded directly in Docker Desktop.

Kubernetes

mesheryctl
Helm
Kubectl Manifests

Deploy Meshery on any Kubernetes cluster:

mesheryctl system start --platform kubernetes

Meshery will be deployed in the meshery namespace with all required components.Access Meshery:

kubectl port-forward svc/meshery -n meshery 9081:9081

Then visit http://localhost:9081

Install using Helm charts:

Add Meshery Helm repository

helm repo add meshery https://meshery.io/charts/
helm repo update

Install Meshery

helm install meshery meshery/meshery \
  --namespace meshery \
  --create-namespace

Verify installation

kubectl get pods -n meshery

Expected output:

NAME                                READY   STATUS    RESTARTS   AGE
meshery-7d9f8b8c9d-xxxxx           1/1     Running   0          2m
meshery-broker-0                   1/1     Running   0          2m
meshery-meshsync-xxxxx-xxxxx       1/1     Running   0          2m
meshery-operator-xxxxx-xxxxx       1/1     Running   0          2m

Customize installation:

# Install with specific adapters enabled
helm install meshery meshery/meshery \
  --set meshery-istio.enabled=true \
  --set meshery-linkerd.enabled=true \
  --namespace meshery \
  --create-namespace

Upgrade Meshery:

helm upgrade meshery meshery/meshery \
  --namespace meshery \
  -f values-upgrade.yaml \
  --wait --timeout 10m

Install using raw Kubernetes manifests:

kubectl apply -f https://raw.githubusercontent.com/meshery/meshery/master/install/deployment_yamls/k8s/meshery-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/meshery/meshery/master/install/deployment_yamls/k8s/meshery-service.yaml

This method requires manual configuration of RBAC, service accounts, and persistent volumes.

Cloud Platforms

Amazon EKS
Google GKE
Azure AKS

Deploy Meshery on Amazon EKS:

Configure kubectl for EKS

aws eks update-kubeconfig \
  --region <region> \
  --name <cluster-name>

Install Meshery

mesheryctl system start --platform kubernetes

Or using Helm:

helm install meshery meshery/meshery \
  --namespace meshery \
  --create-namespace

Expose via LoadBalancer (optional)

kubectl patch svc meshery -n meshery \
  -p '{"spec": {"type": "LoadBalancer"}}'

Get the external IP:

kubectl get svc meshery -n meshery

For production deployments, consider using AWS ALB Ingress Controller for HTTPS and domain routing.

Deploy Meshery on Google Kubernetes Engine:

Configure kubectl for GKE

gcloud container clusters get-credentials <cluster-name> \
  --zone <zone> \
  --project <project-id>

Grant cluster-admin permissions

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole=cluster-admin \
  --user=$(gcloud config get-value core/account)

Install Meshery

helm install meshery meshery/meshery \
  --namespace meshery \
  --create-namespace

Expose via LoadBalancer (optional)

kubectl patch svc meshery -n meshery \
  -p '{"spec": {"type": "LoadBalancer"}}'

Deploy Meshery on Azure Kubernetes Service:

Configure kubectl for AKS

az aks get-credentials \
  --resource-group <resource-group> \
  --name <cluster-name>

Install Meshery

helm install meshery meshery/meshery \
  --namespace meshery \
  --create-namespace

Expose via LoadBalancer (optional)

kubectl patch svc meshery -n meshery \
  -p '{"spec": {"type": "LoadBalancer"}}'

Local Kubernetes

Minikube
kind
Docker Desktop

Deploy Meshery on Minikube:

Start Minikube

minikube start --cpus 4 --memory 8192

Install Meshery

mesheryctl system start --platform kubernetes

Access Meshery

minikube service meshery -n meshery

Deploy Meshery on kind (Kubernetes in Docker):

Create kind cluster

kind create cluster --name meshery-cluster

Install Meshery

mesheryctl system start --platform kubernetes

Port forward to access

kubectl port-forward svc/meshery -n meshery 9081:9081

Deploy on Docker Desktop’s Kubernetes:

Enable Kubernetes

Open Docker Desktop
Go to Settings → Kubernetes
Check Enable Kubernetes
Click Apply & Restart

Install Meshery

mesheryctl system start --platform kubernetes

Access Meshery

kubectl port-forward svc/meshery -n meshery 9081:9081

Platform Support Matrix

Platform	Support Status	Installation Method
Docker	✅ Fully Supported	`mesheryctl`, Docker Compose, Docker Extension
Kubernetes	✅ Fully Supported	`mesheryctl`, Helm, kubectl
AKS	✅ Fully Supported	`mesheryctl`, Helm
EKS	✅ Fully Supported	`mesheryctl`, Helm
GKE	✅ Fully Supported	`mesheryctl`, Helm
Minikube	✅ Fully Supported	`mesheryctl`, Helm
kind	✅ Fully Supported	`mesheryctl`, Helm
Docker Desktop	✅ Fully Supported	Docker Extension, `mesheryctl`
OpenShift	✅ Fully Supported	`mesheryctl`, Helm
Rancher	✅ Fully Supported	`mesheryctl`, Helm
macOS	✅ Fully Supported	`mesheryctl`, Homebrew
Linux	✅ Fully Supported	`mesheryctl`
Windows	✅ Fully Supported	`mesheryctl`, Scoop, WSL2
Raspberry Pi	🚧 In Progress	-

Configuration Options

Environment Variables

Meshery can be configured using environment variables:

# Provider configuration
PROVIDER_BASE_URLS=https://cloud.layer5.io

# Port configuration
PORT=9081

# Kubeconfig location
KUBECONFIG_FOLDER=/home/appuser/.kube

# Adapter URLs (optional)
ADAPTER_URLS=meshery-istio:10000 meshery-linkerd:10001

# Event identifier
EVENT=mesheryLocal

Helm Values

Customize Helm deployments with a values.yaml file:

# values.yaml
env:
  PROVIDER_BASE_URLS: "https://cloud.layer5.io"
  
service:
  type: LoadBalancer
  port: 9081

meshery-istio:
  enabled: true
  
meshery-linkerd:
  enabled: true

resources:
  limits:
    cpu: 1000m
    memory: 1024Mi
  requests:
    cpu: 500m
    memory: 512Mi

Install with custom values:

helm install meshery meshery/meshery \
  --namespace meshery \
  --create-namespace \
  -f values.yaml

Post-Installation

Verify Installation

Check component status

mesheryctl system status

Or using kubectl:

kubectl get pods -n meshery

View logs

mesheryctl system logs

Or for specific components:

kubectl logs -n meshery deployment/meshery

Access Meshery UI

Open your browser to http://localhost:9081

Connect Kubernetes Cluster

After installation, connect your Kubernetes cluster:

mesheryctl system context create k8s --set

Or use the UI:

Navigate to Settings → Connections
Click + Connect Cluster
Select your kubeconfig context
Click Connect

Uninstallation

mesheryctl
Docker Compose
Helm

mesheryctl system stop
mesheryctl system reset

docker-compose down -v

helm uninstall meshery --namespace meshery
kubectl delete namespace meshery

Troubleshooting

Installation fails with 'permission denied'

Ensure you have proper permissions:Docker: Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Kubernetes: Verify cluster-admin permissions:

kubectl auth can-i '*' '*' --all-namespaces

Pods stuck in Pending state

Check resource availability:

kubectl describe pod <pod-name> -n meshery

Verify node resources:

kubectl top nodes

Ensure persistent volume claims are bound:

kubectl get pvc -n meshery

Cannot access Meshery UI

Verify service is running:

kubectl get svc meshery -n meshery

Check port forwarding:

kubectl port-forward svc/meshery -n meshery 9081:9081

Verify firewall rules allow port 9081.

Helm installation fails

Update Helm repositories:

helm repo update

Verify Helm version (3.0+ required):

helm version

Check for existing releases:

helm list -n meshery

Installation

Meshery Installation Guide

Prerequisites

System Requirements

Required Software

Quick Installation

Using mesheryctl (Recommended)

Platform-Specific Installation

Docker

Kubernetes

Cloud Platforms

Local Kubernetes

Platform Support Matrix

Configuration Options

Environment Variables

Helm Values

Post-Installation

Verify Installation

Connect Kubernetes Cluster

Uninstallation

Troubleshooting

Next Steps

Quick Start

Architecture

Integrations

CLI Reference

Additional Resources

​Meshery Installation Guide

​Prerequisites

System Requirements

Required Software

​Quick Installation

​Using mesheryctl (Recommended)

​Platform-Specific Installation

​Docker

​Kubernetes

​Cloud Platforms

​Local Kubernetes

​Platform Support Matrix

​Configuration Options

​Environment Variables

​Helm Values

​Post-Installation

​Verify Installation

​Connect Kubernetes Cluster

​Uninstallation

​Troubleshooting

​Next Steps

Quick Start

Architecture

Integrations

CLI Reference

​Additional Resources

Meshery Installation Guide

Prerequisites

Quick Installation

Using mesheryctl (Recommended)

Platform-Specific Installation

Docker

Kubernetes

Cloud Platforms

Local Kubernetes

Platform Support Matrix

Configuration Options

Environment Variables

Helm Values

Post-Installation

Verify Installation

Connect Kubernetes Cluster

Uninstallation

Troubleshooting

Next Steps

Additional Resources