PipeCD's components with roles
-Basically, there are two types of users/roles that exist in the PipeCD system, which are: +Basically, there are two types of users/roles that exist in the PipeCD system: -- Developers/Production team: Users who use PipeCD to manage their applications’ deployments. You will interact with Piped and may or may not need to install Piped by yourself. +- Developers/Production team: Users who use PipeCD to manage their applications' deployments. You will interact with `piped` and may or may not need to install `piped` by yourself. -- Operators/Platform team: Users who operate the PipeCD for other developers can use it. You will interact with the Control Plane and Piped, you will be the one who installs the Control Plane and keeps it up for other Pipeds to connect while managing their applications’ deployments. +- Operators/Platform team: Users who operate PipeCD for other developers. You will interact with the Control Plane and `piped`, you will be the one who installs the Control Plane and keeps it up for other `piped` instances to connect while managing their applications' deployments. -This section contains the guideline for installing PipeCD's Control Plane and Piped step by step. You can choose what to read based on your roles. +This section contains guidelines for installing PipeCD's Control Plane and `piped` step by step. You can choose what to read based on your roles. diff --git a/docs/content/en/docs-v1.0.x/installation/install-control-plane/_index.md b/docs/content/en/docs-v1.0.x/installation/install-control-plane/_index.md index fe68c06c8f..548e8adcb3 100644 --- a/docs/content/en/docs-v1.0.x/installation/install-control-plane/_index.md +++ b/docs/content/en/docs-v1.0.x/installation/install-control-plane/_index.md @@ -6,4 +6,4 @@ description: > This page describes how to install a control plane. --- -Since Control Plane is a centralized component managing deployment data and provides gRPC API, it needs some components fo storing data or credential... and so on. We explain how to deploy Control Plane components. +Since Control Plane is a centralized component managing deployment data and provides gRPC API, it needs some components for storing data or credentials, and so on. We explain how to deploy Control Plane components. diff --git a/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-ECS.md b/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-ECS.md index acf89b201e..f1a9ff805d 100644 --- a/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-ECS.md +++ b/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-ECS.md @@ -6,7 +6,7 @@ description: > This page describes how to install control plane on ECS. --- -Currently, we provide the example of deploying Control Plane to ECS using terraform. +Currently, we provide an example of deploying Control Plane to ECS using Terraform. -Please refer to the blog post :) +Please refer to the blog post: [PipeCD best practice 02 - control plane on ECS]({{< ref "/blog/control-plane-on-ecs.md" >}} "PipeCD best practice 02 - control plane on ECS"). diff --git a/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-k8s.md b/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-k8s.md index b41a8c71bd..ddb51d6f94 100644 --- a/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-k8s.md +++ b/docs/content/en/docs-v1.0.x/installation/install-control-plane/installing-controlplane-on-k8s.md @@ -8,14 +8,14 @@ description: > ## Prerequisites -- Having a running Kubernetes cluster +- A running Kubernetes cluster - Installed [Helm](https://helm.sh/docs/intro/install/) (3.8.0 or later) ## Installation ### 1. Preparing an encryption key -PipeCD requires a key for encrypting sensitive data or signing JWT token while authenticating. You can use one of the following commands to generate an encryption key. +PipeCD requires a key for encrypting sensitive data or signing JWT tokens while authenticating. You can use one of the following commands to generate an encryption key. ``` console openssl rand 64 | base64 > encryption-key @@ -31,11 +31,11 @@ cat /dev/urandom | head -c64 | base64 > encryption-key Control Plane Architecture -The Control Plane of PipeCD is constructed by several components, as shown in the above graph (for more in detail please read [Control Plane architecture overview docs](../../../user-guide/managing-controlplane/architecture-overview/)). As mentioned in the graph, the PipeCD's data can be stored in one of the provided fully-managed or self-managed services. So you have to decide which kind of [data store](../../../user-guide/managing-controlplane/architecture-overview/#data-store) and [file store](../../../user-guide/managing-controlplane/architecture-overview/#file-store) you want to use and prepare a Control Plane configuration file suitable for that choice. +The Control Plane of PipeCD is constructed by several components, as shown in the above graph (for more details please read [Control Plane architecture overview docs](../../../user-guide/managing-controlplane/architecture-overview/)). As mentioned in the graph, PipeCD's data can be stored in one of the provided fully-managed or self-managed services. So you have to decide which kind of [data store](../../../user-guide/managing-controlplane/architecture-overview/#data-store) and [file store](../../../user-guide/managing-controlplane/architecture-overview/#file-store) you want to use and prepare a Control Plane configuration file suitable for that choice. #### Using Firestore and GCS -PipeCD requires a GCS bucket and service account files to access Firestore and GCS service. Here is an example of configuration file: +PipeCD requires a GCS bucket and service account files to access Firestore and GCS service. Here is an example configuration file: ``` yaml apiVersion: "pipecd.dev/v1beta1" @@ -49,20 +49,20 @@ spec: environment: dev project: {YOUR_GCP_PROJECT_NAME} # Must be a service account with "Cloud Datastore User" and "Cloud Datastore Index Admin" roles - # since PipeCD needs them to creates the needed Firestore composite indexes in the background. + # since PipeCD needs them to create the needed Firestore composite indexes in the background. credentialsFile: /etc/pipecd-secret/firestore-service-account filestore: type: GCS config: bucket: {YOUR_BUCKET_NAME} # Must be a service account with "Storage Object Admin (roles/storage.objectAdmin)" role on the given bucket - # since PipeCD need to write file object such as deployment log file to that bucket. + # since PipeCD needs to write file objects such as deployment log files to that bucket. credentialsFile: /etc/pipecd-secret/gcs-service-account ``` -See [ConfigurationReference](../../../user-guide/managing-controlplane/configuration-reference/) for the full configuration. +See [Configuration reference](../../../user-guide/managing-controlplane/configuration-reference/) for the full configuration. -After all, install the Control Plane as bellow: +After all, install the Control Plane as below: ``` console helm upgrade -i pipecd oci://ghcr.io/pipe-cd/chart/pipecd --version {{< blocks/latest_version >}} --namespace={NAMESPACE} \ @@ -72,11 +72,11 @@ helm upgrade -i pipecd oci://ghcr.io/pipe-cd/chart/pipecd --version {{< blocks/l --set-file secret.gcsServiceAccount.data=path-to-service-account-file ``` -Currently, besides `Firestore` PipeCD supports other databases as its datastore such as `MySQL`. Also as for filestore, PipeCD supports `AWS S3` and `MINIO` either. +Currently, besides `Firestore` PipeCD supports other databases as its datastore such as `MySQL`. As for filestore, PipeCD supports `AWS S3` and `MINIO` as well. -For example, in case of using `MySQL` as datastore and `MINIO` as filestore, the ControlPlane configuration will be as follow: +For example, in case of using `MySQL` as datastore and `MINIO` as filestore, the Control Plane configuration will be as follows: -```yaml +``` yaml apiVersion: "pipecd.dev/v1beta1" kind: ControlPlane spec: @@ -96,42 +96,42 @@ spec: autoCreateBucket: true ``` -You can find required configurations to use other datastores and filestores from [ConfigurationReference](../../../user-guide/managing-controlplane/configuration-reference/). +You can find required configurations to use other datastores and filestores from [Configuration reference](../../../user-guide/managing-controlplane/configuration-reference/). -__Caution__: In case of using `MySQL` as Control Plane's datastore, please note that the implementation of PipeCD requires some features that only available on [MySQL v8](https://dev.mysql.com/doc/refman/8.0/en/), make sure your MySQL service is satisfied the requirement. +__Caution__: In case of using `MySQL` as Control Plane's datastore, please note that the implementation of PipeCD requires some features that are only available in [MySQL v8](https://dev.mysql.com/doc/refman/8.0/en/), make sure your MySQL service satisfies the requirement. ### 3. Accessing the PipeCD web -If your installation was including an [ingress](https://github.com/pipe-cd/pipecd/blob/master/manifests/pipecd/values.yaml#L7), the PipeCD web can be accessed by the ingress's IP address or domain. +If your installation includes an [ingress](https://github.com/pipe-cd/pipecd/blob/master/manifests/pipecd/values.yaml#L7), the PipeCD web can be accessed by the ingress's IP address or domain. Otherwise, private PipeCD web can be accessed by using `kubectl port-forward` to expose the installed Control Plane on your localhost: ``` console kubectl port-forward svc/pipecd 8080 --namespace={NAMESPACE} ``` -Now go to [http://localhost:8080](http://localhost:8080) on your browser, you will see a page to login to your project. +Now go to [http://localhost:8080](http://localhost:8080) on your browser, you will see a page to log in to your project. -Up to here, you have a installed PipeCD's Control Plane. To logging in, you need to initialize a new project. +Up to here, you have an installed PipeCD's Control Plane. To log in, you need to initialize a new project. ### 4. Initialize a new project -To create a new project, you need to access to the `ops` pod in your installed PipeCD control plane, using `kubectl port-forward` command: +To create a new project, you need to access the `ops` pod in your installed PipeCD control plane, using `kubectl port-forward` command: -```console +``` console kubectl port-forward service/pipecd-ops 9082 --namespace={NAMESPACE} ``` -Then, access to [http://localhost:9082](http://localhost:9082). +Then, access [http://localhost:9082](http://localhost:9082). On that page, you will see the list of registered projects and a link to register new projects. Registering a new project requires only a unique ID string and an optional description text. -Once a new project has been registered, a static admin (username, password) will be automatically generated for the project admin, you can use that to login via the login form in the above section. +Once a new project has been registered, a static admin (username, password) will be automatically generated for the project admin, you can use that to log in via the login form in the above section. For more about adding a new project in detail, please read the following [docs](../../../user-guide/managing-controlplane/adding-a-project/). ### 4'. Upgrade Control Plane version -To upgrade the PipeCD Control Plane, preparations and commands remain as you do when installing PipeCD Control Plane. Only need to change the version flag in command to the specified version you want to upgrade your PipeCD Control Plane to. +To upgrade the PipeCD Control Plane, preparations and commands remain as you do when installing PipeCD Control Plane. You only need to change the version flag in command to the specified version you want to upgrade your PipeCD Control Plane to. ``` console helm upgrade -i pipecd oci://ghcr.io/pipe-cd/chart/pipecd --version {NEW_VERSION} --namespace={NAMESPACE} \ @@ -151,7 +151,7 @@ This part provides guidance for a production hardened deployment of the control - End-to-End TLS - After switching to HTTPs, do not forget to set the `api.args.secureCookie` parameter to be `true` to disallow using cookie on unsecured HTTP connection. + After switching to HTTPS, do not forget to set the `api.args.secureCookie` parameter to be `true` to disallow using cookies on unsecured HTTP connection. Alternatively in the case of GKE Ingress, PipeCD also requires a TLS certificate for internal use. This can be a self-signed one and generated by this command: @@ -160,9 +160,9 @@ This part provides guidance for a production hardened deployment of the control ``` Those key and cert can be configured via [`secret.internalTLSKey.data`](https://github.com/pipe-cd/pipecd/blob/master/manifests/pipecd/values.yaml#L118) and [`secret.internalTLSCert.data`](https://github.com/pipe-cd/pipecd/blob/master/manifests/pipecd/values.yaml#L121). - To enable internal tls connection, please set the `gateway.internalTLS.enabled` parameter to be `true`. + To enable internal TLS connection, please set the `gateway.internalTLS.enabled` parameter to be `true`. - Otherwise, the `cloud.google.com/app-protocols` annotation is also should be configured as the following: + Otherwise, the `cloud.google.com/app-protocols` annotation should also be configured as the following: ``` yaml service: diff --git a/docs/content/en/docs-v1.0.x/installation/install-piped/_index.md b/docs/content/en/docs-v1.0.x/installation/install-piped/_index.md index cb60a84f63..97c968f0da 100644 --- a/docs/content/en/docs-v1.0.x/installation/install-piped/_index.md +++ b/docs/content/en/docs-v1.0.x/installation/install-piped/_index.md @@ -1,11 +1,11 @@ --- -title: "Install Piped" -linkTitle: "Install Piped" +title: "Install piped" +linkTitle: "Install piped" weight: 3 description: > - This page describes how you can run the `piped` binary connects your infrastructure to the PipeCD Control Plane. + This page describes how you can run the `piped` binary that connects your infrastructure to the PipeCD Control Plane. --- -Since Piped is a stateless agent, no database or storage is required to run. In addition, a Piped can interact with one or multiple platform providers, so the number of `piped`'s and where they should run is entirely up to your preference. For example, you can run your Pipeds in a Kubernetes cluster to deploy not just Kubernetes applications but your Terraform and Cloud Run applications as well. +Since `piped` is a stateless agent, no database or storage is required to run. In addition, a `piped` can interact with one or multiple plugins, so the number of `piped` instances and where they should run is entirely up to your preference. For example, you can run your `piped` instances in a Kubernetes cluster to deploy not just Kubernetes applications but your Terraform and Cloud Run applications as well. In this guide, we will see how you can configure your `piped` agent and install it on different platforms. diff --git a/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-kubernetes.md b/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-kubernetes.md index d88b1f9a4a..28c9590e94 100644 --- a/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-kubernetes.md +++ b/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-kubernetes.md @@ -3,7 +3,7 @@ title: "Installing on a Kubernetes cluster" linkTitle: "Installing on a Kubernetes cluster" weight: 1 description: > - This page describes how install Piped on a Kubernetes cluster. + This page describes how to install `piped` on a Kubernetes cluster. --- ## Prerequisites @@ -11,29 +11,29 @@ description: > ### A registered `piped` - Make sure your `piped` is registered in the Control Plane and that you have its **PIPED_ID** and **PIPED_KEY**. -- If not, follow the guide to [register a new `Piped`](../../../user-guide/managing-controlplane/registering-a-piped/). +- If not, follow the guide to [register a new `piped`](../../../user-guide/managing-controlplane/registering-a-piped/). ### SSH Key for Git Repositories - If your Git repositories are private, `piped` requires a private SSH key to access those repositories. -- Please checkout [this documentation](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository's Settings page.) +- Please check out [this documentation](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository's Settings page.) If your Git repositories are private, `piped` needs an SSH key to access them. - Generate a new SSH key pair by following [GitHub’s guide to generating an SSH Key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). ->Note: ->If you are using GitHub, add the **public key** as a deploy key to your repositories. +> **Note:** +> If you are using GitHub, add the **public key** as a deploy key to your repositories. ## Installation -### Preparing the `Piped` configuaration file +### Preparing the `piped` configuration file - Plugins are external binaries that have to be referenced in the piped configuration file. There are no plugins set by default. +Plugins are external binaries that have to be referenced in the `piped` configuration file. There are no plugins set by default. -An example of the a piped V1 configuration file using the Kubernetes plugin: +An example of a `piped` v1 configuration file using the Kubernetes plugin: -```yaml +``` yaml apiVersion: pipecd.dev/v1beta1 kind: Piped spec: @@ -50,13 +50,13 @@ spec: ``` >**Note:** ->`Piped`'s plugins are versioned independently from PipeCD. See the [latest releases](https://github.com/pipe-cd/pipecd/releases) for more information. +> `piped`'s plugins are versioned independently from PipeCD. See the [latest releases](https://github.com/pipe-cd/pipecd/releases) for more information. > >We now also have a repository for community built plugins. See the [Community plugins repository on GitHub](https://github.com/pipe-cd/community-plugins) to know more. ## In the cluster-wide mode -This way requires installing cluster-level resources. Piped installed with this way can perform deployment workloads against any other namespaces than the where Piped runs on. +This way requires installing cluster-level resources. When installed this way, `piped` can perform deployment workloads against any other namespaces than the namespace where `piped` runs. - Preparing a piped configuration file as the following @@ -78,14 +78,14 @@ This way requires installing cluster-level resources. Piped installed with this syncInterval: 1m ``` -See [ConfigurationReference](../../../user-guide/managing-piped/configuration-reference/) for the full configuration. +See [Configuration reference](../../../user-guide/managing-piped/configuration-reference/) for the full configuration. - Installing by using [Helm](https://helm.sh/docs/intro/install/) (3.8.0 or later) {{< tabpane >}} - {{< tab lang="bash" header="Piped" >}} -# This command just installs a Piped with the specified version. -# Whenever you want to upgrade that Piped to a new version or update its config data + {{< tab lang="bash" header="piped" >}} +# This command just installs a `piped` with the specified version. +# Whenever you want to upgrade that `piped` to a new version or update its config data # you have to restart it by re-running this command. helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version={{< blocks/latest_version >}} --namespace={NAMESPACE} \ @@ -96,20 +96,20 @@ helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version={{< blocks {{< /tabpane >}} - Note: Be sure to set `--set args.insecure=true` if your Control Plane has not TLS-enabled yet. + Note: Be sure to set `--set args.insecure=true` if your Control Plane does not have TLS enabled yet. See [values.yaml](https://github.com/pipe-cd/pipecd/blob/master/manifests/piped/values.yaml) for the full values. ## In the namespaced mode -The previous way requires installing cluster-level resources. If you want to restrict Piped's permission within the namespace where Piped runs on, you can configure it using the scope parameter. +The previous way requires installing cluster-level resources. If you want to restrict `piped`'s permission within the namespace where `piped` runs, you can configure it using the scope parameter. - Installing by using [Helm](https://helm.sh/docs/intro/install/) (3.8.0 or later) {{< tabpane >}} - {{< tab lang="bash" header="Piped" >}} -# This command just installs a Piped with the specified version. -# Whenever you want to upgrade that Piped to a new version or update its config data + {{< tab lang="bash" header="piped" >}} +# This command just installs a `piped` with the specified version. +# Whenever you want to upgrade that `piped` to a new version or update its config data # you have to restart it by re-running this command. helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version={{< blocks/latest_version >}} --namespace={NAMESPACE} \ @@ -120,7 +120,7 @@ helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version={{< blocks {{< /tab >}} {{< /tabpane >}} -## In case on OpenShift less than 4.2 +## For OpenShift less than 4.2 OpenShift uses an arbitrarily assigned user ID when it starts a container. Starting from OpenShift 4.2, it also inserts that user into `/etc/passwd` for using by the application inside the container, @@ -130,11 +130,11 @@ Therefore if you are running on OpenShift with a version before 4.2, please use - Installing by using [Helm](https://helm.sh/docs/intro/install/) (3.8.0 or later) {{< tabpane >}} - {{< tab lang="bash" header="Piped" >}} + {{< tab lang="bash" header="piped" >}} -# This command just installs a Piped with the specified version. +# This command just installs a `piped` with the specified version. -# Whenever you want to upgrade that Piped to a new version or update its config data +# Whenever you want to upgrade that `piped` to a new version or update its config data # you have to restart it by re-running this command. diff --git a/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-single-machine.md b/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-single-machine.md index 54423d52ee..a205648af2 100644 --- a/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-single-machine.md +++ b/docs/content/en/docs-v1.0.x/installation/install-piped/installing-on-single-machine.md @@ -3,7 +3,7 @@ title: "Installing on a single machine" linkTitle: "Installing on a single machine" weight: 5 description: > - This page describes how to install a Piped on a single machine. + This page describes how to install `piped` on a single machine. --- @@ -12,33 +12,33 @@ description: > ### A registered `piped` - Make sure your `piped` is registered in the Control Plane and that you have its **PIPED_ID** and **PIPED_KEY**. -- If not, follow the guide to [register a new `Piped`](../../../user-guide/managing-controlplane/registering-a-piped/). +- If not, follow the guide to [register a new `piped`](../../../user-guide/managing-controlplane/registering-a-piped/). ### SSH Key for Git Repositories - If your Git repositories are private, `piped` requires a private SSH key to access those repositories. -- Please checkout [this documentation](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository's Settings page.) +- Please check out [this documentation](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository's Settings page.) If your Git repositories are private, `piped` needs an SSH key to access them. - Generate a new SSH key pair by following [GitHub’s guide to generating an SSH Key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). ->Note: ->If you are using GitHub, add the **public key** as a deploy key to your repositories. +> **Note:** +> If you are using GitHub, add the **public key** as a deploy key to your repositories. -### Install the `piped` V1 binary +### Install the `piped` v1 binary -Download the latest `piped` V1. See the [latest releases](https://github.com/pipe-cd/pipecd/releases) and find out the right binary for your machine. +Download the latest `piped` v1. See the [latest releases](https://github.com/pipe-cd/pipecd/releases) and find out the right binary for your machine. ## Installation -### Preparing the `Piped` configuaration file +### Preparing the `piped` configuration file -Plugins are external binaries that have to be referenced in the piped configuration file. There are no plugins set by default. +Plugins are external binaries that have to be referenced in the `piped` configuration file. There are no plugins set by default. -An example of the a piped V1 configuration file using the [Example-stage plugin](https://github.com/pipe-cd/community-plugins/tree/main/plugins/example-stage): +An example of a `piped` v1 configuration file using the [Example-stage plugin](https://github.com/pipe-cd/community-plugins/tree/main/plugins/example-stage): -```yaml +``` yaml apiVersion: pipecd.dev/v1beta1 kind: Piped spec: @@ -54,19 +54,19 @@ spec: plugins: {} ``` -See [ConfigurationReference](../../../user-guide/managing-piped/configuration-reference/) for the full configuration. +See [Configuration reference](../../../user-guide/managing-piped/configuration-reference/) for the full configuration. >**Note:** ->`Piped`'s plugins are versioned independently from PipeCD. Official plugins are maintained and monitored by the PipeCD Maintainers. See the [latest releases](https://github.com/pipe-cd/pipecd/releases) for more information. +> `piped`'s plugins are versioned independently from PipeCD. Official plugins are maintained and monitored by the PipeCD Maintainers. See the [latest releases](https://github.com/pipe-cd/pipecd/releases) for more information. > >We now also have a repository for community built plugins. See the [Community plugins repository on GitHub](https://github.com/pipe-cd/community-plugins) to know more. ## Run the `piped` -After you have configured your Piped configuration file, execute the `piped` binary and specify the path to the Piped configuration file. +After you have configured your `piped` configuration file, execute the `piped` binary and specify the path to the `piped` configuration file. - ``` console - #Replace `PipeCD - a GitOps style continuous delivery solution
@@ -14,12 +14,12 @@ PipeCD - a GitOps style continuous delivery solution ## What Is PipeCD? {{% pageinfo %}} -PipeCD provides a unified continuous delivery solution for multiple application kinds on multi-cloud that empowers engineers to deploy faster with more confidence, a GitOps tool that enables doing deployment operations by pull request on Git. +PipeCD provides a unified continuous delivery solution for multiple application kinds on multi-cloud that empowers engineers to deploy faster with more confidence, a GitOps tool that enables deployment operations by pull request on Git. {{% /pageinfo %}} ## Why PipeCD? -- Simple, unified and easy to use but powerful pipeline definition to construct your deployment +- Simple, unified and easy to use, but powerful pipeline definition to construct your deployment - Same deployment interface to deploy applications of any platform, including Kubernetes, Terraform, GCP Cloud Run, AWS Lambda, AWS ECS and more. - Offers extensibility with a plugin-architecture, allowing users to create plugins and deploy custom applications - No CRD or applications' manifest changes are required; Only need a pipeline definition along with your application manifests @@ -27,16 +27,16 @@ PipeCD provides a unified continuous delivery solution for multiple application - Built-in deployment analysis as part of the deployment pipeline to measure impact based on metrics, logs, emitted requests - Easy to interact with any CI; The CI tests and builds artifacts, PipeCD takes the rest - Insights show metrics like lead time, deployment frequency, MTTR and change failure rate to measure delivery performance -- Designed to manage thousands of cross-platform applications in multi-cloud for company scale but also work well for small projects +- Designed to manage thousands of cross-platform applications in multi-cloud at company scale but also works well for small projects ## PipeCD's Characteristics in detail **Visibility** -- Deployment pipeline UI shows clarify what is happening +- Deployment pipeline UI shows clearly what is happening - Separate logs viewer for each individual deployment -- Realtime visualization of application state -- Deployment notifications to slack, webhook endpoints +- Real-time visualization of application state +- Deployment notifications to Slack, webhook endpoints - Insights show metrics like lead time, deployment frequency, MTTR and change failure rate to measure delivery performance **Automation** @@ -48,16 +48,16 @@ PipeCD provides a unified continuous delivery solution for multiple application **Safety and Security** -- Support single sign-on and role-based access control +- Supports single sign-on and role-based access control - Credentials are not exposed outside the cluster and not saved in the Control Plane -- Piped makes only outbound requests and can run inside a restricted network +- `piped` makes only outbound requests and can run inside a restricted network - Built-in secrets management **Multi-provider & Multi-Tenancy** -- Support multiple application kinds on multi-cloud including Kubernetes, Terraform, Cloud Run, AWS Lambda, Amazon ECS and more with plugins. -- Support multiple analysis providers including Prometheus, Datadog, Stackdriver, and more -- Easy to operate multi-cluster, multi-tenancy by separating Control Plane and Piped +- Supports multiple application kinds on multi-cloud including Kubernetes, Terraform, Cloud Run, AWS Lambda, Amazon ECS and more with plugins. +- Supports multiple analysis providers including Prometheus, Datadog, Stackdriver, and more +- Easy to operate multi-cluster, multi-tenancy by separating Control Plane and `piped` **Open Source** @@ -68,14 +68,14 @@ PipeCD provides a unified continuous delivery solution for multiple application For a good understanding of the PipeCD's components. -- [Concepts](../concepts): describes each components. +- [Concepts](../concepts): describes each component. - [FAQ](../faq): describes the difference between PipeCD and other tools. If you are an **operator** wanting to install and configure PipeCD for other developers. - [Quickstart](../quickstart/) - [Managing Control Plane](../user-guide/managing-controlplane/) -- [Managing Piped](../user-guide/managing-piped/) +- [Managing `piped`](../user-guide/managing-piped/) If you are a **user** using PipeCD to deploy your application/infrastructure: diff --git a/docs/content/en/docs-v1.0.x/quickstart/_index.md b/docs/content/en/docs-v1.0.x/quickstart/_index.md index 4d1ca13d6e..e3a3c45281 100644 --- a/docs/content/en/docs-v1.0.x/quickstart/_index.md +++ b/docs/content/en/docs-v1.0.x/quickstart/_index.md @@ -6,18 +6,18 @@ description: > This page describes how to quickly get started with PipeCD on Kubernetes. --- -PipeCD consists of two core components: The Control Plane and Piped (see [PipeCD Concepts](../concepts/)). +PipeCD consists of two core components: The Control Plane and `piped` (see [PipeCD Concepts](../concepts/)). - **The Control Plane** can be thought of as a web service application that can be installed anywhere. It provides the web UI, API endpoints, and metadata storage. -- **Piped** is a lightweight binary agent that connects your infrastructure to the Control Plane. Piped runs plugins internally which implement the deployment and synchronization logic for a specific application kind, such as Kubernetes or Terraform. +- **`piped`** is a lightweight binary agent that connects your infrastructure to the Control Plane. `piped` runs plugins internally which implement the deployment and synchronization logic for a specific application kind, such as Kubernetes or Terraform. In this quickstart, you’ll install both components on a Kubernetes cluster and deploy a sample “hello world” application. ->Note: +> **Note:** > ->- It's not required to install the PipeCD control plane to the cluster where your applications are running (See [PipeCD best practices](/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 using [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 (See [PipeCD best practices](/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 using [this tutorial](https://github.com/pipe-cd/tutorial). --- @@ -37,7 +37,7 @@ 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 PipeCD control plane will be installed with a default project named `quickstart`. To access the PipeCD Control Plane UI, run the following command: ```bash kubectl port-forward -n pipecd svc/pipecd 8080 @@ -45,32 +45,32 @@ 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) -To login, you can use the configured static admin account as below: +To log in, you can use the configured static admin account as below: - username: `hello-pipecd` - password: `hello-pipecd` -And you will access the main page of PipeCD Control Plane console, which looks like this +And you will access the main page of PipeCD Control Plane console, which looks like this:  -For more about PipeCD control plane management, please check [Managing ControlPlane](/docs/user-guide/managing-controlplane/). +For more about PipeCD control plane management, please check [Managing Control Plane](../user-guide/managing-controlplane/). -#### 1.2. Installing Piped +#### 1.2. Installing piped -Next, in order to perform CD tasks, you need to install a Piped agent to the cluster. +Next, in order to perform CD tasks, you need to install a `piped` agent to the cluster. 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). -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`). +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 on the `Save` button, and then you can see the piped-id and secret-key. - + -You need to copy two values, `Piped Id` and `Base64 Encoded Piped Key`, and fill in `@@ -79,6 +79,6 @@ spec: team: new-team ``` -Commit and push the changes. `Piped` will detect the updates and apply them automatically, according to the configured deployment pipeline. +Commit and push the changes. `piped` will detect the updates and apply them automatically, according to the configured deployment pipeline. For all available configuration options, see the [configuration reference](../configuration-reference/). diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/event-watcher.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/event-watcher.md index 3bd0114f0b..e91d84ad87 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/event-watcher.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/event-watcher.md @@ -12,14 +12,14 @@ The only way to upgrade your application with PipeCD is modifying configuration It brings benefits quite a bit, but it can be painful to manually update them every time in some cases (e.g. continuous deployment to your development environment for debugging, the latest prerelease to the staging environment). If you're experiencing any of the above pains, Event watcher is for you. -Event watcher works as a helper facility to seamlessly link CI and CD. This feature lets you automatically update files managed by your Piped when an arbitrary event has occurred. +Event watcher works as a helper facility to seamlessly link CI and CD. This feature lets you automatically update files managed by your `piped` when an arbitrary event has occurred. While it empowers you to build pretty versatile workflows, the canonical use case is that you trigger a new deployment by image updates, package releases, etc. This guide walks you through configuring Event watcher and how to push an Event. ## Prerequisites -Before we get into configuring EventWatcher, be sure to configure Piped. See [here](../managing-piped/configuring-event-watcher/) for more details. +Before we get into configuring EventWatcher, be sure to configure `piped`. See [here](../managing-piped/configuring-event-watcher/) for more details. ## Usage @@ -35,7 +35,7 @@ Therefore, you mainly need to: #### Use the `.pipe/` directory Prepare EventWatcher configuration files under the `.pipe/` directory at the root of your Git repository. -In that files, you define which values in which files should be updated when the Piped found out a new Event. +In those files, you define which values in which files should be updated when `piped` finds a new Event. For instance, suppose you want to update the Kubernetes manifest defined in `helloworld/deployment.yaml` when an Event with the name `helloworld-image-update` occurs: @@ -106,7 +106,7 @@ You can see the status on the event list page.  -After a while, Piped will create a commit as shown below: +After a while, `piped` will create a commit as shown below: ```diff spec: @@ -116,7 +116,7 @@ After a while, Piped will create a commit as shown below: + image: gcr.io/pipecd/helloworld:v0.2.0 ``` -NOTE: Keep in mind that it may take a little while because Piped periodically fetches the new events from the Control Plane. You can change its interval according to [here](../managing-piped/configuration-reference/#eventwatcher). +> **Note:** Keep in mind that it may take a little while because `piped` periodically fetches the new events from the Control Plane. You can change its interval according to [here](../managing-piped/configuration-reference/#eventwatcher). ### [optional] Using labels Event watcher is a project-wide feature, hence an event name is unique inside a project. That is, you can update multiple repositories at the same time if you use the same event name for different events. @@ -225,7 +225,7 @@ pipectl event register \ --commit-url=https://github.com/pipe-cd/pipecd/commit/20c98a503062021720b2fcf2058276b3245xxxxx ``` -NOTE: There are few more information of the triggered commit you can attach as event metadata, find more in [DeploymentTrace](./deployment-trace) docs. +> **Note:** There is a bit more information about the triggered commit you can attach as event metadata. Find more in [Deployment Trace](./deployment-trace) docs. ## Examples Suppose you want to update your configuration file after releasing a new Helm chart. @@ -267,7 +267,7 @@ pipectl event register \ --data=0.2.0 ``` -Then you'll see that Piped updates as: +Then you'll see that `piped` updates as: ```diff apiVersion: pipecd.dev/v1beta1 diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/manifest-attachment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/manifest-attachment.md index 8a917ef320..ae9219a02c 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/manifest-attachment.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/manifest-attachment.md @@ -35,7 +35,7 @@ spec: - taskdef.yaml ``` -The `config.yaml` file is used as an attachment that can be referenced by other files. The content in `config.yaml` will be reffered to as `config`, and the target files that are configured to use the `config` can be defined under targets. In this case, it is the `taskdef.yaml` file. +The `config.yaml` file is used as an attachment that can be referenced by other files. The content in `config.yaml` will be referred to as `config`, and the target files that are configured to use the `config` can be defined under targets. In this case, it is the `taskdef.yaml` file. And the "target" file, which uses `config.yaml` file content, can be configured as: @@ -50,11 +50,11 @@ containerDefinitions: ... ``` -In all cases, `Piped` will perform attaching the attachment file content at last, right before using it to handle any deployment tasks. +In all cases, `piped` will perform attaching the attachment file content at last, right before using it to handle any deployment tasks. ->**Tip:** +> **Tip:** > ->This feature can be used in combo with PipeCD [SecretManagement feature](../secret-management). You can encrypt your secret data using PipeCD secret encryption function, it will be decrypted and placed in your configuration files; then the PipeCD attachment feature will attach that decrypted configuration to the manifest of resource, which requires that configuration. +> This feature can be used in combo with PipeCD [Secret Management feature](../secret-management). You can encrypt your secret data using PipeCD secret encryption function, it will be decrypted and placed in your configuration files; then the PipeCD attachment feature will attach that decrypted configuration to the manifest of resource, which requires that configuration. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/plan-preview.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/plan-preview.md index 3c370a8b7e..adb3f7769b 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/plan-preview.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/plan-preview.md @@ -24,7 +24,7 @@ PlanPreview with GitHub actions The control plane ops can add a new project for a team. Project adding can be simply done from an internal web page prepared for the ops. -Because that web service is running in an `ops` pod, so in order to access it, using `kubectl port-forward` command to forward a local port to a port on the `ops` pod as following: +Because that web service is running in an `ops` pod, in order to access it, use the `kubectl port-forward` command to forward a local port to a port on the `ops` pod as following: ``` console kubectl port-forward service/pipecd-ops 9082 --namespace={NAMESPACE} @@ -21,4 +21,4 @@ Registering a new project requires only a unique ID string and an optional descr Once a new project has been registered, a static admin (username, password) will be automatically generated for the project admin. You can send that information to the project admin. The project admin first uses the provided static admin information to log in to PipeCD. After that, they can change the static admin information, configure the SSO, RBAC or disable static admin user. -__Caution:__ The Role-Based Access Control (RBAC) setting is required to enable your team login using SSO, please make sure you have that setup before disable static admin user. \ No newline at end of file +> **Important:** Configure RBAC before disabling the static admin user. RBAC is required for SSO login. \ No newline at end of file diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/architecture-overview.md b/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/architecture-overview.md index 4166700b69..cb786a657c 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/architecture-overview.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/architecture-overview.md @@ -11,11 +11,11 @@ description: > Component Architecture
-The control plane is a centralized part of PipeCD. It contains several services as below to manage the application, deployment data and handle all requests from `piped`s and web clients: +The control plane is a centralized part of PipeCD. It contains several services as below to manage the application, deployment data and handle all requests from `piped` instances and web clients: ##### Server -`server` handles all incoming gRPC requests from `piped`s, web clients, incoming HTTP requests such as auth callback from third party services. +`server` handles all incoming gRPC requests from `piped` instances, web clients, incoming HTTP requests such as auth callback from third party services. It also serves all web assets including HTML, JS, CSS... This service can be easily scaled by updating the pod number. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/auth.md b/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/auth.md index d3d5a8a93b..1686afa1a7 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/auth.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/auth.md @@ -3,7 +3,7 @@ title: "Authentication and authorization" linkTitle: "Authentication and authorization" weight: 3 description: > - This page describes about PipeCD Authentication and Authorization. + This page describes PipeCD Authentication and Authorization. ---  @@ -25,7 +25,7 @@ The project can be configured to use a shared SSO configuration (shared OAuth ap - GitHub - Generic OIDC -> Note: In the future, we want to support such as Google Gmail, Bitbucket... +> **Note:** In the future, we want to support such as Google Gmail, Bitbucket... #### Github @@ -45,7 +45,7 @@ Requirements and Troubleshooting: - The OIDC provider must provide claims for user's roles and username. - Roles claim value must use same values as pre-configured project RBAC Roles. -- - Claims can be retreived from the IdToken or UserInfo endpoint. The UserInfo endpoint will be used if issuer supports it. +- Claims can be retrieved from the IdToken or UserInfo endpoint. The UserInfo endpoint will be used if issuer supports it. - You can use set a custom claim key name for roles and username in the OIDC provider. Using `usernameClaimKey` and `rolesClaimKey` in the configuration. If not set, the default value will be chosen in the following order: - Supported Claims Key for Username (in order of priority): `username`, `preferred_username`,`name`, `cognito:username` @@ -254,8 +254,8 @@ resources=*;actions=* User Group represents a relation with a specific team (GitHub)/group (Google) and an arbitrary role. All users belong to a team/group will have all permissions of that team/group. -In case of using the GitHub team as a PipeCD user group, the PipeCD user group must be set in lowercase. For example, if your GitHub team is named `ORG/ABC-TEAM`, the PipeCD user group would be set as `ORG/abc-team`. (It's follow the GitHub team URL as github.com/orgs/{organization-name}/teams/{TEAM-NAME}) +In case of using the GitHub team as a PipeCD user group, the PipeCD user group must be set in lowercase. For example, if your GitHub team is named `ORG/ABC-TEAM`, the PipeCD user group would be set as `ORG/abc-team`. (It follows the GitHub team URL as github.com/orgs/{organization-name}/teams/{TEAM-NAME}) -Note: You CANNOT assign multiple roles to a team/group, should create a new role with suitable permissions instead. +> **Note:** You CANNOT assign multiple roles to a team/group. You should create a new role with suitable permissions instead.  diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/registering-a-piped.md b/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/registering-a-piped.md index 9719f26f8d..a31df82105 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/registering-a-piped.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-controlplane/registering-a-piped.md @@ -6,7 +6,7 @@ description: > This page describes how to register a new piped to a project. --- -The list of pipeds are shown in the Settings page. Anyone who has the project admin role can register a new piped by clicking on the `+ADD` button. +The list of `piped` instances are shown in the Settings page. Anyone who has the project admin role can register a new `piped` by clicking on the `+ADD` button.