DEV Community

Cover image for Getting Started with PipeCD — Deploy Your First App in 10 Minutes
Harshit Ghagre
Harshit Ghagre

Posted on

Getting Started with PipeCD — Deploy Your First App in 10 Minutes

#cloudnative #cicd #pipecd #devops

Hey folks! In this blog, we are going to set up PipeCD from scratch on our local Linux machine and deploy our first application using it. By the end of this, you will have a working PipeCD setup and a clear picture of how GitOps-style deployments work with PipeCD.

Let's jump right in.

So, What is PipeCD?

Before we touch any commands, let me quickly explain what PipeCD actually is.

PipeCD is a continuous delivery (CD) tool. Its job is to take the code or configuration you push to Git and deploy it to your servers — automatically.

Now, you might be thinking — "we already have Argo CD and Flux for that." And you're right, those are great tools. But here's the thing:

Argo CD and Flux only work with Kubernetes.

PipeCD works with Kubernetes, Terraform, AWS Lambda, Amazon ECS, and Google Cloud Run — all from one single tool. So if your team is using more than just Kubernetes (which most teams do), PipeCD saves you from juggling multiple tools.

PipeCD is also a CNCF Sandbox project, meaning it's backed by the same foundation that manages Kubernetes, Prometheus, and other big projects.

How Does PipeCD Work?

PipeCD has two main parts. Think of it like this:

Control Plane = The Manager

  • This runs the web dashboard
  • It stores all the data about your deployments
  • You install it once and it manages everything

Piped = The Worker (Agent)

  • This is a small agent that runs inside your cluster
  • It watches your Git repo for changes
  • When it detects a change, it deploys the new version

Here's the important part — Piped only makes outbound connections. It calls the Control Plane, the Control Plane never calls Piped. This means your cluster credentials and secrets never leave your environment. Very secure.

PipeCD Architecture

That's it. Let's set it up now.

What You Need (Prerequisites)

We are doing everything on Linux. Before we start, make sure you have these four tools installed:

  • Docker — Runs containers. Minikube needs this to create your local cluster.
  • Minikube — Creates a local Kubernetes cluster on your machine.
  • kubectl — The command-line tool that lets you talk to your Kubernetes cluster.
  • Git — Version control. You probably already have this installed.

Installing Docker

If you don't have Docker yet:

sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER
Enter fullscreen mode Exit fullscreen mode

Important: Log out and log back in after the usermod command so the group change takes effect.

Verify Docker is working:

docker --version
Enter fullscreen mode Exit fullscreen mode

Installing Minikube 

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
rm minikube-linux-amd64
Enter fullscreen mode Exit fullscreen mode

Verify:

minikube version
Enter fullscreen mode Exit fullscreen mode

Installing kubectl 

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install kubectl /usr/local/bin/kubectl
rm kubectl
Enter fullscreen mode Exit fullscreen mode

Verify:

kubectl version --client
Enter fullscreen mode Exit fullscreen mode

Alright, all tools are ready. Let's start building.

Step 1: Start Your Minikube Cluster

First, let's create our local Kubernetes cluster using Minikube.

minikube start --driver=docker --memory=4096 --cpus=2
Enter fullscreen mode Exit fullscreen mode

We are giving it 4GB of RAM and 2 CPUs. PipeCD runs a few services, so it needs a bit of resources.

Once it's done, verify the cluster is running:

kubectl get nodes
Enter fullscreen mode Exit fullscreen mode

You should see something like:

NAME       STATUS   ROLES           AGE   VERSION
minikube   Ready    control-plane   30s   v1.xx.x
Enter fullscreen mode Exit fullscreen mode

Minikube cluster running

If you see Ready, we're good. Let's move on.

Step 2: Install the PipeCD Control Plane

Now let's install the PipeCD Control Plane. This is the "manager" that runs the web UI and keeps track of everything.

PipeCD provides ready-made manifest files for quickstart. We just need to apply them.

Create the namespace first:

kubectl create namespace pipecd
Enter fullscreen mode Exit fullscreen mode

Now install the Control Plane:

kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml
Enter fullscreen mode Exit fullscreen mode

This single command installs everything the Control Plane needs — the server, the database, the cache, all of it.

Wait for the pods to come up:

kubectl -n pipecd get pods -w
Enter fullscreen mode Exit fullscreen mode

You'll see a few pods being created. Wait until all of them show Running status. It usually takes 2-3 minutes. Press Ctrl+C to stop watching once they're all running.

Control Plane pods running

All running? Great. Let's access the dashboard.

Step 3: Access the PipeCD Dashboard

The Control Plane has a web UI. To access it from our browser, we need to forward the port.

kubectl port-forward -n pipecd svc/pipecd 8080 &
Enter fullscreen mode Exit fullscreen mode

The & at the end runs it in the background so you can keep using the terminal.

Now open your browser and go to:

http://localhost:8080?project=quickstart
Enter fullscreen mode Exit fullscreen mode

You'll see the PipeCD login page.

PipeCD login page

Login with these quickstart credentials — Project: quickstart, Username: hello-pipecd, Password: hello-pipecd

Once you log in, you'll see the PipeCD dashboard. It's clean and simple — you'll see sections for Applications, Deployments, and more.

PipeCD dashboard

Take a moment to look around. This is where you'll see all your deployments happening in real time later.

Step 4: Install the Piped Agent

The Control Plane is the manager, but it doesn't deploy anything by itself. We need the Piped agent (the worker) to do the actual deploying.

