+Adding a new API key from Settings tab +
+ +When executing a command of pipectl you have to specify either a string of API key via `--api-key` flag or a path to the API key file via `--api-key-file` flag. + +## Usage + +### Help + +Run `help` to know the available commands: + +``` console +$ pipectl --help + +The command line tool for PipeCD. + +Usage: + pipectl [command] + +Available Commands: + application Manage application resources. + deployment Manage deployment resources. + encrypt Encrypt the plaintext entered in either stdin or the --input-file flag. + event Manage event resources. + help Help about any command + init Generate an application config (app.pipecd.yaml) easily and interactively. + piped Manage piped resources. + plan-preview Show plan preview against the specified commit. + version Print the information of current binary. + +Flags: + -h, --help help for pipectl + --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. + +Use "pipectl [command] --help" for more information about a command. +``` + +### Adding a new application + +Add a new application into the project: + +``` console +pipectl application add \ + --address=CONTROL_PLANE_API_ADDRESS \ + --api-key=API_KEY \ + --app-name=simple \ + --app-kind=KUBERNETES \ + --piped-id=PIPED_ID \ + --platform-provider=kubernetes-default \ + --repo-id=examples \ + --app-dir=kubernetes/simple +``` + +Run `help` to know what command flags should be specified: + +``` console +$ pipectl application add --help + +Add a new application. + +Usage: + pipectl application add [flags] + +Flags: + --app-dir string The relative path from the root of repository to the application directory. + --app-kind string The kind of application. (KUBERNETES|TERRAFORM|LAMBDA|CLOUDRUN) + --app-name string The application name. + --platform-provider string The platform provider name. One of the registered providers in the piped configuration. The previous name of this field is cloud-provider. + --config-file-name string The configuration file name. (default "app.pipecd.yaml") + --description string The description of the application. + -h, --help help for add + --piped-id string The ID of piped that should handle this application. + --repo-id string The repository ID. One the registered repositories in the piped configuration. + +Global Flags: + --address string The address to Control Plane api. + --api-key string The API key used while authenticating with Control Plane. + --api-key-file string Path to the file containing API key used while authenticating with Control Plane. + --cert-file string The path to the TLS certificate file. + --insecure Whether disabling transport security while connecting to Control Plane. + --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. +``` + +### Syncing an application + +- Send a request to sync an application and exit immediately when the deployment is triggered: + + ``` console + pipectl application sync \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --app-id={APPLICATION_ID} + ``` + +- Send a request to sync an application and wait until the triggered deployment reaches one of the specified statuses: + + ``` console + pipectl application sync \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --app-id={APPLICATION_ID} \ + --wait-status=DEPLOYMENT_SUCCESS,DEPLOYMENT_FAILURE + ``` + +### Getting an application + +Display the information of a given application in JSON format: + +``` console +pipectl application get \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --app-id={APPLICATION_ID} +``` + +### Listing applications + +Find and display the information of matching applications in JSON format: + +``` console +pipectl application list \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --app-name={APPLICATION_NAME} \ + --app-kind=KUBERNETES \ +``` + +### Disable an application + +Disable an application with given id: + +``` console +pipectl application disable \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --app-id={APPLICATION_ID} +``` + +### Deleting an application + +Delete an application with given id: + +``` console +pipectl application delete \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --app-id={APPLICATION_ID} +``` + +### List deployments + +Show the list of deployments based on filters. + +```console +pipectl deployment list \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --app-id={APPLICATION_ID} +``` + +### Waiting a deployment status + +Wait until a given deployment reaches one of the specified statuses: + +``` console +pipectl deployment wait-status \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --deployment-id={DEPLOYMENT_ID} \ + --status=DEPLOYMENT_SUCCESS +``` + +### Get deployment stages log + +Get deployment stages log. + +```console +pipectl deployment logs \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --deployment-id={DEPLOYMENT_ID} +``` + +### Registering an event for EventWatcher + +Register an event that can be used by EventWatcher: + +``` console +pipectl event register \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --name=example-image-pushed \ + --data=gcr.io/pipecd/example:v0.1.0 +``` + +See more on [usage of Event Watcher](./event-watcher.md). + +### Encrypting the data you want to use when deploying + +Encrypt the plaintext entered either in stdin or via the `--input-file` flag. + +You can encrypt it the same way you do [from the web](../managing-application/secret-management/#encrypting-secret-data). + +- From stdin: + + ``` console + pipectl encrypt \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --piped-id={PIPED_ID} <{PATH_TO_SECRET_FILE} + ``` + +- From the `--input-file` flag: + + ``` console + pipectl encrypt \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --piped-id={PIPED_ID} \ + --input-file={PATH_TO_SECRET_FILE} + ``` + +Note: The docs for pipectl available command is maybe outdated, we suggest users use the `help` command for the updated usage while using pipectl. + +### You want more? + +We always want to add more needed commands into pipectl. Please let us know what command you want to add by creating issues in the [pipe-cd/pipecd](https://github.com/pipe-cd/pipecd/issues) repository. We also welcome your pull request to add the command. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/_index.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/_index.md new file mode 100644 index 0000000000..9e5d54d98b --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/_index.md @@ -0,0 +1,9 @@ +--- +title: "Managing Application" +linkTitle: "Managing Application" +weight: 2 +description: > + This guide is for developers who have PipeCD installed for them and are using PipeCD to deploy their applications. +--- + +> Note: You must have at least one activated/running Piped to enable using any of the following features of PipeCD. Please refer to [Piped installation docs](../../installation/install-piped/) if you do not have any Piped in your pocket. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/deployment-trace.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/deployment-trace.md new file mode 100644 index 0000000000..42fc06b40e --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/deployment-trace.md @@ -0,0 +1,37 @@ +--- +title: "Better connect between CI and CD with Deployment Trace" +linkTitle: "Deployment Trace" +weight: 992 +description: > + A helper fulfill the gap between CI and CD. +--- + +You are a developer who works with application code change, and don't know what deployment is triggered by your commit on PipeCD UI? This feature is for you. + +If you're using PipeCD [Event Watcher](./event-watcher) to trigger the deployment for your code change, you can attach information of the triggered commit as the event data, PipeCD will use that information and helps you to make a link between your application code commit and the triggered deployments that reflect your code change. + + + +## Usage + +Via `pipectl event register` command + +```bash +Usage: + pipectl event register [flags] + +Flags: + --commit-author string The author of commit that triggers the event. + --commit-hash string The commit hash that triggers the event. + --commit-message string The message of commit that triggers the event. + --commit-timestamp int The timestamp of commit that triggers the event. + --commit-title string The title of commit that triggers the event. + --commit-url string The URL of commit that triggers the event. +``` + +Note: You have to attach at least `commit-hash` and `commit-url` as the event data in order to use the Deployment Trace feature. + +## Github Actions + +If you're using Github Actions in your CI workflow, [actions-event-register](https://github.com/marketplace/actions/pipecd-register-event) is for you! +With it, you can easily register events without any installation. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/event-watcher.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/event-watcher.md new file mode 100644 index 0000000000..3bd0114f0b --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/event-watcher.md @@ -0,0 +1,298 @@ +--- +title: "Connect between CI and CD with event watcher" +linkTitle: "Event watcher" +weight: 991 +description: > + A helper facility to automatically update files when it finds out a new event. +--- + + + +The only way to upgrade your application with PipeCD is modifying configuration files managed by the Git repositories. +It brings benefits quite a bit, but it can be painful to manually update them every time in some cases (e.g. continuous deployment to your development environment for debugging, the latest prerelease to the staging environment). + +If you're experiencing any of the above pains, Event watcher is for you. +Event watcher works as a helper facility to seamlessly link CI and CD. This feature lets you automatically update files managed by your Piped when an arbitrary event has occurred. +While it empowers you to build pretty versatile workflows, the canonical use case is that you trigger a new deployment by image updates, package releases, etc. + +This guide walks you through configuring Event watcher and how to push an Event. + +## Prerequisites + +Before we get into configuring EventWatcher, be sure to configure Piped. See [here](../managing-piped/configuring-event-watcher/) for more details. + +## Usage + +File updating can be done by registering the latest value corresponding to the Event in the Control Plane and comparing it with the current value. + +Therefore, you mainly need to: + +1. define which values in which files should be updated when a new Event found. +1. integrate a step to push an Event to the Control Plane using `pipectl` into your CI workflow. + +### 1. Defining Events + +#### Use the `.pipe/` directory + +Prepare EventWatcher configuration files under the `.pipe/` directory at the root of your Git repository. +In that files, you define which values in which files should be updated when the Piped found out a new Event. + +For instance, suppose you want to update the Kubernetes manifest defined in `helloworld/deployment.yaml` when an Event with the name `helloworld-image-update` occurs: + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: EventWatcher +spec: + events: + - name: helloworld-image-update + replacements: + - file: helloworld/deployment.yaml + yamlField: $.spec.template.spec.containers[0].image +``` + +The full list of configurable `EventWatcher` fields are [here](../configuration-reference/#event-watcher-configuration-deprecated). + +#### Use the application configuration + +Define what to do for which event in the application configuration file of the target application. + +- `matcher`: Which event should be handled. +- `handler`: What to do for the event which is specified by matcher. + +For instance, suppose you want to update the Kubernetes manifest defined in `helloworld/deployment.yaml` when an Event with the name `helloworld-image-update` occurs: + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: + eventWatcher: + - handler: + config: + replacements: + - file: deployment.yaml + yamlField: $.spec.template.spec.containers[0].image + type: GIT_UPDATE + matcher: + name: helloworld-image-update + name: helloworld + plugins: + kubernetes: {} +``` + +The full list of configurable `eventWatcher` fields are [here](../configuration-reference/#eventwatcher). + +### 2. Pushing an Event with `pipectl` + +To register a new value corresponding to Event such as the above in the Control Plane, you need to perform `pipectl`. +And we highly recommend integrating a step for that into your CI workflow. + +You first need to set-up the `pipectl`: + +- Install it on your CI system or where you want to run according to [this guide](../command-line-tool/#installation). +- Grab the API key to which the `READ_WRITE` role is attached according to [this guide](../command-line-tool/#authentication). + +Once you're all set up, pushing a new Event to the Control Plane by the following command: + +```bash +pipectl event register \ + --address={CONTROL_PLANE_API_ADDRESS} \ + --api-key={API_KEY} \ + --name=helloworld-image-update \ + --data=gcr.io/pipecd/helloworld:v0.2.0 +``` + +You can see the status on the event list page. + + + + +After a while, Piped will create a commit as shown below: + +```diff + spec: + containers: + - name: helloworld +- image: gcr.io/pipecd/helloworld:v0.1.0 ++ image: gcr.io/pipecd/helloworld:v0.2.0 +``` + +NOTE: Keep in mind that it may take a little while because Piped periodically fetches the new events from the Control Plane. You can change its interval according to [here](../managing-piped/configuration-reference/#eventwatcher). + +### [optional] Using labels +Event watcher is a project-wide feature, hence an event name is unique inside a project. That is, you can update multiple repositories at the same time if you use the same event name for different events. + +On the contrary, if you want to explicitly distinguish those, we recommend using labels. You can make an event definition unique by using any number of labels with arbitrary keys and values. +Suppose you define an event with the labels `env: dev` and `appName: helloworld`: + +When you use the `.pipe/` directory, you can configure like below. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: EventWatcher +spec: + events: + - name: image-update + labels: + env: dev + appName: helloworld + replacements: + - file: helloworld/deployment.yaml + yamlField: $.spec.template.spec.containers[0].image +``` + +The other example is like below. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: + eventWatcher: + - handler: + config: + replacements: + - file: deployment.yaml + yamlField: $.spec.template.spec.containers[0].image + type: GIT_UPDATE + matcher: + labels: + appName: helloworld + env: dev + name: image-update + name: helloworld + plugins: + kubernetes: {} +``` + +The file update will be executed only when the labels are explicitly specified with the `--labels` flag. + +```bash +pipectl event register \ + --address=CONTROL_PLANE_API_ADDRESS \ + --api-key=API_KEY \ + --name=image-update \ + --labels env=dev,appName=helloworld \ + --data=gcr.io/pipecd/helloworld:v0.2.0 +``` + +Note that it is considered a match only when labels are an exact match. + +### [optional] Using contexts + +You can also attach additional metadata to the event. +This information can be added as a trailer to the git commit when Event Watcher using the GIT_UPDATE handler. +This can be useful when attaching information from the source code repository to the manifest repository. + +For example, you can attach the source code commit link to the manifest repository. + +```bash +pipectl event register \ + --address=CONTROL_PLANE_API_ADDRESS \ + --api-key=API_KEY \ + --name=sample \ + --data=gcr.io/pipecd/helloworld:v0.48.0 \ + --contexts Source-Commit-Hash=xxxxxxx,Source-Commit-URL=https://github.com/pipe-cd/pipecd/commit/xxxxxxx +``` + +```bash +# In manifest repository +$ git show +commit ff46cdc9a3ce87a9a66436269251a4870ac55183 (HEAD -> main, origin/main, origin/HEAD) +Author: ffjlabo+PlanPreview with GitHub actions pipe-cd/actions-plan-preview +
+ +## Prerequisites + +- Ensure the version of your Piped is at least `v0.11.0`. +- Having an API key that has `READ_WRITE` role to authenticate with PipeCD's Control Plane. A new key can be generated from `settings/api-key` page of your PipeCD web. + +## Usage + +Plan-preview result can be requested by using `pipectl` command-line tool as below: + +``` console +pipectl plan-preview \ + --address={ PIPECD_CONTROL_PLANE_ADDRESS } \ + --api-key={ PIPECD_API_KEY } \ + --repo-remote-url={ REPO_REMOTE_GIT_SSH_URL } \ + --head-branch={ HEAD_BRANCH } \ + --head-commit={ HEAD_COMMIT } \ + --base-branch={ BASE_BRANCH } \ + --sort-label-keys={ SORT_LABEL_KEYS } +``` + +You can run it locally or integrate it to your CI system to run automatically when a new pull request is opened/updated. Use `--help` to see more options. + +``` console +pipectl plan-preview --help +``` + +### Order of the results + +By default, the results are sorted by PipedID and Application Name. + +If you want to sort the results by labels, add `--sort-label-keys` option. For example, when you run with `--sort-label-keys=env,team`, the results will be sorted by PipedID, `env` label, `team` label, and then Application Name. + + +## GitHub Actions + +If you are using GitHub Actions, you can seamlessly integrate our prepared [actions-plan-preview](https://github.com/pipe-cd/actions-plan-preview) to your workflows. This automatically comments the plan-preview result on the pull request when it is opened or updated. You can also trigger to run plan-preview manually by leave a comment `/pipecd plan-preview` on the pull request. diff --git a/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/_index.md b/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/_index.md new file mode 100644 index 0000000000..050cbac14f --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/_index.md @@ -0,0 +1,9 @@ +--- +title: "Observability and Metrics" +linkTitle: "Observability and Metrics" +weight: 2 +description: > + Understand how you can get end-to-end visibility of your PipeCD deployment through a collection of various metrics. +--- + +> Note: You must have at least one activated/running Piped to enable using any of the following features of PipeCD. Please refer to [Piped installation docs](../../installation/install-piped/) if you do not have any Piped in your pocket. diff --git a/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/insights.md b/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/insights.md new file mode 100644 index 0000000000..3247a21d02 --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/insights.md @@ -0,0 +1,39 @@ +--- +title: "Insights" +linkTitle: "Insights" +weight: 994 +description: > + This page describes how to see delivery performance. +--- + + + +### Application metrics + +The topmost block helps you understand how many applications your project has. + +### Deployment metrics + +Based on your executed deployment data, PipeCD provides charts that help you better understand the delivery performance of your organization. + +You can view daily, and monthly data visualizations of your entire project, a specific application, or a group of applications that match a list of labels. + +#### Deployment Frequency + +How often does your application/project deploy code to production. + +#### Change Failure Rate + +How often deployment failures occur in production that requires an immediate remedy (fix, rollback...). + +#### Lead Time for Changes + +How long does it take to go from code committed to code successfully running on production. + +> WIP + +#### Mean Time To Restore + +How long does it generally take to restore service when a service incident occurs. + +> WIP diff --git a/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/metrics.md b/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/metrics.md new file mode 100644 index 0000000000..dfb9c02bbe --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/observability-and-metrics/metrics.md @@ -0,0 +1,125 @@ +--- +title: "Metrics" +linkTitle: "Metrics" +weight: 995 +description: > + This page describes how to enable monitoring system for collecting PipeCD' metrics. +--- + +PipeCD comes with a monitoring system including Prometheus, Alertmanager, and Grafana. +This page walks you through how to set up and use them. + +## Monitoring overview + + ++Monitoring Architecture +
+ +Both the Control plane and piped agent have their own "admin servers" (the default port number is 9085), which are simple HTTP servers providing operational information such as health status, running version, go profile, and monitoring metrics. + +The piped agent collects its metrics and periodically sends them to the Control plane. The Control plane then compacts its resource usage and cluster information with the metrics sent by the piped agent and re-publishes them via its admin server. When the PipeCD monitoring feature is turned on, Prometheus, Alertmanager, and Grafana are deployed with the Control plane, and Prometheus retrieves metrics information from the Control plane's admin server. + +Developers managing the piped agent can also get metrics directly from the piped agent and monitor them with their custom monitoring service. + +## Enable monitoring system +To enable monitoring system for PipeCD, you first need to set the following value to `helm install` when [installing](../../../installation/install-controlplane/#2-preparing-control-plane-configuration-file-and-installing). + +``` +--set monitoring.enabled=true +``` + +## Dashboards + +If you've already enabled monitoring system in the previous section, you can access Grafana using port forwarding: + +``` +kubectl port-forward -n {NAMESPACE} svc/{PIPECD_RELEASE_NAME}-grafana 3000:80 +``` + +#### Control Plane dashboards +There are three dashboards related to Control Plane: +- Overview - usage stats of PipeCD +- Incoming Requests - gRPC and HTTP requests stats to check for any negative impact on users +- Go - processes stats of PipeCD components + +#### Piped dashboards +Visualize the metrics of Piped registered in the Control plane. +- Overview - usage stats of piped agents +- Process - resource usage of piped agent +- Go - processes stats of piped agents. + +#### Cluster dashboards +Because cluster dashboards tracks cluster-wide metrics, defaults to disable. You can enable it with: + +``` +--monitoring.clusterStats=true +``` + +There are three dashboards that track metrics for: +- Node - nodes stats within the Kubernetes cluster where PipeCD runs on +- Pod - stats for pods that make PipeCD up +- Prometheus - stats for Prometheus itself + +## Alert notifications +If you want to send alert notifications to external services like Slack, you need to set an alertmanager configuration file. + +For example, let's say you use Slack as a receiver. Create `values.yaml` and put the following configuration to there. + +```yaml +prometheus: + alertmanagerFiles: + alertmanager.yml: + global: + slack_api_url: {YOUR_WEBHOOK_URL} + route: + receiver: slack-notifications + receivers: + - name: slack-notifications + slack_configs: + - channel: '#your-channel' +``` + +And give it to the `helm install` command when [installing](../../../installation/install-controlplane/#2-preparing-control-plane-configuration-file-and-installing). + +``` +--values=values.yaml +``` + +See [here](https://prometheus.io/docs/alerting/latest/configuration/) for more details on AlertManager's configuration. + +## Piped agent metrics + +| Metric | Type | Description | +| --- | --- | --- | +| `cloudprovider_kubernetes_tool_calls_total` | counter | Number of calls made to run the tool like kubectl, kustomize. | +| `deployment_status` | gauge | The current status of deployment. 1 for current status, 0 for others. | +| `livestatestore_kubernetes_api_requests_total` | counter | Number of requests sent to kubernetes api server. | +| `livestatestore_kubernetes_resource_events_total` | counter | Number of resource events received from kubernetes server. | +| `plan_preview_command_handled_total` | counter | Total number of plan-preview commands handled at piped. | +| `plan_preview_command_handling_seconds` | histogram | Histogram of handling seconds of plan-preview commands. | +| `plan_preview_command_received_total` | counter | Total number of plan-preview commands received at piped. | + +## Control plane metrics + +All Piped's metrics are sent to the control plane so that they are also available on the control plane's metrics server. + +| Metric | Type | Description | +| --- | --- | --- | +| `cache_get_operation_total` | counter | Number of cache get operation while processing. | +| `grpcapi_create_deployment_total` | counter | Number of successful CreateDeployment RPC with project label. | +| `http_request_duration_milliseconds` | histogram | Histogram of request latencies in milliseconds. | +| `http_requests_total` | counter | Total number of HTTP requests. | +| `insight_application_total` | gauge | Number of applications currently controlled by control plane. | + +## Health Checking + +The below components expose their endpoint for health checking. +- server +- ops +- piped +- launcher (only when you run with designating the `launcher-admin-port` option.) + +The spec of the health check endpoint is as below. +- Path: `/healthz` +- Port: the same as admin server's port. 9085 by default. diff --git a/docs/content/en/docs-v1.0.x/user-guide/terraform-provider-pipecd.md b/docs/content/en/docs-v1.0.x/user-guide/terraform-provider-pipecd.md new file mode 100644 index 0000000000..5e62f0154b --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/terraform-provider-pipecd.md @@ -0,0 +1,68 @@ +--- +title: "PipeCD Terraform provider" +linkTitle: "PipeCD Terraform provider" +weight: 997 +description: > + This page describes how to manage PipeCD resources with Terraform using terraform-provider-pipecd. +--- + +Besides using web UI and command line tool, PipeCD community also provides Terraform module, [terraform-provider-pipecd](https://registry.terraform.io/providers/pipe-cd/pipecd/latest), which allows you to manage PipeCD resources. +This provider enables us to add, update, and delete PipeCD resources as Infrastructure as Code (IaC). Storing resources as code in a version control system like Git repository ensures more reliability, security, and makes it more friendly for engineers to manage PipeCD resources with the power of Git leverage. + +## Usage + +### Setup Terraform provider +Add terraform block to declare that you use PipeCD Terraform provider. You need to input a controle plane's host name and API key via provider settings or environment variables. API key is available on the web UI. + +```hcl +terraform { + required_providers { + pipecd = { + source = "pipe-cd/pipecd" + version = "0.1.0" + } + } + required_version = ">= 1.4" +} + +provider "pipecd" { + # pipecd_host = "" // optional, if not set, read from environments as PIPECD_HOST + # pipecd_api_key = "" // optional, if not set, read from environments as PIPECD_API_KEY +} +``` + +### Manage Piped agent +Add `pipecd_piped` resource to manage a Piped agent. + +```hcl +resource "pipecd_piped" "mypiped" { + name = "mypiped" + description = "This is my piped" + id = "my-piped-id" +} +``` + +### Adding a new application +Add `pipecd_application` resource to manage an application. + +```hcl +// CloudRun Application +resource "pipecd_application" "main" { + kind = "CLOUDRUN" + name = "example-application" + description = "This is the simple application" + platform_provider = "cloudrun-inproject" + piped_id = "your-piped-id" + git = { + repository_id = "examples" + remote = "git@github.com:pipe-cd/examples.git" + branch = "master" + path = "cloudrun/simple" + filename = "app.pipecd.yaml" + } +} +``` + +### You want more? + +We always want to add more needed resources into the Terraform provider. Please let the maintainers know what resources you want to add by creating issues in the [pipe-cd/terraform-provider-pipecd](https://github.com/pipe-cd/terraform-provider-pipecd/) repository. We also welcome your pull request to contribute! diff --git a/docs/static/images/insights.png b/docs/static/images/insights.png index 3c21419e2b..4cbdc03347 100644 Binary files a/docs/static/images/insights.png and b/docs/static/images/insights.png differ