Skip to content

Commit

Permalink
Add docs for v0.46.0
Browse files Browse the repository at this point in the history 
Signed-off-by: Yoshiki Fujikane <ffjlabo@gmail.com>
  • Loading branch information
@ffjlabo
ffjlabo committed Feb 6, 2024
1 parent 790bb70 commit 27f4098
Show file tree
Hide file tree
Showing 80 changed files with 6,775 additions and 1 deletion.
4 changes: 4 additions & 0 deletions docs/config.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,10 @@ no = 'Sorry to hear that. Please <a href="https://github.com/pipe-cd/pipecd/issu
githubbranch = "master"
url = "/docs-dev/"

[[params.versions]]
version = "v0.46.x"
url = "/docs-v0.46.x/"

[[params.versions]]
version = "v0.45.x"
url = "/docs-v0.45.x/"
Expand Down
5 changes: 5 additions & 0 deletions docs/content/en/docs-v0.46.x/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: "Welcome to PipeCD"
linkTitle: "Documentation [v0.46.x]"
type: docs
---
75 changes: 75 additions & 0 deletions docs/content/en/docs-v0.46.x/concepts/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
title: "Concepts"
linkTitle: "Concepts"
weight: 2
description: >
This page describes several core concepts in PipeCD.
---

![](/images/architecture-overview.png)
<p style="text-align: center;">
Component Architecture
</p>

### Piped

`piped` is a single binary component you run as an agent in your cluster, your local network to handle the deployment tasks.
It can be run inside a Kubernetes cluster by simply starting a Pod or a Deployment.
This component is designed to be stateless, so it can also be run in a single VM or even your local machine.

### Control Plane

A centralized component managing deployment data and provides gRPC API for connecting `piped`s as well as all web-functionalities of PipeCD such as
authentication, showing deployment list/details, application list/details, delivery insights...

### Project

A project is a logical group of applications to be managed by a group of users.
Each project can have multiple `piped` instances from different clouds or environments.

There are three types of project roles:

- **Viewer** has only permissions of viewing to deployment and application in the project.
- **Editor** has all viewer permissions, plus permissions for actions that modify state such as manually trigger/cancel the deployment.
- **Admin** has all editor permissions, plus permissions for managing project data, managing project `piped`.

### Application

A collect of resources (containers, services, infrastructure components...) and configurations that are managed together.
PipeCD supports multiple kinds of applications such as `KUBERNETES`, `TERRAFORM`, `ECS`, `CLOUDRUN`, `LAMBDA`...

### Application Configuration

A YAML file that contains information to define and configure application.
Each application requires one file at application directory stored in the Git repository.
The default file name is `app.pipecd.yaml`.

### Application Directory

A directory in Git repository containing application configuration file and application manifests.
Each application must have one application directory.

### Deployment

A deployment is a process that does transition from the current state (running state) to the desired state (specified state in Git) of a specific application.
When the deployment is success, it means the running state is being synced with the desired state specified in the target commit.

### Sync Strategy

There are 3 strategies that PipeCD supports while syncing your application state with its configuration stored in Git. Which are:
- Quick Sync: a fast way to make the running application state as same as its Git stored configuration. The generated pipeline contains only one predefined `SYNC` stage.
- Pipeline Sync: sync the running application state with its Git stored configuration through a pipeline defined in its application configuration.
- Auto Sync: depends on your defined application configuration, `piped` will decide the best way to sync your application state with its Git stored configuration.

### Platform Provider

Note: The previous name of this concept was Cloud Provider.

PipeCD supports multiple platforms and multiple kinds of applications.
Platform Provider defines which platform, cloud and where application should be deployed to.

Currently, PipeCD is supporting these five platform providers: `KUBERNETES`, `ECS`, `TERRAFORM`, `CLOUDRUN`, `LAMBDA`.

