Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Make new quickstart guideline official docs #5185

Merged
merged 1 commit into from
Sep 4, 2024
Merged

Make new quickstart guideline official docs #5185

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 42 additions & 68 deletions docs/content/en/docs-v0.48.x/quickstart/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,135 +8,109 @@ description: >

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](/blog/2021/12/29/pipecd-best-practice-01-operate-your-own-pipecd-cluster/) to understand more about PipeCD in real life use cases.
Note:

Note: If you want to experiment with PipeCD freely or don't have a Kubernetes cluster, we recommend [this Tutorial](https://github.com/pipe-cd/tutorial).
- It's not required to install the PipeCD control plane to the cluster where your applications are running. Please read this [blog post](/blog/2021/12/29/pipecd-best-practice-01-operate-your-own-pipecd-cluster/) to understand more about PipeCD in real life use cases.
- If you want to experiment with PipeCD freely or don't have a Kubernetes cluster, we recommend [this Tutorial](https://github.com/pipe-cd/tutorial).

### Prerequisites
- Having a Kubernetes cluster and connect to it via [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
- Forked the [Examples](https://github.com/pipe-cd/examples) repository
- Prepare for authentication to [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry).

### 1. Installing PipeCD in quickstart mode

#### 1.1. Installing PipeCD client
Across the [PipeCD concepts](/docs/concepts/), PipeCD platform is constructed by 2 components: Control Plane and Piped (the agent).

##### Method 1: Official Installation
The official PipeCD client named `pipectl` can be installed using the following command

``` console
# OS="darwin" or "linux"
curl -Lo ./pipectl https://github.com/pipe-cd/pipecd/releases/download/{{< blocks/latest_version >}}/pipectl_{{< blocks/latest_version >}}_{OS}_amd64
```

Then make the pipectl binary executable

``` console
chmod +x ./pipectl
```

You can also move the pipectl binary to the $PATH for later use
#### 1.1. Installing PipeCD Control Plane

```console
sudo mv ./pipectl /usr/local/bin/pipectl
$ kubectl create namespace pipecd
$ kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml
```

##### Method 2: [Asdf](https://asdf-vm.com/) Supported Installation
The PipeCD control plane will be installed with a default project named `quickstart`. To access the PipeCD Control Plane UI, run the following command

```console
asdf plugin add pipectl && asdf install pipectl latest && asdf global pipectl latest
$ kubectl port-forward -n pipecd svc/pipecd 8080
```

##### Method 3: [aqua](https://aquaproj.github.io/) Supported Installation

```console
aqua g -i pipe-cd/pipecd/pipectl && aqua i
```
You can access the PipeCD console at [http://localhost:8080?project=quickstart](http://localhost:8080?project=quickstart)

##### Method 4: [Homebrew](https://brew.sh/) Supported Installation

```console
brew install pipe-cd/tap/pipectl
```
To login, you can use the configured static admin account as below:
- username: `hello-pipecd`
- password: `hello-pipecd`

#### 1.2. Installing PipeCD's components
And you will access the main page of PipeCD Control Plane console, which looks like this

We can simply use __pipectl quickstart__ command to start the PipeCD installation process and follow the instruction
![](/images/pipecd-control-plane-mainpage.png)

```console
pipectl quickstart --version {{< blocks/latest_version >}}
```
For more about PipeCD control plane management, please check [Managing ControlPlane](/docs/user-guide/managing-controlplane/).

Follow the instruction, the PipeCD control plane will be installed with a default project named `quickstart`. You can access to the PipeCD console at [http://localhost:8080](http://localhost:8080?project=quickstart) and pipectl command will open the PipeCD console automatically in your browser.
#### 1.2. Installing Piped

To login, you can use the configured static admin account as below:
- username: `hello-pipecd`
- password: `hello-pipecd`
Next, in order to perform CD tasks, you need to install a Piped agent to the cluster.

![](/images/quickstart-login-form.png)
From your logged in tab, navigate to the PipeCD setting page at [http://localhost:8080/settings/piped?project=quickstart](http://localhost:8080/settings/piped?project=quickstart).

After successfully logging in, the browser will redirect you to the PipeCD console settings page at the `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`).
You will find the `+ADD` button around the top left of this page, click there and insert information to register the `piped`.

![](/images/quickstart-adding-piped.png)

Click on the `Save` button, and then you can see the piped-id and secret-key.

![](/images/quickstart-piped-registered.png)

Use the above value to fill the form showing on the terminal you run __pipectl quickstart__ command
You need to copy two values, `Piped Id` and `Base64 Encoded Piped Key`, and fill in `<COPIED_PIPED_ID>` and `<COPIED_ENCODED_PIPED_KEY>` respectively this below command

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

$ curl -s https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml | \
sed -e 's/<YOUR_PIPED_ID>/<COPIED_PIPED_ID>/g' \
-e 's/<YOUR_PIPED_KEY_DATA>/<COPIED_ENCODED_PIPED_KEY>/g' | \
kubectl apply -n pipecd -f -
```

That's all!
For more about Piped management, please check [Managing Piped](/docs/user-guide/managing-piped/).

Note: The __pipectl quickstart__ command will run continuously to expose your PipeCD console on `localhost:8080`. If you stop the process, the installed PipeCD components will not be lost, you can access to the PipeCD console anytime using __kubectl port-forward__ command
That's all! You are ready to use PipeCD to manage your application's deployment.

You can check the readiness of all PipeCD components via command

```console
kubectl -n pipecd port-forward svc/pipecd 8080
$ kubectl get pod -n pipecd
NAME READY STATUS RESTARTS AGE
pipecd-cache-56c7c65ddc-xqcst 1/1 Running 0 38m
pipecd-gateway-58589b55f9-9nbrv 1/1 Running 0 38m
pipecd-minio-677999d5bb-xnb78 1/1 Running 0 38m
pipecd-mysql-6fff49fbc7-hkvt4 1/1 Running 0 38m
pipecd-ops-779d6844db-nvbwn 1/1 Running 0 38m
pipecd-server-5769df7fcb-9hc45 1/1 Running 1 (38m ago) 38m
piped-8477b5d55d-74s5v 1/1 Running 0 97s
```

### 2. Deploy a kubernetes application with PipeCD
### 2. Deploy a Kubernetes application with PipeCD

Above is all that is necessary to set up your own PipeCD (both control plane and agent), let's use the installed one to deploy your first Kubernetes application with PipeCD.

#### 2.1. 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.
You should see a lot of suggested applications. Select one of listed applications and click the `SAVE` button to register.

![](/images/quickstart-adding-application-from-suggestions.png)

After a bit, the first deployment is complete and will automatically sync the application to the state specified in the current Git commit.

![](/images/quickstart-first-deployment.png)

#### 2.2. 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`.

![](/images/quickstart-update-image-tag.png)

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

![](/images/quickstart-deploying.png)
For more about manage applications' deployment with PipeCD, referrence to [Managing application](/docs/user-guide/managing-application/)

### 3. Cleanup
When you’re finished experimenting with PipeCD quickstart mode, you can uninstall it using:

``` console
pipectl quickstart --uninstall
$ kubectl delete ns pipecd
```

### What's next?
Expand Down
Loading