From 4281cfc19521dbdd1cffb4bcacaed6eea27442ec Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant Date: Mon, 17 Nov 2025 14:06:10 +0530 Subject: [PATCH 1/7] ADD userguide/managingPiped Signed-off-by: Eeshaan Sawant --- .../user-guide/managing-piped/_index.md | 11 + .../managing-piped/adding-a-git-repository.md | 41 +++ .../adding-an-analysis-provider.md | 58 ++++ ...dding-helm-chart-repository-or-registry.md | 60 ++++ .../managing-piped/configuration-reference.md | 273 ++++++++++++++++++ .../managing-piped/configuring-a-plugin.md | 0 .../configuring-event-watcher.md | 66 +++++ .../configuring-notifications.md | 138 +++++++++ .../remote-upgrade-remote-config.md | 38 +++ .../managing-piped/runtime-options.md | 80 +++++ .../managing-piped/using-pprof-in-piped.md | 57 ++++ 11 files changed, 822 insertions(+) create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/_index.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/using-pprof-in-piped.md diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/_index.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/_index.md new file mode 100644 index 0000000000..274469cc03 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/_index.md @@ -0,0 +1,11 @@ +--- +title: "Managing Piped" +linkTitle: "Managing Piped" +weight: 3 +description: > + This guide is for administrators and operators wanting to install and configure piped for other developers. +--- + +In order to use Piped you will need to register a piped through the PipeCD control plane. Check out [how to register a Piped](../managing-controlplane/registering-a-piped/) if you have not have already. After registering successfully, you can monitor your Piped live state via the PipeCD console on the settings page. + +![piped-list-page](/images/piped-list-page.png) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md new file mode 100644 index 0000000000..97bf68b200 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md @@ -0,0 +1,41 @@ +--- +title: "Adding a git repository" +linkTitle: "Adding git repository" +weight: 2 +description: > + This page describes how to add a new Git repository. +--- + +In the `piped` configuration file, we specify the list of Git repositories should be handled by the `piped`. +A Git repository contains one or more deployable applications where each application is put inside a directory called as [application directory](../../../concepts/#application-directory). +That directory contains an application configuration file as well as application manifests. +The `piped` periodically checks the new commits and fetches the needed manifests from those repositories for executing the deployment. + +A single `piped` can be configured to handle one or more Git repositories. +In order to enable a new Git repository, let's add a new [GitRepository](../configuration-reference/#gitrepository) block to the `repositories` field in the `piped` configuration file. + +For example, with the following snippet, `piped` will take the `master` branch of [pipe-cd/examples](https://github.com/pipe-cd/examples) repository as a target Git repository for doing deployments. + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + ... + repositories: + - repoId: examples + remote: git@github.com:pipe-cd/examples.git + branch: master +``` + +In most of the cases, we want to deal with private Git repositories. For accessing those private repositories, `piped` needs a private SSH key, which can be configured while [installing](../../../installation/install-piped/installing-on-kubernetes/) with `secret.sshKey` in the Helm chart. + +``` console +helm install dev-piped pipecd/piped --version={VERSION} \ + --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \ + --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \ + --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} +``` + +You can see this [configuration reference](../configuration-reference/#git) for more configurable fields about Git commands. + +Currently, `piped` allows configuring only one private SSH key for all specified Git repositories. So you can configure the same SSH key for all of those private repositories, or break them into separate `piped`s. In the near future, we also want to update `piped` to support loading multiple SSH keys. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md new file mode 100644 index 0000000000..6604a0fcd1 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md @@ -0,0 +1,58 @@ +--- +title: "Adding an analysis provider" +linkTitle: "Adding analysis provider" +weight: 6 +description: > + This page describes how to add an analysis provider for doing deployment analysis. +--- + +To enable [Automated deployment analysis](../../managing-application/customizing-deployment/automated-deployment-analysis/) feature, you have to set the needed information for Piped to connect to the [Analysis Provider](../../../concepts/#analysis-provider). + +Currently, PipeCD supports the following providers: + +- [Prometheus](https://prometheus.io/) +- [Datadog](https://datadoghq.com/) + +## Prometheus + +Piped queries the [range query endpoint](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) to obtain metrics used to evaluate the deployment. + +You need to define the Prometheus server address accessible to Piped. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + analysisProviders: + - name: prometheus-dev + type: PROMETHEUS + config: + address: https://your-prometheus.dev +``` + +The full list of configurable fields are [here](configuration-reference/#analysisproviderprometheusconfig). + +## Datadog + +Piped queries the [MetricsApi.QueryMetrics](https://docs.datadoghq.com/api/latest/metrics/#query-timeseries-points) endpoint to obtain metrics used to evaluate the deployment. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + analysisProviders: + - name: datadog-dev + type: DATADOG + config: + apiKeyFile: /etc/piped-secret/datadog-api-key + applicationKeyFile: /etc/piped-secret/datadog-application-key +``` + +The full list of configurable fields are [here](configuration-reference/#analysisproviderdatadogconfig). + +If you choose `Helm` as the installation method, we recommend using `--set-file` to mount the key files while performing the [upgrading process](../../../installation/install-piped/installing-on-kubernetes/#in-the-cluster-wide-mode). + +```console +--set-file secret.data.datadog-api-key={PATH_TO_API_KEY_FILE} \ +--set-file secret.data.datadog-application-key={PATH_TO_APPLICATION_KEY_FILE} +``` diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md new file mode 100644 index 0000000000..1bf71d0cf3 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md @@ -0,0 +1,60 @@ +--- +title: "Adding a Helm chart repository or registry" +linkTitle: "Adding Helm chart repo or registry" +weight: 5 +description: > + This page describes how to add a new Helm chart repository or registry. +--- + +PipeCD supports Kubernetes applications that are using Helm for templating and packaging. In addition to being able to deploy a Helm chart that is sourced from the same Git repository (`local chart`) or from a different Git repository (`remote git chart`), an application can use a chart sourced from a Helm chart repository. + +### Adding Helm chart repository + +A Helm [chart repository](https://helm.sh/docs/topics/chart_repository/) is a location backed by an HTTP server where packaged charts can be stored and shared. Before an application can be configured to use a chart from a Helm chart repository, that chart repository must be enabled in the related `piped` by adding the [ChartRepository](../configuration-reference/#chartrepository) struct to the piped configuration file. + +``` yaml +# piped configuration file +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + ... + chartRepositories: + - name: pipecd + address: https://charts.pipecd.dev +``` + +For example, the above snippet enables the official chart repository of PipeCD project. After that, you can configure the Kubernetes application to load a chart from that chart repository for executing the deployment. + +``` yaml +# Application configuration file. +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: + input: + # Helm chart sourced from a Helm Chart Repository. + helmChart: + repository: pipecd + name: helloworld + version: v0.5.0 +``` + +In case the chart repository is backed by HTTP basic authentication, the username and password strings are required in [configuration](../configuration-reference/#chartrepository). + +### Adding Helm chart registry + +A Helm chart [registry](https://helm.sh/docs/topics/registries/) is a mechanism enabled by default in Helm 3.8.0 and later that allows the OCI registry to be used for storage and distribution of Helm charts. + +Before an application can be configured to use a chart from a registry, that registry must be enabled in the related `piped` by adding the [ChartRegistry](../configuration-reference/#chartregistry) struct to the piped configuration file if authentication is enabled at the registry. + +``` yaml +# piped configuration file +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + ... + chartRegistries: + - type: OCI + address: registry.example.com + username: sample-username + password: sample-password +``` diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md new file mode 100644 index 0000000000..207807ced3 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md @@ -0,0 +1,273 @@ +--- +title: "Configuration reference" +linkTitle: "Configuration reference" +weight: 9 +description: > + This page describes all configurable fields in the piped configuration. +--- + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + projectID: ... + pipedID: ... + ... +``` + +## Piped Configuration + +| Field | Type | Description | Required | +|-|-|-|-| +| projectID | string | The identifier of the PipeCD project where this piped belongs to. | Yes | +| pipedID | string | The generated ID for this piped. | Yes | +| pipedKeyFile | string | The path to the file containing the generated key string for this piped. | Yes | +| pipedKeyData | string | Base64 encoded string of Piped key. Either pipedKeyFile or pipedKeyData must be set. | Yes | +| apiAddress | string | The address used to connect to the Control Plane's API in format `host:port`. | Yes | +| syncInterval | duration | How often to check whether an application should be synced. Default is `1m`. | No | +| appConfigSyncInterval | duration | How often to check whether application configuration files should be synced. Default is `1m`. | No | +| git | [Git](#git) | Git configuration needed for Git commands. | No | +| repositories | [][Repository](#gitrepository) | List of Git repositories this piped will handle. | No | +| chartRepositories | [][ChartRepository](#chartrepository) | List of Helm chart repositories that should be added while starting up. | No | +| chartRegistries | [][ChartRegistry](#chartregistry) | List of helm chart registries that should be logged in while starting up. | No | +| platformProviders | [][PlatformProvider](#platformprovider) | List of platform providers can be used by this piped. | No | +| analysisProviders | [][AnalysisProvider](#analysisprovider) | List of analysis providers can be used by this piped. | No | +| eventWatcher | [EventWatcher](#eventwatcher) | Optional Event watcher settings. | No | +| secretManagement | [SecretManagement](#secretmanagement) | The using secret management method. | No | +| notifications | [Notifications](#notifications) | Sending notifications to Slack, Webhook... | No | +| appSelector | map[string]string | List of labels to filter all applications this piped will handle. Currently, it is only be used to filter the applications suggested for adding from the control plane. | No | + +## Git + +| Field | Type | Description | Required | +|-|-|-|-| +| username | string | The username that will be configured for `git` user. Default is `piped`. | No | +| email | string | The email that will be configured for `git` user. Default is `pipecd.dev@gmail.com`. | No | +| sshConfigFilePath | string | Where to write ssh config file. Default is `$HOME/.ssh/config`. | No | +| host | string | The host name. Default is `github.com`. | No | +| hostName | string | The hostname or IP address of the remote git server. Default is the same value with Host. | No | +| sshKeyFile | string | The path to the private ssh key file. This will be used to clone the source code of the specified git repositories. | No | +| sshKeyData | string | Base64 encoded string of SSH key. | No | +| password | string | The base64 encoded password for git used while cloning above Git repository. | No | + +## GitRepository + +| Field | Type | Description | Required | +|-|-|-|-| +| repoID | string | Unique identifier to the repository. This must be unique in the piped scope. | Yes | +| remote | string | Remote address of the repository used to clone the source code. e.g. `git@github.com:org/repo.git` | Yes | +| branch | string | The branch will be handled. | Yes | + +## ChartRepository + +| Field | Type | Description | Required | +|-|-|-|-| +| type | string | The repository type. Currently, HTTP and GIT are supported. Default is HTTP. | No | +| name | string | The name of the Helm chart repository. Note that is not a Git repository but a [Helm chart repository](https://helm.sh/docs/topics/chart_repository/). | Yes if type is HTTP | +| address | string | The address to the Helm chart repository. | Yes if type is HTTP | +| username | string | Username used for the repository backed by HTTP basic authentication. | No | +| password | string | Password used for the repository backed by HTTP basic authentication. | No | +| insecure | bool | Whether to skip TLS certificate checks for the repository or not. | No | +| gitRemote | string | Remote address of the Git repository used to clone Helm charts. | Yes if type is GIT | +| sshKeyFile | string | The path to the private ssh key file used while cloning Helm charts from above Git repository. | No | + +## ChartRegistry + +| Field | Type | Description | Required | +|-|-|-|-| +| type | string | The registry type. Currently, only OCI is supported. Default is OCI. | No | +| address | string | The address to the registry. | Yes | +| username | string | Username used for the registry authentication. | No | +| password | string | Password used for the registry authentication. | No | + +## PlatformProvider + +| Field | Type | Description | Required | +|-|-|-|-| +| name | string | The name of the platform provider. | Yes | +| type | string | The platform provider type. Must be one of the following values:
`KUBERNETES`, `TERRAFORM`, `ECS`, `CLOUDRUN`, `LAMBDA`. | Yes | +| config | [PlatformProviderConfig](#platformproviderconfig) | Specific configuration for the specified type of platform provider. | No | + +## PlatformProviderConfig + +Must be one of the following structs: + +### PlatformProviderKubernetesConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| masterURL | string | The master URL of the kubernetes cluster. Empty means in-cluster. | No | +| kubectlVersion | string | Version of kubectl which will be used to connect to your cluster. Empty means the version set on [piped config](../user-guide/managing-piped/configuration-reference/#platformproviderkubernetesconfig) or [default version](https://github.com/pipe-cd/pipecd/blob/master/tool/piped-base/install-kubectl.sh#L24) will be used. | No | +| kubeConfigPath | string | The path to the kubeconfig file. Empty means in-cluster. | No | +| appStateInformer | [KubernetesAppStateInformer](#kubernetesappstateinformer) | Configuration for application resource informer. | No | + +### PlatformProviderTerraformConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| vars | []string | List of variables that will be set directly on terraform commands with `-var` flag. The variable must be formatted by `key=value`. | No | +| driftDetectionEnabled | bool | Enable drift detection. This is a temporary option and will be possibly removed in the future release. Default is `true` | No | + +### PlatformProviderCloudRunConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| project | string | The GCP project hosting the Cloud Run service. | Yes | +| region | string | The region of running Cloud Run service. | Yes | +| credentialsFile | string | The path to the service account file for accessing Cloud Run service. | No | + +### PlatformProviderLambdaConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| region | string | The region of running Lambda service. | Yes | +| credentialsFile | string | The path to the credential file for logging into AWS cluster. If this value is not provided, piped will read credential info from environment variables. It expects the format [~/.aws/credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). | No | +| roleARN | string | The IAM role arn to use when assuming an role. Required if you want to use the AWS SecurityTokenService. | No | +| tokenFile | string | The path to the WebIdentity token the SDK should use to assume a role with. Required if you want to use the AWS SecurityTokenService. | No | +| profile | string | The profile to use for logging into AWS cluster. The default value is `default`. | No | +| awsAPIPollingInterval | duration | The interval of periodical calls of AWS APIs. Currently, this is an interval of refreshing the live state of Lambda functions. Default is 15s. | No | + +### PlatformProviderECSConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| region | string | The region of running ECS cluster. | Yes | +| credentialsFile | string | The path to the credential file for logging into AWS cluster. If this value is not provided, piped will read credential info from environment variables. It expects the format [~/.aws/credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) | No | +| roleARN | string | The IAM role arn to use when assuming an role. Required if you want to use the AWS SecurityTokenService. | No | +| tokenFile | string | The path to the WebIdentity token the SDK should use to assume a role with. Required if you want to use the AWS SecurityTokenService. | No | +| profile | string | The profile to use for logging into AWS cluster. The default value is `default`. | No | + +## KubernetesAppStateInformer + +| Field | Type | Description | Required | +|-|-|-|-| +| namespace | string | Only watches the specified namespace. Empty means watching all namespaces. | No | +| includeResources | [][KubernetesResourcematcher](#kubernetesresourcematcher) | List of resources that should be added to the watching targets. | No | +| excludeResources | [][KubernetesResourcematcher](#kubernetesresourcematcher) | List of resources that should be ignored from the watching targets. | No | + +### KubernetesResourceMatcher + +| Field | Type | Description | Required | +|-|-|-|-| +| apiVersion | string | The APIVersion of the kubernetes resource. | Yes | +| kind | string | The kind name of the kubernetes resource. Empty means all kinds are matching. | No | + +## AnalysisProvider + +| Field | Type | Description | Required | +|-|-|-|-| +| name | string | The unique name of the analysis provider. | Yes | +| type | string | The provider type. Currently, only PROMETHEUS, DATADOG are available. | Yes | +| config | [AnalysisProviderConfig](#analysisproviderconfig) | Specific configuration for the specified type of analysis provider. | Yes | + +## AnalysisProviderConfig + +Must be one of the following structs: + +### AnalysisProviderPrometheusConfig +| Field | Type | Description | Required | +|-|-|-|-| +| address | string | The Prometheus server address. | Yes | +| usernameFile | string | The path to the username file. | No | +| passwordFile | string | The path to the password file. | No | + +### AnalysisProviderDatadogConfig +| Field | Type | Description | Required | +|-|-|-|-| +| address | string | The address of Datadog API server. Only "datadoghq.com", "us3.datadoghq.com", "datadoghq.eu", "ddog-gov.com" are available. Defaults to "datadoghq.com" | No | +| apiKeyFile | string | The path to the api key file. | Yes | +| applicationKeyFile | string | The path to the application key file. | Yes | +| apiKeyData | string | Base64 API Key for Datadog API server. Either apiKeyData or apiKeyFile must be set | No | +| applicationKeyData | string | Base64 Application Key for Datadog API server. Either applicationKeyFile or applicationKeyData must be set | No | + +## EventWatcher + +| Field | Type | Description | Required | +|-|-|-|-| +| checkInterval | duration | Interval to fetch the latest event and compare it with one defined in EventWatcher config files. Defaults to `1m`. | No | +| gitRepos | [][EventWatcherGitRepo](#eventwatchergitrepo) | The configuration list of git repositories to be observed. Only the repositories in this list will be observed by Piped. | No | + +### EventWatcherGitRepo + +| Field | Type | Description | Required | +|-|-|-|-| +| repoId | string | Id of the git repository. This must be unique within the repos' elements. | Yes | +| commitMessage | string | The commit message used to push after replacing values. Default message is used if not given. | No | +| includes | []string | The paths to EventWatcher files to be included. Patterns can be used like `foo/*.yaml`. | No | +| excludes | []string | The paths to EventWatcher files to be excluded. Patterns can be used like `foo/*.yaml`. This is prioritized if both includes and this are given. | No | + +## SecretManagement + +| Field | Type | Description | Required | +|-|-|-|-| +| type | string | Which management method should be used. Default is `KEY_PAIR`. | Yes | +| config | [SecretManagementConfig](#secretmanagementconfig) | Configration for using secret management method. | Yes | + +## SecretManagementConfig + +Must be one of the following structs: + +### SecretManagementKeyPair + +| Field | Type | Description | Required | +|-|-|-|-| +| privateKeyFile | string | Path to the private RSA key file. | Yes | +| privateKeyData | string | Base64 encoded string of private RSA key. Either privateKeyFile or privateKeyData must be set. | No | +| publicKeyFile | string | Path to the public RSA key file. | Yes | +| publicKeyData | string | Base64 encoded string of public RSA key. Either publicKeyFile or publicKeyData must be set. | No | + +### SecretManagementGCPKMS + +> WIP + +## Notifications + +| Field | Type | Description | Required | +|-|-|-|-| +| routes | [][NotificationRoute](#notificationroute) | List of notification routes. | No | +| receivers | [][NotificationReceiver](#notificationreceiver) | List of notification receivers. | No | + +### NotificationRoute + +| Field | Type | Description | Required | +|-|-|-|-| +| name | string | The name of the route. | Yes | +| receiver | string | The name of receiver who will receive all matched events. | Yes | +| events | []string | List of events that should be routed to the receiver. | No | +| ignoreEvents | []string | List of events that should be ignored. | No | +| groups | []string | List of event groups should be routed to the receiver. | No | +| ignoreGroups | []string | List of event groups should be ignored. | No | +| apps | []string | List of applications where their events should be routed to the receiver. | No | +| ignoreApps | []string | List of applications where their events should be ignored. | No | +| labels | map[string]string | List of labels where their events should be routed to the receiver. | No | +| ignoreLabels | map[string]string | List of labels where their events should be ignored. | No | + + +### NotificationReceiver + +| Field | Type | Description | Required | +|-|-|-|-| +| name | string | The name of the receiver. | Yes | +| slack | [NotificationReciverSlack](#notificationreceiverslack) | Configuration for slack receiver. | No | +| webhook | [NotificationReceiverWebhook](#notificationreceiverwebhook) | Configuration for webhook receiver. | No | + +#### NotificationReceiverSlack + +| Field | Type | Description | Required | +|-|-|-|-| +| hookURL | string | The hookURL of a slack channel. | Yes | +| oauthToken | string | [The token for Slack API use.](https://api.slack.com/authentication/basics) (deprecated)| No | +| oauthTokenData | string | Base64 encoded string of [The token for Slack API use.](https://api.slack.com/authentication/basics) | No | +| oauthTokenFile | string | The path to the oautoken file | No | +| channelID | string | The channel id which slack api send to. | No | +| mentionedAccounts | []string | The accounts to which slack api referes. This field supports both `@username` and `username` writing styles.| No | +| mentionedGroups | []string | The groups to which slack api referes. This field supports both `` and `groupname` writing styles.| No | + +#### NotificationReceiverWebhook + +| Field | Type | Description | Required | +|-|-|-|-| +| url | string | The URL where notification event will be sent to. | Yes | +| signatureKey | string | The HTTP header key used to store the configured signature in each event. Default is "PipeCD-Signature". | No | +| signatureValue | string | The value of signature included in header of each event request. It can be used to verify the received events. | No | +| signatureValueFile | string | The path to the signature value file. | No | diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md new file mode 100644 index 0000000000..74d8a7dfde --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md @@ -0,0 +1,66 @@ +--- +title: "Configuring event watcher" +linkTitle: "Configuring event watcher" +weight: 7 +description: > + This page describes how to configure piped to enable event watcher. +--- + +To enable [EventWatcher](../../event-watcher/), you have to configure your piped at first. + +### Grant write permission + +The [SSH key used by Piped](../configuration-reference/#git) must be a key with write-access because piped needs to commit and push to your git repository when any incoming event matches. + +### Specify Git repositories to be observed + +Piped watches events only for the Git repositories specified in the `gitRepos` list. +You need to add all repositories you want to enable Eventwatcher. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + eventWatcher: + gitRepos: + - repoId: repo-1 + - repoId: repo-2 + - repoId: repo-3 +``` + +### [optional] Specify Eventwatcher files Piped will use + +>NOTE: This way is valid only for defining events using [.pipe/](../../event-watcher/#use-the-pipe-directory). + +If multiple Pipeds handle a single repository, you can prevent conflicts by splitting into the multiple EventWatcher files and setting `includes/excludes` to specify the files that should be monitored by this Piped. + +Say for instance, if you only want the Piped to use the Eventwatcher files under `.pipe/dev/`: + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + eventWatcher: + gitRepos: + - repoId: repo-1 + commitMessage: Update values by Event watcher + includes: + - dev/*.yaml +``` + +`excludes` is prioritized if both `includes` and `excludes` are given. + +The full list of configurable fields are [here](../configuration-reference/#eventwatcher). + +### [optional] Settings for git user + +By default, every git commit uses `piped` as a username and `pipecd.dev@gmail.com` as an email. You can change it with the [git](../configuration-reference/#git) field. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + git: + username: foo + email: foo@example.com +``` diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md new file mode 100644 index 0000000000..1d022e9109 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md @@ -0,0 +1,138 @@ +--- +title: "Configuring notifications" +linkTitle: "Configuring notifications" +weight: 8 +description: > + This page describes how to configure piped to send notifications to external services. +--- + +PipeCD events (deployment triggered, planned, completed, analysis result, piped started...) can be sent to external services like Slack or a Webhook service. While forwarding those events to a chat service helps developers have a quick and convenient way to know the deployment's current status, forwarding to a Webhook service may be useful for triggering other related tasks like CI jobs. + +PipeCD events are emitted and sent by the `piped` component. So all the needed configurations can be specified in the `piped` configuration file. +Notification configuration including: + +- a list of `Route`s which used to match events and decide where the event should be sent to +- a list of `Receiver`s which used to know how to send events to the external service + +[Notification Route](configuration-reference/#notificationroute) matches events based on their metadata like `name`, `group`, `app`, `labels`. +Below is the list of supporting event names and their groups. + +| Event | Group | Supported | Description | +|-|-|-|-| +| DEPLOYMENT_TRIGGERED | DEPLOYMENT |

| | +| DEPLOYMENT_PLANNED | DEPLOYMENT |

| | +| DEPLOYMENT_STARTED | DEPLOYMENT |

| | +| DEPLOYMENT_APPROVED | DEPLOYMENT |

| | +| DEPLOYMENT_WAIT_APPROVAL | DEPLOYMENT |

| | +| DEPLOYMENT_ROLLING_BACK | DEPLOYMENT |

| PipeCD sends a notification when a deployment is completed, while it does not send a notification when a deployment status changes to DEPLOYMENT_ROLLING_BACK because it is not a completion status. See [#4547](https://github.com/pipe-cd/pipecd/issues/4547) | +| DEPLOYMENT_SUCCEEDED | DEPLOYMENT |

| | +| DEPLOYMENT_FAILED | DEPLOYMENT |

| | +| DEPLOYMENT_CANCELLED | DEPLOYMENT |

| | +| DEPLOYMENT_TRIGGER_FAILED | DEPLOYMENT |

| | +| APPLICATION_SYNCED | APPLICATION_SYNC |

| | +| APPLICATION_OUT_OF_SYNC | APPLICATION_SYNC |

| | +| APPLICATION_HEALTHY | APPLICATION_HEALTH |

| | +| APPLICATION_UNHEALTHY | APPLICATION_HEALTH |

| | +| PIPED_STARTED | PIPED |

| | +| PIPED_STOPPED | PIPED |

| | + +### Sending notifications to Slack + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + notifications: + routes: + # Sending all event which contains labels `env: dev` to dev-slack-channel. + - name: dev-slack + labels: + env: dev + receiver: dev-slack-channel + # Only sending deployment started and completed events which contains + # labels `env: prod` and `team: pipecd` to prod-slack-channel. + - name: prod-slack + events: + - DEPLOYMENT_TRIGGERED + - DEPLOYMENT_SUCCEEDED + labels: + env: prod + team: pipecd + receiver: prod-slack-channel + - name: integration-slack + receiver: integration-slack-api + receivers: + - name: dev-slack-channel + slack: + hookURL: https://slack.com/dev + - name: prod-slack-channel + slack: + hookURL: https://slack.com/prod + - name: integration-slack-api + slack: + oauthTokenData: "token" + channelID: "testid" + - name: hookurl-with-mentioned-accounts + slack: + hookURL: https://slack.com/dev, + mentionedAccounts: + - '@user1' + - 'user2' + - name: integration-slack-api-with-mentioned-accounts + slack: + oauthTokenData: token + channelID: testid + mentionedAccounts: + - '@user1' + - 'user2' + - name: integration-slack-api-with-oauthTokenData-and-mentioned-groups + slack: + oauthTokenData: token + channelID: testid + mentionedGroups: + - 'group1' + - '' + - name: integration-slack-api-with-oauthTokenData-and-mentioned-both-accounts-and-groups + slack: + oauthTokenData: token + channelID: testid + mentionedAccounts: + - 'user1' + - '@user2' + mentionedGroups: + - 'groupID1' + - '' +``` + +![A slack notification of a successful deployment](/images/slack-notification-deployment.png) +

+Deployment was triggered, planned and completed successfully +

+ +![A Slack notification of a Piped starting](/images/slack-notification-piped-started.png) +

+A piped has been started +

+ + +For detailed configuration, please check the [configuration reference for Notifications](configuration-reference/#notifications). + +### Sending notifications to external services via webhook + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + notifications: + routes: + # Sending all events an external service. + - name: all-events-to-a-external-service + receiver: a-webhook-service + receivers: + - name: a-webhook-service + webhook: + url: {WEBHOOK_SERVICE_URL} + signatureValue: {RANDOM_SIGNATURE_STRING} +``` + +For detailed configuration, please check the [configuration reference for NotificationReceiverWebhook](configuration-reference/#notificationreceiverwebhook) section. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md new file mode 100644 index 0000000000..07ac08b83c --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md @@ -0,0 +1,38 @@ +--- +title: "Remote upgrade and remote config" +linkTitle: "Remote upgrade and remote config" +weight: 1 +description: > + This page describes how to use remote upgrade and remote config features. +--- + +## Remote upgrade + +The remote upgrade is the ability to restart the currently running Piped with another version from the web console. +This reduces the effort involved in updating Piped to newer versions. +All Pipeds that are running by the provided Piped container image can be enabled to use this feature. +It means Pipeds running on a Kubernetes cluster, a virtual machine, a serverless service can be upgraded remotely from the web console. + +Basically, in order to use this feature you must run Piped with `/launcher` command instead of `/piped` command as usual. +Please check the [installation](../../../installation/install-piped/) guide on each environment to see the details. + +After starting Piped with the remote-upgrade feature, you can go to the Settings page then click on `UPGRADE` button on the top-right corner. +A dialog will be shown for selecting which Pipeds you want to upgrade and what version they should run. + +![Remote Upgrade Settings](/images/settings-remote-upgrade.png) +

+Select a list of Pipeds to upgrade from Settings page +

+ +## Remote config + +Although the remote-upgrade allows you remotely restart your Pipeds to run any new version you want, if your Piped is loading its config locally where Piped is running, you still need to manually restart Piped after adding any change on that config data. Remote-config is for you to remove that kind of manual operation. + +Remote-config is the ability to load Piped config data from a remote location such as a Git repository. Not only that, but it also watches the config periodically to detect any changes on that config and restarts Piped to reflect the new configuration automatically. + +This feature requires the remote-upgrade feature to be enabled simultaneously. Please check [Runtime Options](runtime-options.md) and the [installation](../../../installation/install-piped/) guide on each environment to know how to configure Piped to load a remote config file. + +## Summary + +- By `remote-upgrade` you can upgrade your Piped to a newer version by clicking on the web console +- By `remote-config` you can enforce your Piped to use the latest config data just by updating its config file stored in a Git repository diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md new file mode 100644 index 0000000000..c38e240bb7 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md @@ -0,0 +1,80 @@ +--- +title: "Runtime Options" +linkTitle: "Runtime Options" +weight: 11 +description: > + This page describes configurable options for executing Piped and launcher. +--- + +You can configure some options when running Piped and launcher. + +## Options for Piped + +```bash +Usage: + piped piped [flags] + +Flags: + --add-login-user-to-passwd Whether to add login user to $HOME/passwd. This is typically for applications running as a random user ID. + --admin-port int The port number used to run a HTTP server for admin tasks such as metrics, healthz. (default 9085) + --app-manifest-cache-count int The number of app manifests to cache. The cache-key contains the commit hash. The default is 150. (default 150) + --cert-file string The path to the TLS certificate file. + --config-aws-secret string The ARN of secret that contains Piped config and be stored in AWS Secrets Manager. + --config-aws-ssm-parameter string The name of parameter of Piped config stored in AWS Systems Manager Parameter Store. SecureString is also supported. + --config-data string The base64 encoded string of the configuration data. + --config-file string The path to the configuration file. + --config-gcp-secret string The resource ID of secret that contains Piped config and be stored in GCP SecretManager. + --enable-default-kubernetes-cloud-provider Whether the default kubernetes provider is enabled or not. This feature is deprecated. + --grace-period duration How long to wait for graceful shutdown. (default 30s) + -h, --help help for piped + --insecure Whether disabling transport security while connecting to control-plane. + --launcher-version string The version of launcher which initialized this Piped. + --tools-dir string The path to directory where to install needed tools such as kubectl, helm, kustomize. (default "~/.piped/tools") + +Global Flags: + --log-encoding string The encoding type for logger [json|console|humanize]. (default "humanize") + --log-level string The minimum enabled logging level. (default "info") + --metrics Whether metrics is enabled or not. (default true) + --profile If true enables uploading the profiles to Stackdriver. + --profile-debug-logging If true enables logging debug information of profiler. + --profiler-credentials-file string The path to the credentials file using while sending profiles to Stackdriver. +``` + +## Options for launcher + +```bash +Usage: + launcher launcher [flags] + +Flags: + --aws-secret-id string The ARN of secret that contains Piped config in AWS Secrets Manager service. + --aws-ssm-parameter string The name of parameter of Piped config stored in AWS Systems Manager Parameter Store. SecureString is also supported. + --cert-file string The path to the TLS certificate file. + --check-interval duration Interval to periodically check desired config/version to restart Piped. Default is 1m. (default 1m0s) + --config-data string The base64 encoded string of the configuration data. + --config-file string The path to the configuration file. + --config-from-aws-secret Whether to load Piped config that is being stored in AWS Secrets Manager service. + --config-from-aws-ssm-parameter-store Whether to load Piped config that is being stored in AWS Systems Manager Parameter Store. + --config-from-gcp-secret Whether to load Piped config that is being stored in GCP SecretManager service. + --config-from-git-repo Whether to load Piped config that is being stored in a git repository. + --default-version string The version should be run when no desired version was specified. Empty means using the same version with Launcher. + --gcp-secret-id string The resource ID of secret that contains Piped config in GCP SecretManager service. + --git-branch string Branch of git repository to for Piped config. + --git-piped-config-file string Relative path within git repository to locate Piped config file. + --git-repo-url string The remote URL of git repository to fetch Piped config. + --git-ssh-key-data string Base64 encoded value of SSH private key to fetch Piped config from the private git repository. + --git-ssh-key-file string The path to SSH private key to fetch Piped config from private git repository. + --grace-period duration How long to wait for graceful shutdown. (default 30s) + -h, --help help for launcher + --home-dir string The working directory of Launcher. + --insecure Whether disabling transport security while connecting to control-plane. + --launcher-admin-port int The port number used to run a HTTP server for admin tasks such as metrics, healthz. + +Global Flags: + --log-encoding string The encoding type for logger [json|console|humanize]. (default "humanize") + --log-level string The minimum enabled logging level. (default "info") + --metrics Whether metrics is enabled or not. (default true) + --profile If true enables uploading the profiles to Stackdriver. + --profile-debug-logging If true enables logging debug information of profiler. + --profiler-credentials-file string The path to the credentials file using while sending profiles to Stackdriver. +``` diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/using-pprof-in-piped.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/using-pprof-in-piped.md new file mode 100644 index 0000000000..6288b82e5f --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/using-pprof-in-piped.md @@ -0,0 +1,57 @@ +--- +title: "Using Pprof in Piped" +linkTitle: "Using Pprof in Piped" +weight: 10 +description: > + This guide is for developers who want to use pprof for performance profiling in Piped. +--- + +Piped provides built-in support for pprof, a tool for visualization and analysis of profiling data. It's a part of the standard Go library. + +In Piped, several routes are registered to serve the profiling data in a format understood by the pprof tool. Here are the routes: + +- `/debug/pprof/`: This route serves an index page that lists the available profiling data. +- `/debug/pprof/profile`: This route serves CPU profiling data. +- `/debug/pprof/trace`: This route serves execution trace data. + +You can access these routes to get the profiling data. For example, to get the CPU profiling data, you can access the `/debug/pprof/profile` route. + +Note that using these features in a production environment may impact performance. + +This document explains the basic usage of [pprof](https://pkg.go.dev/net/http/pprof) in Piped. For more detailed information or specific use cases, please refer to the official Go documentation. + +## How to use pprof + +1. Access the pprof index page + + ```bash + curl http://localhost:9085/debug/pprof/ + ``` + + This will return an HTML page that lists the available profiling data. + +2. Get the CPU Profile + + ```bash + curl http://localhost:9085/debug/pprof/profile > cpu.pprof + ``` + + This will save the CPU profiling data to a file named cpu.pprof. You can then analyze this data using the pprof tool: + + ```bash + go tool pprof cpu.pprof + ``` + +3. Get the Execution Trace + + ```bash + curl http://localhost:9085/debug/pprof/trace > trace.out + ``` + + This will save the execution trace data to a file named trace.out. You can then view this trace using the go tool trace command: + + ```bash + go tool trace trace.out + ``` + + Please replace localhost:9085 with the actual address and port of your Piped's admin server. From 6e7b5a33053d671d1360d86e0d4b645c2e8d06d5 Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant Date: Wed, 19 Nov 2025 17:40:56 +0530 Subject: [PATCH 2/7] delete: remove adding Helm chart repository or registry page Signed-off-by: Eeshaan Sawant --- ...dding-helm-chart-repository-or-registry.md | 60 ------------------- 1 file changed, 60 deletions(-) delete mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md deleted file mode 100644 index 1bf71d0cf3..0000000000 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-helm-chart-repository-or-registry.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Adding a Helm chart repository or registry" -linkTitle: "Adding Helm chart repo or registry" -weight: 5 -description: > - This page describes how to add a new Helm chart repository or registry. ---- - -PipeCD supports Kubernetes applications that are using Helm for templating and packaging. In addition to being able to deploy a Helm chart that is sourced from the same Git repository (`local chart`) or from a different Git repository (`remote git chart`), an application can use a chart sourced from a Helm chart repository. - -### Adding Helm chart repository - -A Helm [chart repository](https://helm.sh/docs/topics/chart_repository/) is a location backed by an HTTP server where packaged charts can be stored and shared. Before an application can be configured to use a chart from a Helm chart repository, that chart repository must be enabled in the related `piped` by adding the [ChartRepository](../configuration-reference/#chartrepository) struct to the piped configuration file. - -``` yaml -# piped configuration file -apiVersion: pipecd.dev/v1beta1 -kind: Piped -spec: - ... - chartRepositories: - - name: pipecd - address: https://charts.pipecd.dev -``` - -For example, the above snippet enables the official chart repository of PipeCD project. After that, you can configure the Kubernetes application to load a chart from that chart repository for executing the deployment. - -``` yaml -# Application configuration file. -apiVersion: pipecd.dev/v1beta1 -kind: Application -spec: - input: - # Helm chart sourced from a Helm Chart Repository. - helmChart: - repository: pipecd - name: helloworld - version: v0.5.0 -``` - -In case the chart repository is backed by HTTP basic authentication, the username and password strings are required in [configuration](../configuration-reference/#chartrepository). - -### Adding Helm chart registry - -A Helm chart [registry](https://helm.sh/docs/topics/registries/) is a mechanism enabled by default in Helm 3.8.0 and later that allows the OCI registry to be used for storage and distribution of Helm charts. - -Before an application can be configured to use a chart from a registry, that registry must be enabled in the related `piped` by adding the [ChartRegistry](../configuration-reference/#chartregistry) struct to the piped configuration file if authentication is enabled at the registry. - -``` yaml -# piped configuration file -apiVersion: pipecd.dev/v1beta1 -kind: Piped -spec: - ... - chartRegistries: - - type: OCI - address: registry.example.com - username: sample-username - password: sample-password -``` From 7f3069bdbe016e7844414dc3b6c907b5bd621146 Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant Date: Wed, 19 Nov 2025 17:49:25 +0530 Subject: [PATCH 3/7] fix: update analysis provider configuration in documentation Signed-off-by: Eeshaan Sawant --- .../adding-an-analysis-provider.md | 38 ++++++++++++------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md index 6604a0fcd1..32db22da60 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md @@ -3,7 +3,7 @@ title: "Adding an analysis provider" linkTitle: "Adding analysis provider" weight: 6 description: > - This page describes how to add an analysis provider for doing deployment analysis. + This page describes how to add an Analysis Provider to analyize the metrics of your deployment. --- To enable [Automated deployment analysis](../../managing-application/customizing-deployment/automated-deployment-analysis/) feature, you have to set the needed information for Piped to connect to the [Analysis Provider](../../../concepts/#analysis-provider). @@ -17,20 +17,25 @@ Currently, PipeCD supports the following providers: Piped queries the [range query endpoint](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) to obtain metrics used to evaluate the deployment. -You need to define the Prometheus server address accessible to Piped. +You need to define the Prometheus server address so that it can be accessed by your `piped`. ```yaml apiVersion: pipecd.dev/v1beta1 kind: Piped spec: - analysisProviders: - - name: prometheus-dev - type: PROMETHEUS + plugins: + - name: analysis + port: + url: config: - address: https://your-prometheus.dev + analysisProviders: + - name: prometheus-dev + type: PROMETHEUS + config: + address: https://your-prometheus.dev ``` -The full list of configurable fields are [here](configuration-reference/#analysisproviderprometheusconfig). +To know more, see the full list of [configurable fields](configuration-reference/#analysisproviderdatadogconfig). ## Datadog @@ -40,19 +45,24 @@ Piped queries the [MetricsApi.QueryMetrics](https://docs.datadoghq.com/api/lates apiVersion: pipecd.dev/v1beta1 kind: Piped spec: - analysisProviders: - - name: datadog-dev - type: DATADOG + plugins: + - name: analysis + port: + url: config: - apiKeyFile: /etc/piped-secret/datadog-api-key - applicationKeyFile: /etc/piped-secret/datadog-application-key + analysisProviders: + - name: datadog-dev + type: DATADOG + config: + apiKeyFile: /etc/piped-secret/datadog-api-key + applicationKeyFile: /etc/piped-secret/datadog-application-key ``` -The full list of configurable fields are [here](configuration-reference/#analysisproviderdatadogconfig). +To know more, see the full list of [configurable fields](configuration-reference/#analysisproviderdatadogconfig). If you choose `Helm` as the installation method, we recommend using `--set-file` to mount the key files while performing the [upgrading process](../../../installation/install-piped/installing-on-kubernetes/#in-the-cluster-wide-mode). -```console +```bash --set-file secret.data.datadog-api-key={PATH_TO_API_KEY_FILE} \ --set-file secret.data.datadog-application-key={PATH_TO_APPLICATION_KEY_FILE} ``` From 186bbb647a334fda54cd93e50c74b81d437ec687 Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant Date: Wed, 19 Nov 2025 17:51:33 +0530 Subject: [PATCH 4/7] docs: update remote upgrade and remote config features note Signed-off-by: Eeshaan Sawant --- .../remote-upgrade-remote-config.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md index 07ac08b83c..769fb4e714 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md @@ -6,14 +6,23 @@ description: > This page describes how to use remote upgrade and remote config features. --- -## Remote upgrade +>**NOTE:** +> +>Remote Upgrade and Remote Config features are not available right now for PipeCD versions 1.0.0 and above. +> We are working on them, and will update this page as soon as they are ready. + + + + + + From 353201787388de0820787c3493671f00b03204d1 Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant Date: Thu, 20 Nov 2025 02:08:45 +0530 Subject: [PATCH 5/7] docs: correct usage command for Piped in runtime options Signed-off-by: Eeshaan Sawant --- .../en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md index c38e240bb7..36d265f0cf 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/runtime-options.md @@ -12,7 +12,7 @@ You can configure some options when running Piped and launcher. ```bash Usage: - piped piped [flags] + piped run [flags] Flags: --add-login-user-to-passwd Whether to add login user to $HOME/passwd. This is typically for applications running as a random user ID. From 19d267c671a03808f87ac5e201ba314b60e9b8a7 Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant Date: Wed, 26 Nov 2025 14:21:01 +0530 Subject: [PATCH 6/7] docs: add configuring-a-plugin.md Signed-off-by: Eeshaan Sawant --- .../managing-piped/configuring-a-plugin.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md index e69de29bb2..649a4d30ee 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md @@ -0,0 +1,98 @@ +--- +title: "Configuring a Plugin" +linkTitle: "Configuring a Plugin" +weight: 4 +description: > + This page describes how to configure a plugin in PipeCD. +--- + +Starting PipeCD v1, you can deploy your application to multiple platforms using plugins. + +A plugin represents a deployment capability (like Kubernetes, Terraform, etc.). Each plugin can have one or more `deployTargets`, where a deploy target represents the environment where your application will be deployed. + +Currently, the official plugins maintained by the PipeCD Maintainers are: + +- Kubernetes +- Terraform +- Analysis +- ScriptRun +- Wait +- Wait Approval + +We are working towards releasing more plugins in the future. + +>**Note:** +> We also have the [PipeCD Community Plugins repository](https://github.com/pipe-cd/community-plugins) for plugins made by the PipeCD Community. + +A plugin is added to the piped configuration inside the `spec.plugins` array and providing the plugin’s executable URL, the port it should run on, and any deploy targets that belong to it. For more details, see the [configuration reference for plugins](../configuration-reference/#plugins). + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + repositories: + plugins: + - name: plugin_name + port: 7001 + url: url_to_plugin_binary + deployTargets: + - name: + config: {} +``` + +Check out the latest plugin releases on [GitHub](https://github.com/pipe-cd/pipecd/releases). + +--- + +Now, we will see how you can configure plugins for different application types. + +### Configuring Kubernetes plugin + +The Kubernetes plugin enables PipeCD to manage Kubernetes application deployments. + +By default, piped deploys Kubernetes application to the cluster where the piped is running in. An external cluster can be connected by specifying the `masterURL` and `kubeConfigPath` in [`deployTargets`](../configuration-reference/#kubernetesplugin). + + + +Below is an example configuration for using the Kubernetes plugin: + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + ... + plugins: + - name: kubernetes + port: 7001 + url: https://github.com/pipe-cd/pipecd/releases/download/pkg%2Fapp%2Fpipedv1%2Fplugin%2Fkubernetes%2Fv0.1.0/kubernetes_v0.1.0_darwin_arm64 + deployTargets: + - name: local + config: + kubectlVersion: 1.32.4 + kubeConfigPath: /path/to/.kube/config +``` + +See [Configuration Reference for Kubernetes plugin](../configuration-reference/#kubernetesplugin) for complete configuration details. + +### Configuring Terraform plugin + +The Terraform plugin enables Piped to run Terraform-based deployments. +A deploy target represents a Terraform execution environment (e.g., dev/prod workspace, shared variables, drift detection settings). + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + ... + plugins: + - name: terraform + port: 7002 + url: https://github.com/.../terraform_v0.3.0_linux_amd64 + deployTargets: + - name: tf-dev + config: + vars: + - "project=pipecd" +``` + +See [Configuration Reference for Terraform plugin](../configuration-reference/#terraformplugin) for complete configuration details. From a1cf85acafdc2ee926bf5564ca28fba3ac77373c Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant Date: Sat, 21 Feb 2026 13:53:55 +0530 Subject: [PATCH 7/7] fix userguide/mamanging-piped Signed-off-by: Eeshaan Sawant --- .../managing-piped/adding-a-git-repository.md | 18 ++++++++++-------- .../managing-piped/configuring-a-plugin.md | 4 ++-- .../configuring-event-watcher.md | 10 ++++++---- .../configuring-notifications.md | 3 +-- .../remote-upgrade-remote-config.md | 4 ---- 5 files changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md index 97bf68b200..6b719c4862 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md @@ -3,18 +3,20 @@ title: "Adding a git repository" linkTitle: "Adding git repository" weight: 2 description: > - This page describes how to add a new Git repository. + Learn how to add a git repository in the the `piped` configuration file. + --- +In the `piped` configuration file, all the git repositories that you want to be tracked by the `piped` agent are specified. -In the `piped` configuration file, we specify the list of Git repositories should be handled by the `piped`. A Git repository contains one or more deployable applications where each application is put inside a directory called as [application directory](../../../concepts/#application-directory). -That directory contains an application configuration file as well as application manifests. + +An application directory contains an **application configuration file** as well as application manifests. The `piped` periodically checks the new commits and fetches the needed manifests from those repositories for executing the deployment. A single `piped` can be configured to handle one or more Git repositories. -In order to enable a new Git repository, let's add a new [GitRepository](../configuration-reference/#gitrepository) block to the `repositories` field in the `piped` configuration file. +In order to enable a new Git repository, add a new [GitRepository](../configuration-reference/#gitrepository) block to the `repositories` field in the `piped` configuration file. -For example, with the following snippet, `piped` will take the `master` branch of [pipe-cd/examples](https://github.com/pipe-cd/examples) repository as a target Git repository for doing deployments. +For example, in the following snippet, `piped` will take the `master` branch of [pipe-cd/examples](https://github.com/pipe-cd/examples) repository as a target Git repository for deployments. ``` yaml apiVersion: pipecd.dev/v1beta1 @@ -27,7 +29,7 @@ spec: branch: master ``` -In most of the cases, we want to deal with private Git repositories. For accessing those private repositories, `piped` needs a private SSH key, which can be configured while [installing](../../../installation/install-piped/installing-on-kubernetes/) with `secret.sshKey` in the Helm chart. +In most cases, you would want to deal with private git repositories. For accessing private repositories, `piped` needs a private SSH key, which can be configured while [installing](../../../installation/install-piped/installing-on-kubernetes/) with `secret.sshKey` in the Helm chart. ``` console helm install dev-piped pipecd/piped --version={VERSION} \ @@ -36,6 +38,6 @@ helm install dev-piped pipecd/piped --version={VERSION} \ --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} ``` -You can see this [configuration reference](../configuration-reference/#git) for more configurable fields about Git commands. +You can see the [git configuration reference](../configuration-reference/#git) to learn more about the configurable fields. -Currently, `piped` allows configuring only one private SSH key for all specified Git repositories. So you can configure the same SSH key for all of those private repositories, or break them into separate `piped`s. In the near future, we also want to update `piped` to support loading multiple SSH keys. +Currently, `piped` allows configuring only one private SSH key for all specified git repositories. For working with multiple repositories, you either have configure the same SSH key for all of those private repositories, or use separate `piped`s for each repository. We are working on adding support for multiple SSH keys for a single `piped`. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md index 649a4d30ee..0f100f123e 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin.md @@ -1,7 +1,7 @@ --- title: "Configuring a Plugin" linkTitle: "Configuring a Plugin" -weight: 4 +weight: 2 description: > This page describes how to configure a plugin in PipeCD. --- @@ -46,7 +46,7 @@ Check out the latest plugin releases on [GitHub](https://github.com/pipe-cd/pipe Now, we will see how you can configure plugins for different application types. -### Configuring Kubernetes plugin +## Configuring Kubernetes plugin The Kubernetes plugin enables PipeCD to manage Kubernetes application deployments. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md index 74d8a7dfde..6148ff2a33 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md @@ -8,7 +8,7 @@ description: > To enable [EventWatcher](../../event-watcher/), you have to configure your piped at first. -### Grant write permission +## Grant write permission The [SSH key used by Piped](../configuration-reference/#git) must be a key with write-access because piped needs to commit and push to your git repository when any incoming event matches. @@ -50,11 +50,13 @@ spec: `excludes` is prioritized if both `includes` and `excludes` are given. -The full list of configurable fields are [here](../configuration-reference/#eventwatcher). +See the full list of [configurable fields for event watcher](../configuration-reference/#eventwatcher) for more information. -### [optional] Settings for git user +### **OPTIONAL** Settings for git user -By default, every git commit uses `piped` as a username and `pipecd.dev@gmail.com` as an email. You can change it with the [git](../configuration-reference/#git) field. +By default, every git commit uses **piped** as the username and **pipecd.dev@gmail.com** as the email. You can change it with the [git](../configuration-reference/#git) field. + +For example: ```yaml apiVersion: pipecd.dev/v1beta1 diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md index 1d022e9109..5990518492 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md @@ -36,7 +36,7 @@ Below is the list of supporting event names and their groups. | PIPED_STARTED | PIPED |

| | | PIPED_STOPPED | PIPED |

| | -### Sending notifications to Slack +## Sending notifications to Slack ``` yaml apiVersion: pipecd.dev/v1beta1 @@ -114,7 +114,6 @@ Deployment was triggered, planned and completed successfully A piped has been started

- For detailed configuration, please check the [configuration reference for Notifications](configuration-reference/#notifications). ### Sending notifications to external services via webhook diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md index 769fb4e714..529f988c44 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md @@ -11,10 +11,6 @@ description: > >Remote Upgrade and Remote Config features are not available right now for PipeCD versions 1.0.0 and above. > We are working on them, and will update this page as soon as they are ready. - - - -