First, apply the piped manifest:

kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml
Enter fullscreen mode Exit fullscreen mode

Now here's the important part that trips up most people — the piped manifest ships with placeholder values for the piped ID and key. You need to register the piped through the UI first.

Go to the PipeCD dashboard → click Settings (bottom-left gear icon) → go to the Piped tab → click + ADD. Give it a name like quickstart-piped and click Save.

You'll see a popup with three values — Piped ID, Piped Key, and Base64 Encoded Piped Key. Copy the Piped ID and the Base64 Encoded Piped Key (the third field). Save them somewhere — you won't see the key again.

Now update the piped's configmap with your actual values:

kubectl edit configmap piped -n pipecd
Enter fullscreen mode Exit fullscreen mode

Find the pipedID and pipedKeyData fields and replace the placeholders with the values you just copied. The pipedKeyData field expects the Base64 Encoded Piped Key (the third field from the popup). Save the file and restart the piped:

kubectl delete pod -n pipecd -l app.kubernetes.io/name=piped
Enter fullscreen mode Exit fullscreen mode

Wait for the new pod to start:

kubectl -n pipecd get pods -w
Enter fullscreen mode Exit fullscreen mode

You should see the piped pod in Running status with 1/1 ready.

All pods including piped running

Go back to the PipeCD dashboard → Settings → Piped tab. You should see your piped showing a green connected status. That means the agent is now watching for changes and ready to deploy.

Step 5: Understanding the GitOps Flow

Now before we deploy anything, let me explain what happens behind the scenes. This is important — don't skip this part.

In PipeCD, every application has two things in Git:

1. app.pipecd.yaml — This is the PipeCD configuration file. It tells PipeCD what kind of app this is and how to deploy it.

Here's a simple example:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: my-app
  pipeline:
    stages:
      - name: K8S_PRIMARY_ROLLOUT
        desc: Deploy the new version
Enter fullscreen mode Exit fullscreen mode

This is saying: "Hey PipeCD, this is a Kubernetes app. Deploy it using a rolling update."

2. Your Kubernetes manifests — These are your regular deployment, service, configmap files. Nothing special here. Just the normal YAML files you already know.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: nginx:1.25
          ports:
            - containerPort: 80
Enter fullscreen mode Exit fullscreen mode

When you push a change to either of these files — for example, changing the image from nginx:1.25 to nginx:1.26 — Piped will detect the change and deploy it automatically.

You don't run any deploy commands. You just push to Git. PipeCD does the rest.

That's the whole idea of GitOps.

Step 6: Deploy Your First Application

Now let's actually deploy something. The piped is already configured to watch the pipe-cd/examples Git repository, which has sample applications ready to go.

Go to the PipeCD dashboard and click Applications in the top navigation. Then click + ADD.

You'll see a panel with tabs at the top. Click "PIPED V0 ADD FROM SUGGESTIONS" — this shows all the applications the piped has discovered from the examples repository. You should see around 55 apps listed.

Pick kubernetes/simple from the list and click Save.

Go back to the Applications tab. You'll see your new application listed there. Click on it.

PipeCD will automatically trigger an initial deployment. You can watch each stage of the pipeline execute one by one — it's like watching a CI/CD pipeline run, but for deployments.

Once the deployment finishes, you'll see green checkmarks on all stages. Your application is now deployed to your cluster.

You can verify it in your terminal too:

kubectl get deployments -A
kubectl get pods -A
Enter fullscreen mode Exit fullscreen mode

You should see the sample application pods running alongside the PipeCD pods.

If something goes wrong during deployment, PipeCD will automatically rollback to the previous working version. You don't have to do anything.

What Makes PipeCD Special?

After setting it up, here's what I think stands out:

1. Works with more than just Kubernetes.
Terraform, Lambda, ECS, Cloud Run — one tool handles all of them. You don't need Argo CD for Kubernetes AND a separate tool for Terraform.

2. Your secrets stay safe.
The Piped agent only makes outbound calls. Your cloud credentials never leave your cluster. This is a big deal for security.

3. Deployment strategies are built in.
Canary deployments, blue-green deployments, automated analysis — you just configure them in the app.pipecd.yaml file. No extra tools needed.

4. Drift detection.
If someone manually changes something in your cluster (like editing a deployment with kubectl edit), PipeCD catches it. It shows you exactly what drifted from your Git state.

5. The UI is really clean.
You can see your deployment pipelines, logs, application state, and history — all in one place. No clicking through 10 different pages.

PipeCD Applications view

PipeCD deployment pipeline

PipeCD application details

PipeCD live state

Cleanup

Once you're done playing around, clean everything up:

# Stop the port-forward
kill %1

# Delete PipeCD resources
kubectl delete -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml
kubectl delete -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml
kubectl delete namespace pipecd

# Stop and delete the Minikube cluster
minikube stop
minikube delete
Enter fullscreen mode Exit fullscreen mode

Everything gone. Clean system.

Where to Go From Here?

If you want to dig deeper, here are some useful links:

Wrapping Up

PipeCD is one of those tools that just makes sense once you use it. It does continuous delivery for Kubernetes, Terraform, Lambda, ECS, and Cloud Run — all from one platform. The security model is solid, the UI is clean, and the GitOps workflow just works.

Happy deploying! 🚀

PipeCD v0.56.0 was recently released with improvements to pipectl and deployment workflows. Check out the release notes.

Tags: #gitops #kubernetes #devops #cicd #pipecd #cncf #cloudnative #linux

Top comments (0)