- A GitOps style continuous delivery platform that provides
consistent deployment and operations experience for any applications
+ A GitOps style continuous delivery platform that provides
consistent deployment and operations experience for any application.
+Component Architecture +
+ +### 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. +- 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. diff --git a/docs/content/en/docs-v1.0.x/contribution-guidelines/_index.md b/docs/content/en/docs-v1.0.x/contribution-guidelines/_index.md new file mode 100755 index 0000000000..b47753d9aa --- /dev/null +++ b/docs/content/en/docs-v1.0.x/contribution-guidelines/_index.md @@ -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! +--- diff --git a/docs/content/en/docs-v1.0.x/contribution-guidelines/architectural-overview.md b/docs/content/en/docs-v1.0.x/contribution-guidelines/architectural-overview.md new file mode 100644 index 0000000000..c7569db0f4 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/contribution-guidelines/architectural-overview.md @@ -0,0 +1,36 @@ +--- +title: "Architectural overview" +linkTitle: "Architectural overview" +weight: 3 +description: > + This page describes the architecture of PipeCD. +--- + + ++Component Architecture +
+ +### 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/). diff --git a/docs/content/en/docs-v1.0.x/contribution-guidelines/contributing.md b/docs/content/en/docs-v1.0.x/contribution-guidelines/contributing.md new file mode 100644 index 0000000000..87eb1a51c0 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/contribution-guidelines/contributing.md @@ -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. \ No newline at end of file diff --git a/docs/content/en/docs-v1.0.x/faq/_index.md b/docs/content/en/docs-v1.0.x/faq/_index.md new file mode 100644 index 0000000000..010be73068 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/faq/_index.md @@ -0,0 +1,66 @@ +--- +title: "FAQ" +linkTitle: "FAQ" +weight: 10 +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 +- 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 +- 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). diff --git a/docs/content/en/docs-v1.0.x/feature-status/_index.md b/docs/content/en/docs-v1.0.x/feature-status/_index.md new file mode 100644 index 0000000000..b9dcbfcf3b --- /dev/null +++ b/docs/content/en/docs-v1.0.x/feature-status/_index.md @@ -0,0 +1,142 @@ +--- +title: "Feature Status" +linkTitle: "Feature Status" +weight: 8 +description: > + This page lists the relative maturity of every PipeCD features. +--- + +Please note that the phases (Incubating, Alpha, Beta, and Stable) are applied to individual features within the project, not to the project as a whole. + +## Feature Phase Definitions + +| Phase | Definition | +|-|-| +|Incubating| Early in design or prototype stage. Not ready for general use.| +|Alpha|Works end to end but may be incomplete or unstable. Backward compatibility is not guaranteed.| +|Beta|Ready for production use and well documented, but may still evolve.| +|Stable|Production-proven, fully supported, and backward compatible.| + +## Plugins + + + +## Piped + +| Feature | Phase | +|-|-| +| [Deployment wait stage](../user-guide/managing-application/customizing-deployment/adding-a-wait-stage/) | Beta | +| [Deployment manual approval stage](../user-guide/managing-application/customizing-deployment/adding-a-manual-approval/) | Beta | +| [Notification](../user-guide/managing-piped/configuring-notifications/) to Slack | Beta | +| [Notification](../user-guide/managing-piped/configuring-notifications/) to external service via webhook | Beta | +| [Secrets management](../user-guide/managing-application/secret-management/) - Storing secrets safely in the Git repository | Beta | +| [Event watcher](../user-guide/event-watcher/) - Updating files in Git automatically for given events | Beta | +| [Pipectl](../user-guide/command-line-tool/) - Command-line tool for interacting with Control Plane | Beta | +| Deployment plugin - Allow executing user-created deployment plugin | Incubating | +| [ADA](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) (Automated Deployment Analysis) by Prometheus metrics | Beta | +| [ADA](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) by Datadog metrics | Beta | +| [ADA](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) by Stackdriver metrics | Incubating | +| [ADA](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) by Stackdriver log | Incubating | +| [ADA](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) by CloudWatch metrics | Incubating | +| [ADA](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) by CloudWatch log | Incubating | +| [ADA](../user-guide/managing-application/customizing-deployment/automated-deployment-analysis/) by HTTP request (smoke test...) | Incubating | +| [Remote upgrade](../user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade) - Ability to upgrade Piped from the web console | Beta | +| [Remote config](../user-guide/managing-piped/remote-upgrade-remote-config/#remote-config) - Watch and reload configuration from a remote location such as Git | Beta | + +## Control Plane + +| Feature | Phase | +|-|-| +| Project/Piped/Application/Deployment management | Beta | +| Rendering deployment pipeline in realtime | Beta | +| Canceling a deployment from console | Beta | +| Triggering a deployment manually from console | Beta | +| RBAC on PipeCD resources such as Application, Piped... | Beta | +| Authentication by username/password for static admin | Beta | +| GitHub & GitHub Enterprise Server SSO | Beta | +| Support GCP [Firestore](https://cloud.google.com/firestore) as data store | Beta | +| Support [MySQL v8.0](https://www.mysql.com/) as data store | Beta | +| Support file store as data store | Alpha - Deprecated (remove soon) | +| Support GCP [GCS](https://cloud.google.com/storage) as file store | Beta | +| Support AWS [S3](https://aws.amazon.com/s3/) as file store | Beta | +| Support [Minio](https://github.com/minio/minio) as file store | Beta | +| [Insights](../user-guide/insights/) - Show the delivery performance of a team or an application | Beta | +| [Deployment Chain](../user-guide/managing-application/deployment-chain/) - Allow rolling out to multiple clusters gradually or promoting across environments | Alpha | +| [Metrics](../user-guide/managing-controlplane/metrics/) - Dashboards for PipeCD and Piped metrics | Beta | + +## Pipectl + +Check [pipectl](../user-guide/command-line-tool/) docs for available commands. diff --git a/docs/content/en/docs-v1.0.x/migrating-from-v0-to-v1/_index.md b/docs/content/en/docs-v1.0.x/migrating-from-v0-to-v1/_index.md new file mode 100644 index 0000000000..2e1d92acc3 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/migrating-from-v0-to-v1/_index.md @@ -0,0 +1,303 @@ +--- +title: "Migrate to PipeCD V1" +linkTitle: "Migrate to PipeCD V1" +weight: 90 +description: > + Documentation on migrating your application from PipeCD V0 to V1 +--- + +This page explains how to safely migrate your existing PipeCD System to the RC version of **PipeCD V1**, the new plugin-based architecture that brings modularity and extensibility to PipeCD. + +Incase you are using PipeCD V0, follow the setps on this page to migrate to **PipeCD V1**. + +## Overview + +PipeCD V1 introduces a **pluggable architecture** that allows developers to add and maintain custom deployment and operational plugins without modifying the core system of PipeCD. + +Migration from v0 is designed to be **safe** and **incremental**, allowing you to switch to PipeCD V1 with minimal disruption. + +## Components + +The PipeCD System has 2 main components: + +| Component | Description | Compatibility | +|------------|--------------|----------------| +| **Control Plane** | Manages projects, deployments, and applications. | Supports both piped and pipedv1 concurrently. | +| **Piped** | Manages the actual deployment and syncing of applications. | Backward compatible - You can switch back to old piped versions. | + +--- + +## Prerequisites + +Before you start, ensure that: + +- You are running the latest version of PipeCD **(v0.55.0)**. + - You have the **latest Control Plane** installed. + - You have the **latest version of `pipectl` and `piped`**. + +> **Note:** If you’re new to the plugin architecture, read: +> +> - [Overview of the plan for plugin-enabled PipeCD](https://pipecd.dev/blog/2024/11/28/overview-of-the-plan-for-pluginnable-pipecd/) +> - [What’s new in pipedv1](https://pipecd.dev/blog/2025/09/02/what-is-new-in-pipedv1-plugin-arch-piped/) + +--- + +## Migration Process Overview + +The migration flow involves the following steps: + +1. [Update `pipectl`](#1-update-pipectl) +2. [Convert application configurations to the v1 format](#2-convert-application-configurations-to-v1-format) +3. [Update the application model in the Control Plane database](#3-update-application-model-in-control-plane-database) +4. [Update piped configuration for v1](#4-update-piped-configuration-for-v1-plugin-definition) +5. [Deploy and verify pipedv1](#5-installing-pipedv1) + +--- + +## 1. Update pipectl + +You can install or upgrade `pipectl` using **curl**, **Homebrew**, **aqua**, or other available methods. +For the full list of installation options, see the [`pipectl` installation guide](https://pipecd.dev/docs-v0.55.x/user-guide/command-line-tool/). + +Below is an example of upgrading pipectl using `curl`: + +```bash +# Example for upgrading pipectl +curl -Lo ./pipectl https://github.com/pipe-cd/pipecd/releases/download/v0.55.0/pipectl_+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. +{{% /pageinfo %}} + +## Why PipeCD? + +- 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 +- No CRD or applications' manifest changes are required; Only need a pipeline definition along with your application manifests +- No deployment credentials are exposed or required outside the application cluster +- 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 + +## PipeCD's Characteristics in detail + +**Visibility** +- Deployment pipeline UI shows clarify what is happening +- Separate logs viewer for each individual deployment +- Realtime 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** +- Automated deployment analysis to measure deployment impact based on metrics, logs, emitted requests +- Automatically roll back to the previous state as soon as analysis or a pipeline stage fails +- Automatically detect configuration drift to notify and render the changes +- Automatically trigger a new deployment when a defined event has occurred (e.g. container image pushed, helm chart published, etc) + +**Safety and Security** +- Support 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 +- Built-in secrets management + +**Multi-provider & Multi-Tenancy** +- Support multiple application kinds on multi-cloud including Kubernetes, Terraform, Cloud Run, AWS Lambda, Amazon ECS +- Support multiple analysis providers including Prometheus, Datadog, Stackdriver, and more +- Easy to operate multi-cluster, multi-tenancy by separating Control Plane and Piped + +**Open Source** + +- Released as an Open Source project +- Under APACHE 2.0 license, see [LICENSE](https://github.com/pipe-cd/pipecd/blob/master/LICENSE) + +## Where should I go next? + +For a good understanding of the PipeCD's components. +- [Concepts](../concepts): describes each components. +- [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/) + +If you are a **user** using PipeCD to deploy your application/infrastructure: +- [User Guide](../user-guide/) +- [Examples](../user-guide/examples) + +If you want to be a **contributor**: +- [Contributor Guide](../contribution-guidelines/) diff --git a/docs/content/en/docs-v1.0.x/releases/_index.md b/docs/content/en/docs-v1.0.x/releases/_index.md new file mode 100644 index 0000000000..25ac023e4b --- /dev/null +++ b/docs/content/en/docs-v1.0.x/releases/_index.md @@ -0,0 +1,6 @@ +--- +title: "Releases ⧉" +manualLink: "https://github.com/pipe-cd/pipecd/releases" +manualLinkTarget: "_blank" +weight: 99 +--- \ No newline at end of file diff --git a/docs/layouts/docs-v1.0.x/baseof.html b/docs/layouts/docs-v1.0.x/baseof.html new file mode 100644 index 0000000000..20af4e6526 --- /dev/null +++ b/docs/layouts/docs-v1.0.x/baseof.html @@ -0,0 +1,32 @@ + + + + {{ partial "head.html" . }} + + +