### Analysis Provider
An external product that provides metrics/logs to evaluate deployments, such as `Prometheus`, `Datadog`, `Stackdriver`, `CloudWatch` and so on.
It is mainly used in the [Automated deployment analysis](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) context.
7 changes: 7 additions & 0 deletions docs/content/en/docs-v0.46.x/contribution-guidelines/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
title: "Contributor Guide"
linkTitle: "Contributor Guide"
weight: 6
description: >
This guide is for anyone who want to contribute to PipeCD project. We are so excited to have you!
---
36 changes: 36 additions & 0 deletions docs/content/en/docs-v0.46.x/contribution-guidelines/architectural-overview.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
title: "Architectural overview"
linkTitle: "Architectural overview"
weight: 3
description: >
This page describes the architecture of PipeCD.
---

![](/images/architecture-overview.png)
<p style="text-align: center;">
Component Architecture
</p>

### Piped

A single binary component runs in your cluster, your local network to handle the deployment tasks.
It can be run inside a Kubernetes cluster by simply starting a Pod or a Deployment.
This component is designed to be stateless, so it can also be run in a single VM or even your local machine.

### Control Plane

A centralized component manages deployment data and provides gRPC API for connecting `piped`s as well as all web-functionalities of PipeCD such as
authentication, showing deployment list/details, application list/details, delivery insights...

Control Plane contains the following components:
- `server`: a service to provide api for piped, web and serve static assets for web.
- `ops`: a service to provide administrative features for Control Plane owner like adding/managing projects.
- `cache`: a redis cache service for caching internal data.
- `datastore`: data storage for storing deployment, application data
- this can be a fully-managed service such as `Firestore`, `Cloud SQL`...
- or a self-managed such as `MySQL`
- `filestore`: file storage for storing logs, application states
- this can a fully-managed service such as `GCS`, `S3`...
- or a self-managed service such as `Minio`

For more information, see [Architecture overview of Control Plane](../../user-guide/managing-controlplane/architecture-overview/).
9 changes: 9 additions & 0 deletions docs/content/en/docs-v0.46.x/contribution-guidelines/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
title: "Contributing"
linkTitle: "Contributing"
weight: 1
description: >
This page describes how to contribute to PipeCD.
---

PipeCD is an open source project that anyone in the community can use, improve, and enjoy. We'd love you to join us! [Contributing to PipeCD](https://github.com/pipe-cd/pipecd/tree/master/CONTRIBUTING.md) is the best place to start with.
93 changes: 93 additions & 0 deletions docs/content/en/docs-v0.46.x/examples/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
---
title: "Examples"
linkTitle: "Examples"
weight: 7
description: >
Some examples of PipeCD in action!
---

One of the best ways to see what PipeCD can do, and learn how to deploy your applications with it, is to see some real examples.

We have prepared some examples for each kind of application.
The examples can be found at the following repository:

https://github.com/pipe-cd/examples

### Kubernetes Applications

