Quickstart

This page describes how to quickly get started with PipeCD on Kubernetes.

This page is a guideline for installing PipeCD into your Kubernetes cluster and deploying a “hello world” application to that same Kubernetes cluster.

Note: It’s not required to install the PipeCD control plane to the cluster where your applications are running. Please read this blog post to understand more about PipeCD in real life use cases.

Prerequisites

  • Having a Kubernetes cluster and connect to it via kubectl.
  • Forked the Examples repository

1. Installing PipeCD client

The official PipeCD client named pipectl can be installed using the following command

# OS="darwin" or "linux"
curl -Lo ./pipectl https://github.com/pipe-cd/pipecd/releases/download/v0.40.1/pipectl_v0.40.1_{OS}_amd64

Then make the pipectl binary executable

chmod +x ./pipectl

You can also move the pipectl binary to the $PATH for later use

sudo mv ./pipectl /usr/local/bin/pipectl

2. Installing PipeCD’s component with pipectl

We can simply use pipectl quickstart command to start the PipeCD installation process and follow the instruction

pipectl quickstart --version v0.40.1

Follow the instruction, the PipeCD control plane will be available at http://localhost:8080 and pipectl command will open the PipeCD console automatically on your browser.

To login, you can use the configured static admin account as below:

  • username: hello-pipecd
  • password: hello-pipecd

After logged in successfully, the browser will redirect you to the PipeCD console settings page at piped settings tab. You will find the +ADD button on the top of this page, click there and insert information to register the deployment runner for PipeCD (called piped).

Click on the Save button, and then you can see the piped-id and secret-key. Be sure to keep a copy for later use.

Use the above value to fill the form showing in the terminal you run pipectl quickstart command

...
Fill up your registered Piped information:
✔ ID: 2bf655c6-d7a8-4b97-8480-43fb0155539e█
Key: 02s3b0b6bo07kvzr8662tke4i292uo5n8w1x9pn8q9rww5lk0b
GitRemoteRepo: https://github.com/{FORKED_GITHUB_ORG}/examples.git

That’s all!

Note: The pipectl quickstart command will keep running to expose your PipeCD console on localhost:8080. If you stop the process, the installed PipeCD components will not lost, you can access to the PipeCD console anytime using kubectl port-forward command

kubectl -n pipecd port-forward svc/pipecd 8080

3. Registering a kubernetes application

Navigate to the Applications page, click on the ADD button on the top left corner.

Go to the ADD FROM SUGGESTIONS tab, then select:

  • Piped: dev (you just registered)
  • PlatformProvider: kubernetes-default

You should see a lot of suggested applications. Select the canary application and click the SAVE button to register.

After a bit, the first deployment would be complete automatically to sync the application to the state specified in the current Git commit.

4. Let’s deploy!

Let’s get started with deployment! All you have to do is to make a PR to update the image tag, scale the replicas, or change the manifests.

For instance, open the kubernetes/canary/deployment.yaml under the forked examples' repository, then change the tag from v0.1.0 to v0.2.0.

After a short wait, a new deployment will be started to update to v0.2.0.

5. Cleanup

When you’re finished experimenting with PipeCD, you can uninstall with:

pipectl quickstart --uninstall

What’s next?

To prepare your PipeCD for a production environment, please visit the Installation guideline. For guidelines to use PipeCD to deploy your application in daily usage, please visit the User guide docs.


Last modified December 1, 2022: Fix comment in docs (#4035) (fa73262a)