# Install PipeCD locally using Kind This guide walks you through installing and running PipeCD locally using Kind, covering the essential steps to get a working Kubernetes cluster and PipeCD setup for local experimentation. ## Big picture This guide walks you through setting up a local PipeCD development environment using Kind (Kubernetes in Docker). The goal is to get PipeCD running on your machine in a way that's simple and that you can catch up quickly with PipeCD. By the end of this guide, you will have: - a working Kubernetes cluster running in Docker - Calico installed and providing cluster networking - the PipeCD control plane running - a connected piped agent ready to deploy applications This setup typically takes 20–30 minutes, depending on your system and network speed. ## Value Use this guide if you want to: - try PipeCD locally without cloud infrastructure - understand how PipeCD components fit together - experiment safely before moving to production This is not a production setup. For production environments, refer to the official PipeCD deployment guides. ## Before you begin ### Required You'll need a Linux machine with: * Docker installed and running * At least 2 CPUs (4+ recommended) * 8GB RAM recommended * ~10GB free disk space Or run Linux in a virtual environment(VM) ## Tools Make sure the following tools are available: ``` docker --version kubectl version --client kind version ``` If any of these commands fail, you need to install the missing tool before continuing[1]. ### Resources[1]: https://docs.docker.com/engine/install/ https://kind.sigs.k8s.io/ https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/ ## Concepts ### Why Kind? Kind runs Kubernetes inside Docker containers. It's lightweight, fast to reset, and ideal for local development. ### Why Calico? PipeCD expects a properly configured Kubernetes network. Calico is a widely used CNI that works well with Kind and closely resembles real-world setups. In this guide, we explicitly install Calico instead of relying on Kind's default networking. ## How to ### Create a Kubernetes cluster with Kind We'll start by creating a multi-node cluster: one control plane and two workers. ### Create a Kind configuration file You can create this file in the home directory or whichever directory you would like to(current development working directory); ``` # kind-config.yaml kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane - role: worker - role: worker networking: disableDefaultCNI: true ``` We disable the default CNI so we can install Calico ourselves. ### Create the cluster ``` kind create cluster --name mycluster --config kind-config.yaml ``` Verify the cluster is reachable: ```yaml kubectl cluster-info kubectl get nodes ``` At this point, nodes may show NotReady. This is expected until networking is installed. ## Install Calico Next, install Calico to provide pod networking. ``` kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml ``` Watch the rollout: ``` kubectl get pods -n kube-system -w ``` You'll see Calico pods initializing. This can take a few minutes. Confirm Calico is running ``` kubectl get pods -n kube-system ``` Wait until: - all `calico-node` pods are `Running` - `calico-kube-controllers` is `Running` - `coredns` pods are `Running` Then confirm node readiness: ``` kubectl get nodes ``` All nodes should now be `Ready`. > Note: > If your Kubernetes nodes are not in the Ready state, stop here. > Fix networking (probably Calico or any other CNI) before installing PipeCD. > PipeCD depends on a healthy cluster and will not work correctly otherwise. ## Create the PipeCD namespace ``` kubectl create namespace pipecd ``` ## Deploy the PipeCD control plane PipeCD provides a Quickstart manifest that deploys all required components. ``` kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml ``` Watch the pods: ``` kubectl get pods -n pipecd -w ``` Wait until all PipeCD pods are in the `Running` state. ## Access the PipeCD Web UI Forward the service locally: ``` kubectl port-forward -n pipecd svc/pipecd 8080:80 ``` Open your browser and visit: ``` http://localhost:8080?project=quickstart ``` You should now see the PipeCD UI. ![PipeCD login screen display](https://hackmd.io/_uploads/HkoCnL_Pbl.png) ## Create and register a Piped agent PipeCD uses piped as the agent that runs inside your cluster and executes deployments. ### Create a `Piped` in the UI In the PipeCD UI: * Go to Settings → Piped * Create a new Piped * Copy the generated: * Piped ID * Piped Key (base64 encoded) Example values (for illustration only): ``` PIPED_ID=piped-sample-123 PIPED_KEY=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t... ``` ## Deploy Piped to the cluster Export your values: ``` export PIPED_ID="piped-sample-123" export PIPED_KEY="LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t..." ``` Another approach is, you can explicitly insert your key secrets directly into the command as shown below after the first approach. Apply the Piped manifest, replacing placeholders using `sed`: ``` curl -s https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml | \ sed -e "s/<YOUR_PIPED_ID>/${PIPED_ID}/g" \ -e "s/<YOUR_PIPED_KEY_DATA>/${PIPED_KEY}/g" | \ kubectl apply -n pipecd -f - #Or you can directly insert your secrets inside the command this way curl -s https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml | \ sed -e "s/<YOUR_PIPED_ID>/piped-sample-123/g" \ -e "s/<YOUR_PIPED_KEY_DATA>/LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t/g" | \ kubectl apply -n pipecd -f - ``` This command: * downloads the manifest * injects your `Piped` credentials * applies it directly to the cluster ## Verify Piped is running ``` kubectl get pods -n pipecd ``` You should see a `piped` pod in the `Running` state. In the PipeCD UI, the Piped should now appear as Connected(Denoted by the blue dot after the title name). ![PipeCD quickstart UI dashboard page](https://hackmd.io/_uploads/SkVw0IuDWe.png) ## Final checks Before considering the setup complete, verify: ``` kubectl get nodes kubectl get pods -A kubectl get pods -n pipecd ``` All components should be healthy(Running). ![PipeCD components state](https://hackmd.io/_uploads/HJl2AIOPWl.png) ## Cleanup When you're done, you can safely tear down the cluster to free system resources and avoid state-related issues. To delete the Kind cluster run: ``` kind delete cluster --name mycluster ``` ## What's next? To prepare your PipeCD for a production environment, please visit the [Installation guideline](https://pipecd.dev/docs-v0.55.x/installation/). For guidelines to use PipeCD to deploy your application in daily usage, please visit the [User guide docs](https://pipecd.dev/docs-v0.55.x/user-guide/).