| Name | Description |
|-----------------------------------------------------------------------------|-------------|
| [simple](https://github.com/pipe-cd/examples/tree/master/kubernetes/simple) | Deploy plain-yaml manifests in application directory without using pipeline. |
| [helm-local-chart](https://github.com/pipe-cd/examples/tree/master/kubernetes/helm-local-chart) | Deploy a helm chart sourced from the same Git repository. |
| [helm-remote-chart](https://github.com/pipe-cd/examples/tree/master/kubernetes/helm-remote-chart) | Deploy a helm chart sourced from a [Helm Chart Repository](https://helm.sh/docs/topics/chart_repository/). |
| [helm-remote-git-chart](https://github.com/pipe-cd/examples/tree/master/kubernetes/helm-remote-git-chart) | Deploy a helm chart sourced from another Git repository. |
| [kustomize-local-base](https://github.com/pipe-cd/examples/tree/master/kubernetes/kustomize-local-base) | Deploy a kustomize package that just uses the local bases from the same Git repository. |
| [kustomize-remote-base](https://github.com/pipe-cd/examples/tree/master/kubernetes/kustomize-remote-base) | Deploy a kustomize package that uses remote bases from other Git repositories. |
| [canary](https://github.com/pipe-cd/examples/tree/master/kubernetes/canary) | Deployment pipeline with canary strategy. |
| [canary-by-config-change](https://github.com/pipe-cd/examples/tree/master/kubernetes/canary-by-config-change) | Deployment pipeline with canary strategy when ConfigMap was changed. |
| [canary-patch](https://github.com/pipe-cd/examples/tree/master/kubernetes/canary-patch) | Demonstrate how to customize manifests for Canary variant using [patches](../user-guide/configuration-reference/#kubernetescanaryrolloutstageoptions) option. |
| [bluegreen](https://github.com/pipe-cd/examples/tree/master/kubernetes/bluegreen) | Deployment pipeline with bluegreen strategy. This also contains a manual approval stage. |
| [mesh-istio-canary](https://github.com/pipe-cd/examples/tree/master/kubernetes/mesh-istio-canary) | Deployment pipeline with canary strategy by using Istio for traffic routing. |
| [mesh-istio-bluegreen](https://github.com/pipe-cd/examples/tree/master/kubernetes/mesh-istio-bluegreen) | Deployment pipeline with bluegreen strategy by using Istio for traffic routing. |
| [mesh-smi-canary](https://github.com/pipe-cd/examples/tree/master/kubernetes/mesh-smi-canary) | Deployment pipeline with canary strategy by using SMI for traffic routing. |
| [mesh-smi-bluegreen](https://github.com/pipe-cd/examples/tree/master/kubernetes/mesh-smi-bluegreen) | Deployment pipeline with bluegreen strategy by using SMI for traffic routing. |
| [wait-approval](https://github.com/pipe-cd/examples/tree/master/kubernetes/wait-approval) | Deployment pipeline that contains a manual approval stage. |
| [multi-steps-canary](https://github.com/pipe-cd/examples/tree/master/kubernetes/multi-steps-canary) | Deployment pipeline with multiple canary steps. |
| [analysis-by-metrics](https://github.com/pipe-cd/examples/tree/master/kubernetes/analysis-by-metrics) | Deployment pipeline with analysis stage by metrics. |
| [analysis-by-http](https://github.com/pipe-cd/examples/tree/master/kubernetes/analysis-by-http) | Deployment pipeline with analysis stage by running http requests. |
| [analysis-by-log](https://github.com/pipe-cd/examples/tree/master/kubernetes/analysis-by-log) | Deployment pipeline with analysis stage by checking logs. |
| [analysis-with-baseline](https://github.com/pipe-cd/examples/tree/master/kubernetes/analysis-with-baseline) | Deployment pipeline with analysis stage by comparing baseline and canary. |
| [secret-management](https://github.com/pipe-cd/examples/tree/master/kubernetes/secret-management) | Demonstrate how to manage sensitive data by using [Secret Management](../user-guide/managing-application/secret-management/) feature. |

### Terraform Applications

| Name | Description |
|-----------------------------------------------------------------------------|-------------|
| [simple](https://github.com/pipe-cd/examples/tree/master/terraform/simple) | Automatically applies when any changes were detected. |
| [local-module](https://github.com/pipe-cd/examples/tree/master/terraform/local-module) | Deploy application that using local terraform modules from the same Git repository. |
| [remote-module](https://github.com/pipe-cd/examples/tree/master/terraform/remote-module) | Deploy application that using remote terraform modules from other Git repositories. |
| [wait-approval](https://github.com/pipe-cd/examples/tree/master/terraform/wait-approval) | Deployment pipeline that contains a manual approval stage. |
| [autorollback](https://github.com/pipe-cd/examples/tree/master/terraform/autorollback) | Automatically rollback the changes when deployment was failed. |
| [secret-management](https://github.com/pipe-cd/examples/tree/master/terraform/secret-management) | Demonstrate how to manage sensitive data by using [Secret Management](../user-guide/managing-application/secret-management/) feature. |

### Cloud Run Applications

| Name | Description |
|-----------------------------------------------------------------------------|-------------|
| [simple](https://github.com/pipe-cd/examples/tree/master/cloudrun/simple) | Quick sync by rolling out the new version and switching all traffic to it. |
| [canary](https://github.com/pipe-cd/examples/tree/master/cloudrun/canary) | Deployment pipeline with canary strategy. |
| [analysis](https://github.com/pipe-cd/examples/tree/master/cloudrun/analysis) | Deployment pipeline that contains an analysis stage. |
| [secret-management](https://github.com/pipe-cd/examples/tree/master/cloudrun/secret-management) | Demonstrate how to manage sensitive data by using [Secret Management](../user-guide/managing-application/secret-management/) feature. |
| [wait-approval](https://github.com/pipe-cd/examples/tree/master/cloudrun/wait-approval) | Deployment pipeline that contains a manual approval stage. |

### Lambda Applications

| Name | Description |
|-----------------------------------------------------------------------------|-------------|
| [simple](https://github.com/pipe-cd/examples/tree/master/lambda/simple) | Quick sync by rolling out the new version and switching all traffic to it. |
| [canary](https://github.com/pipe-cd/examples/tree/master/lambda/canary) | Deployment pipeline with canary strategy. |
| [analysis](https://github.com/pipe-cd/examples/tree/master/lambda/analysis) | Deployment pipeline that contains an analysis stage. |
| [secret-management](https://github.com/pipe-cd/examples/tree/master/lambda/secret-management) | Demonstrate how to manage sensitive data by using [Secret Management](../user-guide/managing-application/secret-management/) feature. |
| [wait-approval](https://github.com/pipe-cd/examples/tree/master/lambda/wait-approval) | Deployment pipeline that contains a manual approval stage. |
| [remote-git](https://github.com/pipe-cd/examples/tree/master/lambda/remote-git) | Deploy the lambda code sourced from another Git repository. |
| [zip-packing-s3](https://github.com/pipe-cd/examples/tree/master/lambda/zip-packing-s3) | Deployment pipeline of kind Lambda which uses s3 stored zip file as function code. |

### ECS Applications

| Name | Description |
|-----------------------------------------------------------------------------|-------------|
| [simple](https://github.com/pipe-cd/examples/tree/master/ecs/simple) | Quick sync by rolling out the new version and switching all traffic to it. |
| [simple-via-servicediscovery](https://github.com/pipe-cd/examples/tree/master/ecs/servicediscovery/simple) | Quick sync by rolling out the new version and switching all traffic to it for ECS Service Discovery. |
| [canary](https://github.com/pipe-cd/examples/tree/master/ecs/canary) | Deployment pipeline with canary strategy. |
| [canary-via-servicediscovery](https://github.com/pipe-cd/examples/tree/master/ecs/servicediscovery/canary) | Deployment pipeline with canary strategy for ECS Service Discovery. |
| [bluegreen](https://github.com/pipe-cd/examples/tree/master/ecs/bluegreen) | Deployment pipeline with blue-green strategy. |
| [secret-management](https://github.com/pipe-cd/examples/tree/master/ecs/secret-management) | Demonstrate how to manage sensitive data by using [Secret Management](../user-guide/managing-application/secret-management/) feature. |
| [wait-approval](https://github.com/pipe-cd/examples/tree/master/ecs/wait-approval) | Deployment pipeline that contains a manual approval stage. |
| [standalone-task](https://github.com/pipe-cd/examples/tree/master/ecs/standalone-task) | Deployment Standalone Task. (`Standalone task is only supported for Quick sync`) |


### Deployment chain

| Name | Description |
|-----------------------------------------------------------------------------|-------------|
| [simple](https://github.com/pipe-cd/examples/tree/master/deployment-chain/simple) | Simple deployment chain which uses application name as a filter in chain configuration. |
68 changes: 68 additions & 0 deletions docs/content/en/docs-v0.46.x/faq/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
title: "FAQ"
linkTitle: "FAQ"
weight: 9
description: >
List of frequently asked questions.
---

If you have any other questions, please feel free to create the issue in the [pipe-cd/pipecd](https://github.com/pipe-cd/pipecd/issues/new/choose) repository or contact us on [Cloud Native Slack](https://slack.cncf.io) (channel [#pipecd](https://app.slack.com/client/T08PSQ7BQ/C01B27F9T0X)).

### 1. What kind of application (platform provider) will be supported?

Currently, PipeCD can be used to deploy `Kubernetes`, `ECS`, `Terraform`, `CloudRun`, `Lambda` applications.

In the near future we also want to support `Crossplane`...

### 2. What kind of templating methods for Kubernetes application will be supported?

Currently, PipeCD is supporting `Helm` and `Kustomize` as templating method for Kubernetes applications.

### 3. Istio is supported now?

Yes, you can use PipeCD for both mesh (Istio, SMI) applications and non-mesh applications.

### 4. What are the differences between PipeCD and FluxCD?

- Not just Kubernetes applications, PipeCD also provides a unified interface for other cloud services (CloudRun, AWS Lamda...) and Terraform
- One tool for both GitOps sync and progressive deployment
- Supports multiple Git repositories
- Has web UI for better visibility
- Log viewer for each deployment
- Visualization of application component/state in realtime
- Show configuration drift in realtime
- Also supports Canary and BlueGreen for non-mesh applications
- Has built-in secrets management
- Supports gradual rollout of a single app to multiple clusters
- Shows the delivery performance insights

### 5. What are the differences between PipeCD and ArgoCD?

- Not just Kubernetes applications, PipeCD also provides a unified interface for other cloud services (GCP CloudRun, AWS Lamda...) and Terraform
- One tool for both GitOps sync and progressive deployment
- Don't need another CRD or changing the existing manifests for doing Canary/BlueGreen. PipeCD just uses the standard Kubernetes deployment object
- Easier and safer to operate multi-tenancy, multi-cluster for multiple teams (even some teams are running in a private/restricted network)
- Has built-in secrets management
- Supports gradual rollout of a single app to multiple clusters
- Shows the delivery performance insights

### 6. What should I do if I lost my Piped key?

You can create a new Piped key. Go to the `Piped` tab at `Settings` page, and click the vertical ellipsis of the Piped that you would like to create the new Piped key. Don't forget deleting the old Key, too.

### 7. What is the strong point if PipeCD is used only for Kubernetes?

- Simple interface, easy to understand no extra CRD required
- Easy to install, upgrade, and manage (both the ControlPlane and the agent Piped)
- Not strict depend on any Kubernetes API, not being part of issues for your Kubernetes cluster versioning upgrade
- Easy to interact with any CI; Plan preview feature gives you an early look at what will be changed in your cluster even before manifests update
- Insights show metrics like lead time, deployment frequency, MTTR, and change failure rate to measure delivery performance

### 8. Is it open source?

Yes, PipeCD is fully open source project with APACHE LICENSE, VERSION 2.0!!

### 9. How should I investigate high CPU usage or memory usage in piped, or when OOM occurs?

If you're noticing high CPU usage, memory usage, or facing OOM issues in Piped, you can use the built-in support for `pprof`, a tool for visualization and analysis of profiling data.
`pprof` can help you identify the parts of your application that are consuming the most resources. For more detailed information and examples of how to use `pprof` in Piped, please refer to our [Using Pprof in Piped guide](../managing-piped/using-pprof-in-piped).

0 comments on commit 27f4098

Please sign in to comment.