From d9e4754e80316a54586d6fe4a419c4db266c510e Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Mon, 6 Jul 2026 00:06:40 +0530 Subject: [PATCH] improve quickstart wording Signed-off-by: rahulshendre --- docs/content/en/docs-dev/quickstart/_index.md | 107 ++++++++++-------- .../en/docs-v0.57.x/quickstart/_index.md | 107 ++++++++++-------- 2 files changed, 114 insertions(+), 100 deletions(-) diff --git a/docs/content/en/docs-dev/quickstart/_index.md b/docs/content/en/docs-dev/quickstart/_index.md index e3b84ebd8a..560f4c96b3 100644 --- a/docs/content/en/docs-dev/quickstart/_index.md +++ b/docs/content/en/docs-dev/quickstart/_index.md @@ -6,93 +6,98 @@ description: > This page describes how to quickly get started with PipeCD on Kubernetes. --- -PipeCD is constructed by two components: the Control plane and the piped (agent) (ref: [PipeCD concepts](../concepts/)). The control plane can be thought of as a regular web service application that can be installed anywhere, while the piped agent is a single binary that can run as a pod in a Kubernetes cluster, a container on ECS, a serverless function like Lambda, Cloud Run, or a process running directly on your local machine. +PipeCD consists of two components: the Control Plane and the piped agent (see [PipeCD concepts](../concepts/)). The Control Plane is a regular web service application that can be installed anywhere, while the piped agent is a single binary that can run as a pod in a Kubernetes cluster, a container on ECS, a serverless function on Lambda or Cloud Run, or a process running directly on your local machine. -This page is a guideline for installing PipeCD (both two components) into your Kubernetes cluster and deploying a "hello world" application to that same Kubernetes cluster. +This page walks you through installing both components 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. -- 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). +> **Note:** +> - You don't need to install the PipeCD Control Plane on the cluster where your applications are running. See this [blog post](/blog/2021/12/29/pipecd-best-practice-01-operate-your-own-pipecd-cluster/) to understand how PipeCD is operated 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/). +- A running Kubernetes cluster, such as [minikube](https://minikube.sigs.k8s.io/docs/start/) or [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed and connected to the cluster. ### 1. Installing PipeCD in quickstart mode -Across the [PipeCD concepts](/docs/concepts/), PipeCD platform is constructed by 2 components: Control Plane and Piped (the agent). - #### 1.1. Installing PipeCD Control Plane -```console -$ kubectl create namespace pipecd -$ kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml +```bash +kubectl create namespace pipecd +kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml ``` -The PipeCD control plane will be installed with a default project named `quickstart`. To access the PipeCD Control Plane UI, run the following command +The Control Plane pods pull their container images on the first run, which can take a few minutes. Wait until all pods are `1/1 Running` with `kubectl get pod -n pipecd`. + +The PipeCD Control Plane is installed with a default project named `quickstart`. To access the PipeCD console, run: -```console -$ kubectl port-forward -n pipecd svc/pipecd 8080 +```bash +kubectl port-forward -n pipecd svc/pipecd 8080 ``` -You can access the PipeCD console at [http://localhost:8080?project=quickstart](http://localhost:8080?project=quickstart) +You can access the PipeCD console at [http://localhost:8080?project=quickstart](http://localhost:8080?project=quickstart). For this quickstart setup, the project name is fixed to `quickstart`. If you open `http://localhost:8080` directly, enter `quickstart` on the login screen. -To login, you can use the configured static admin account as below: -- username: `hello-pipecd` -- password: `hello-pipecd` +To log in, use the configured static admin account: +- **username**: `hello-pipecd` +- **password**: `hello-pipecd` -And you will access the main page of PipeCD Control Plane console, which looks like this +After logging in, you will see the main page of the PipeCD console, which looks like this: ![](/images/pipecd-control-plane-mainpage.png) -For more about PipeCD control plane management, please check [Managing ControlPlane](/docs/user-guide/managing-controlplane/). +For more about PipeCD Control Plane management, see [Managing ControlPlane](../user-guide/managing-controlplane/). #### 1.2. Installing Piped -Next, in order to perform CD tasks, you need to install a Piped agent to the cluster. +Next, install a piped agent to the cluster to perform CD tasks. -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). +From your logged in tab, navigate to the piped settings page at [http://localhost:8080/settings/piped?project=quickstart](http://localhost:8080/settings/piped?project=quickstart). -You will find the `+ADD` button around the top left of this page, click there and insert information to register the Piped agent (for example, `dev`). +Click the `+ADD` button at the top left of the page and enter a name for the piped agent (for example, `dev`). ![](/images/quickstart-adding-piped.png) -Click on the `Save` button, and then you can see the piped-id and secret-key. +Click the `Save` button, and then you can see the generated piped ID and secret key. ![](/images/quickstart-piped-registered.png) -You need to copy two values, `Piped Id` and `Base64 Encoded Piped Key`, and fill in `` and `` respectively this below command +> **Note:** The `Piped Id` is the UUID generated after you click `Save` (for example, `7c17c8f8-...`), not the name you entered while registering. Using the name instead of the UUID causes an `unable to find piped from datastore` error in the piped logs. -```console -$ curl -s https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml | \ +Copy the two values, `Piped Id` and `Base64 Encoded Piped Key`, and fill them in `` and `` respectively in the command below: + +```bash +curl -s https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml | \ sed -e 's///g' \ -e 's///g' | \ kubectl apply -n pipecd -f - ``` -For more about Piped management, please check [Managing Piped](/docs/user-guide/managing-piped/). +For more about Piped management, see [Managing Piped](../user-guide/managing-piped/). 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 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 +You can check the readiness of all PipeCD components via command: + +```bash +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 0 38m +piped-8477b5d55d-74s5v 1/1 Running 0 97s ``` ### 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. +Your PipeCD installation (both Control Plane and agent) is now complete. Let's use it to deploy your first Kubernetes application with PipeCD. Navigate to the `Applications` page, click on the `+ADD` button on the top left corner. @@ -100,25 +105,27 @@ Go to the `ADD FROM SUGGESTIONS` tab, then select: - Piped that you have just registered (e.g. `dev`) - PlatformProvider: `kubernetes-default` -You should see a lot of suggested applications. Select one of listed applications and click the `SAVE` button to register. +> **Note:** The piped agent needs a minute or two after connecting to clone the examples repository and discover applications. If the list is empty, wait a moment and reload the page. + +You should see a list of suggested applications. Select one and click the `SAVE` button to register it. ![](/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. +The first deployment starts automatically and syncs the application to the state specified in the current Git commit. ![](/images/quickstart-first-deployment.png) -For more about managing applications' deployment with PipeCD, refer to [Managing application](/docs/user-guide/managing-application/) +For more about managing applications' deployment with PipeCD, see [Managing application](../user-guide/managing-application/). ### 3. Cleanup -When you’re finished experimenting with PipeCD quickstart mode, you can uninstall it using: +When you're finished experimenting with PipeCD quickstart mode, you can uninstall it using: -``` console -$ kubectl delete ns pipecd +```bash +kubectl delete ns pipecd ``` ### What's next? -To prepare your PipeCD for a production environment, please visit the [Installation](../installation/) guideline. For guidelines to use PipeCD to deploy your application in daily usage, please visit the [User guide](../user-guide/) docs. +To prepare your PipeCD for a production environment, see the [Installation](../installation/) guide. For guidelines to use PipeCD to deploy your application in daily usage, see the [User guide](../user-guide/) docs. -To set up the development environment and start contributing to PipeCD, please visit the [Contributor guide](../contribution-guidelines/) docs. +To set up the development environment and start contributing to PipeCD, see the [Contributor guide](../contribution-guidelines/) docs. diff --git a/docs/content/en/docs-v0.57.x/quickstart/_index.md b/docs/content/en/docs-v0.57.x/quickstart/_index.md index e3b84ebd8a..560f4c96b3 100644 --- a/docs/content/en/docs-v0.57.x/quickstart/_index.md +++ b/docs/content/en/docs-v0.57.x/quickstart/_index.md @@ -6,93 +6,98 @@ description: > This page describes how to quickly get started with PipeCD on Kubernetes. --- -PipeCD is constructed by two components: the Control plane and the piped (agent) (ref: [PipeCD concepts](../concepts/)). The control plane can be thought of as a regular web service application that can be installed anywhere, while the piped agent is a single binary that can run as a pod in a Kubernetes cluster, a container on ECS, a serverless function like Lambda, Cloud Run, or a process running directly on your local machine. +PipeCD consists of two components: the Control Plane and the piped agent (see [PipeCD concepts](../concepts/)). The Control Plane is a regular web service application that can be installed anywhere, while the piped agent is a single binary that can run as a pod in a Kubernetes cluster, a container on ECS, a serverless function on Lambda or Cloud Run, or a process running directly on your local machine. -This page is a guideline for installing PipeCD (both two components) into your Kubernetes cluster and deploying a "hello world" application to that same Kubernetes cluster. +This page walks you through installing both components 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. -- 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). +> **Note:** +> - You don't need to install the PipeCD Control Plane on the cluster where your applications are running. See this [blog post](/blog/2021/12/29/pipecd-best-practice-01-operate-your-own-pipecd-cluster/) to understand how PipeCD is operated 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/). +- A running Kubernetes cluster, such as [minikube](https://minikube.sigs.k8s.io/docs/start/) or [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed and connected to the cluster. ### 1. Installing PipeCD in quickstart mode -Across the [PipeCD concepts](/docs/concepts/), PipeCD platform is constructed by 2 components: Control Plane and Piped (the agent). - #### 1.1. Installing PipeCD Control Plane -```console -$ kubectl create namespace pipecd -$ kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml +```bash +kubectl create namespace pipecd +kubectl apply -n pipecd -f https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/control-plane.yaml ``` -The PipeCD control plane will be installed with a default project named `quickstart`. To access the PipeCD Control Plane UI, run the following command +The Control Plane pods pull their container images on the first run, which can take a few minutes. Wait until all pods are `1/1 Running` with `kubectl get pod -n pipecd`. + +The PipeCD Control Plane is installed with a default project named `quickstart`. To access the PipeCD console, run: -```console -$ kubectl port-forward -n pipecd svc/pipecd 8080 +```bash +kubectl port-forward -n pipecd svc/pipecd 8080 ``` -You can access the PipeCD console at [http://localhost:8080?project=quickstart](http://localhost:8080?project=quickstart) +You can access the PipeCD console at [http://localhost:8080?project=quickstart](http://localhost:8080?project=quickstart). For this quickstart setup, the project name is fixed to `quickstart`. If you open `http://localhost:8080` directly, enter `quickstart` on the login screen. -To login, you can use the configured static admin account as below: -- username: `hello-pipecd` -- password: `hello-pipecd` +To log in, use the configured static admin account: +- **username**: `hello-pipecd` +- **password**: `hello-pipecd` -And you will access the main page of PipeCD Control Plane console, which looks like this +After logging in, you will see the main page of the PipeCD console, which looks like this: ![](/images/pipecd-control-plane-mainpage.png) -For more about PipeCD control plane management, please check [Managing ControlPlane](/docs/user-guide/managing-controlplane/). +For more about PipeCD Control Plane management, see [Managing ControlPlane](../user-guide/managing-controlplane/). #### 1.2. Installing Piped -Next, in order to perform CD tasks, you need to install a Piped agent to the cluster. +Next, install a piped agent to the cluster to perform CD tasks. -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). +From your logged in tab, navigate to the piped settings page at [http://localhost:8080/settings/piped?project=quickstart](http://localhost:8080/settings/piped?project=quickstart). -You will find the `+ADD` button around the top left of this page, click there and insert information to register the Piped agent (for example, `dev`). +Click the `+ADD` button at the top left of the page and enter a name for the piped agent (for example, `dev`). ![](/images/quickstart-adding-piped.png) -Click on the `Save` button, and then you can see the piped-id and secret-key. +Click the `Save` button, and then you can see the generated piped ID and secret key. ![](/images/quickstart-piped-registered.png) -You need to copy two values, `Piped Id` and `Base64 Encoded Piped Key`, and fill in `` and `` respectively this below command +> **Note:** The `Piped Id` is the UUID generated after you click `Save` (for example, `7c17c8f8-...`), not the name you entered while registering. Using the name instead of the UUID causes an `unable to find piped from datastore` error in the piped logs. -```console -$ curl -s https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml | \ +Copy the two values, `Piped Id` and `Base64 Encoded Piped Key`, and fill them in `` and `` respectively in the command below: + +```bash +curl -s https://raw.githubusercontent.com/pipe-cd/pipecd/master/quickstart/manifests/piped.yaml | \ sed -e 's///g' \ -e 's///g' | \ kubectl apply -n pipecd -f - ``` -For more about Piped management, please check [Managing Piped](/docs/user-guide/managing-piped/). +For more about Piped management, see [Managing Piped](../user-guide/managing-piped/). 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 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 +You can check the readiness of all PipeCD components via command: + +```bash +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 0 38m +piped-8477b5d55d-74s5v 1/1 Running 0 97s ``` ### 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. +Your PipeCD installation (both Control Plane and agent) is now complete. Let's use it to deploy your first Kubernetes application with PipeCD. Navigate to the `Applications` page, click on the `+ADD` button on the top left corner. @@ -100,25 +105,27 @@ Go to the `ADD FROM SUGGESTIONS` tab, then select: - Piped that you have just registered (e.g. `dev`) - PlatformProvider: `kubernetes-default` -You should see a lot of suggested applications. Select one of listed applications and click the `SAVE` button to register. +> **Note:** The piped agent needs a minute or two after connecting to clone the examples repository and discover applications. If the list is empty, wait a moment and reload the page. + +You should see a list of suggested applications. Select one and click the `SAVE` button to register it. ![](/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. +The first deployment starts automatically and syncs the application to the state specified in the current Git commit. ![](/images/quickstart-first-deployment.png) -For more about managing applications' deployment with PipeCD, refer to [Managing application](/docs/user-guide/managing-application/) +For more about managing applications' deployment with PipeCD, see [Managing application](../user-guide/managing-application/). ### 3. Cleanup -When you’re finished experimenting with PipeCD quickstart mode, you can uninstall it using: +When you're finished experimenting with PipeCD quickstart mode, you can uninstall it using: -``` console -$ kubectl delete ns pipecd +```bash +kubectl delete ns pipecd ``` ### What's next? -To prepare your PipeCD for a production environment, please visit the [Installation](../installation/) guideline. For guidelines to use PipeCD to deploy your application in daily usage, please visit the [User guide](../user-guide/) docs. +To prepare your PipeCD for a production environment, see the [Installation](../installation/) guide. For guidelines to use PipeCD to deploy your application in daily usage, see the [User guide](../user-guide/) docs. -To set up the development environment and start contributing to PipeCD, please visit the [Contributor guide](../contribution-guidelines/) docs. +To set up the development environment and start contributing to PipeCD, see the [Contributor guide](../contribution-guidelines/) docs.