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..6b719c4862 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-a-git-repository.md @@ -0,0 +1,43 @@ +--- +title: "Adding a git repository" +linkTitle: "Adding git repository" +weight: 2 +description: > + 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. + +A Git repository contains one or more deployable applications where each application is put inside a directory called as [application directory](../../../concepts/#application-directory). + +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, add a new [GitRepository](../configuration-reference/#gitrepository) block to the `repositories` field in the `piped` configuration file. + +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 +kind: Piped +spec: + ... + repositories: + - repoId: examples + remote: git@github.com:pipe-cd/examples.git + branch: master +``` + +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} \ + --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 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. 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/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..32db22da60 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/adding-an-analysis-provider.md @@ -0,0 +1,68 @@ +--- +title: "Adding an analysis provider" +linkTitle: "Adding analysis provider" +weight: 6 +description: > + 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). + +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 so that it can be accessed by your `piped`. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + plugins: + - name: analysis + port: + url: + config: + analysisProviders: + - name: prometheus-dev + type: PROMETHEUS + config: + address: https://your-prometheus.dev +``` + +To know more, see the full list of [configurable fields](configuration-reference/#analysisproviderdatadogconfig). + +## 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: + plugins: + - name: analysis + port: + url: + config: + analysisProviders: + - name: datadog-dev + type: DATADOG + config: + apiKeyFile: /etc/piped-secret/datadog-api-key + applicationKeyFile: /etc/piped-secret/datadog-application-key +``` + +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). + +```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} +``` 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..0f100f123e --- /dev/null +++ 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: 2 +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. 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..6148ff2a33 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-event-watcher.md @@ -0,0 +1,68 @@ +--- +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. + +See the full list of [configurable fields for event watcher](../configuration-reference/#eventwatcher) for more information. + +### **OPTIONAL** Settings for git user + +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 +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..5990518492 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuring-notifications.md @@ -0,0 +1,137 @@ +--- +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..529f988c44 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/remote-upgrade-remote-config.md @@ -0,0 +1,43 @@ +--- +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. +--- + +>**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. + + 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..36d265f0cf --- /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 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. + --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.