diff --git a/hugo/config/_default/menus/main.en.yaml b/hugo/config/_default/menus/main.en.yaml index d054e57a3c7d..b2310a677984 100644 --- a/hugo/config/_default/menus/main.en.yaml +++ b/hugo/config/_default/menus/main.en.yaml @@ -6193,11 +6193,6 @@ menu: parent: deployment_gates_setup identifier: deployment_gates_setup_preconfigured weight: 2 - - name: Explore - url: deployment_gates/explore/ - parent: deployment_gates - identifier: deployment_gates_explore - weight: 2 - name: Test Optimization url: tests/ pre: ci diff --git a/hugo/content/en/deployment_gates/_index.md b/hugo/content/en/deployment_gates/_index.md index e348d3b27115..4dd0c87458c2 100644 --- a/hugo/content/en/deployment_gates/_index.md +++ b/hugo/content/en/deployment_gates/_index.md @@ -1,13 +1,12 @@ --- title: Deployment Gates -description: "Reduce deployment incidents by automatically evaluating monitors and APM anomalies to halt releases when performance regressions are detected." +description: "Reduce deployment incidents by evaluating monitors and APM Faulty Deployment Detection during a rollout, so your pipeline can halt releases when regressions are detected." +aliases: + - /deployment_gates/explore further_reading: - link: "/deployment_gates/setup" tag: "Documentation" text: "Set up Deployment Gates" -- link: "/deployment_gates/explore" - tag: "Documentation" - text: "Learn about the Deployment Gates explorer" - link: "continuous_delivery" tag: "Documentation" text: "Learn about Continuous Delivery Visibility" @@ -20,12 +19,77 @@ algolia: Deployment Gates allow you to reduce the likelihood and impact of incidents caused by deployments. -When performing a production rollout, you can use Deployment Gates to evaluate the impact of the new changes by using [monitors][1] and APM anomalies. -When anomalies or performance regressions are detected, you can automatically halt the release, preventing unstable code from reaching a wider user base. Additionally, you can then use Deployment Gates as the entry-point to investigate the problem. +When performing a production rollout, you can use Deployment Gates to evaluate the impact of new changes with [monitors][1] and [APM Faulty Deployment Detection][4]. When your gate detects a performance regression, you can automatically halt the release, preventing unstable code from reaching a wider user base. You can then use Deployment Gates as the entry point to investigate the problem. + +{{< img src="/deployment_gates/explore/deployment_gates_explorer.png" alt="The Deployment Gate evaluation page in Datadog" style="width:100%" >}} + +For setup instructions, see [Set up Deployment Gates][2]. + +## How Deployment Gates work + +A Deployment Gate has two main components: + +- **Gate**: A gate, defined for a given service and environment, evaluates one or more rules to decide whether a deployment should proceed. +- **Rule**: A [rule](#rules) checks the status of one or more [monitors][1] or runs [APM Faulty Deployment Detection][4] on the deployed version. The outcome determines whether the associated gate should pass or fail. + +Although a gate reports whether a regression is detected, it doesn't stop a deployment on its own. After receiving a gate evaluation result, your deployment pipeline decides what to do next—for example, halting the deployment, performing a rollback, or alerting your team. + +### Configuration sources + +A gate's configuration source is where the gate is defined: in the evaluation request itself, or in Datadog ahead of time. + +- **JIT**: A Just-In-Time (JIT) Deployment Gate is defined in your deployment configuration, such as a JSON configuration file passed to the [`datadog-ci` CLI][5] or the payload of an API call, and sent with each evaluation request. There is no setup in Datadog. +- **Preconfigured**: A preconfigured Deployment Gate is created ahead of time in Datadog, then referenced in an evaluation request. + +| | JIT | Preconfigured | +|---|---|---| +| **Where the gate is defined** | In your deployment configuration or CI step | In Datadog | +| **Setup in Datadog** | None | Create the gate and its rules before the first evaluation | +| **What the evaluation request contains** | The full gate configuration, including service, environment, and rules | Service, environment, and optionally identifier, which reference the preconfigured gate | +| **Does the gate have an ID?** | No, the gate exists only within each evaluation | Yes, the gate persists between evaluations | +| **Evaluations shown on [Evaluations][6] page?** | Yes | Yes | +| **Best for** | Managing rules as code alongside your pipeline, and teams that own their own gate configuration | Sharing rules across services, managing gates centrally, and editing rules outside of CI | + +You can use different configuration sources for different gates. If you're unsure where to start, use JIT gates. They require no setup in Datadog, and you can iterate on rules directly in your deployment configuration. + +## Rules + +A rule is a check that a Deployment Gate runs to decide whether a deployment can proceed. Each gate contains one or more rules, and all of them must pass for the gate to pass (when the gate and its rules are in [active mode](#evaluation-modes)). When your pipeline requests a gate evaluation, Datadog evaluates each rule against the service, environment, and version being deployed. Each rule resolves to pass or fail, and the gate's result is based on those outcomes. + +Each rule has a [type](#rule-types) and options specific to its type. Rules belong to the gate's [configuration source](#configuration-sources): JIT gates send their rules with each evaluation request, and preconfigured gates keep their rules in Datadog. + +You can set an individual rule's [evaluation mode](#evaluation-modes) to dry run, independently of the gate's evaluation mode. In an active gate, a dry run rule that fails is recorded but doesn't affect the gate's outcome. + +### Rule types + +Deployment Gates support two rule types: + +- [Monitor][1]: Checks the state of one or more [monitors][1] over a configurable period of up to two hours. The rule fails if a monitor enters an `Alert` or `No Data` status during that period. Indicate the monitor(s) to check using a monitor search query or by providing a monitor ID. +- [APM Faulty Deployment Detection][4]: Uses [Watchdog][7] to compare the deployed version against previous versions of the same service. The rule fails if the analysis detects new types of errors or a significant increase in error rates. The analysis runs over a configurable period of up to two hours. + +A gate can have one or more rules, including any combination of monitor and APM Faulty Deployment Detection rules. + +## Evaluations + +An evaluation is a single run of a gate's rules against a specific deployment. Evaluations are asynchronous—your pipeline triggers an evaluation, then checks back for the result while the rules run in the background. + +1. **Your pipeline requests a gate evaluation.** The request identifies the service, environment, and version being deployed. For a [JIT](#configuration-sources) gate, the request also contains the gate's rules. For a [preconfigured](#configuration-sources) gate, Datadog uses the service, environment, and optional identifier to find the gate. The version is required if the gate has an APM Faulty Deployment Detection rule. +2. **Datadog starts the evaluation.** The API immediately returns an evaluation ID, and each rule runs for its configured duration. +3. **Your pipeline polls for the result.** Your pipeline uses the evaluation ID to check the evaluation's status, which stays `in_progress` while the rules run. The [`datadog-ci` CLI][5] and the [GitHub Action][8] handle polling for you: they wait until the evaluation completes or a configurable timeout is reached. +4. **The evaluation resolves to `pass` or `fail`.** The gate passes if all of its active rules pass, and fails if any active rule fails. Your pipeline then decides how to proceed based on the result. + +Each evaluation and its per-rule results, including the reason a rule failed, are recorded on the [Deployment Gates Evaluations][6] page. Here, you can also identify frequently failing rules and gates and track patterns over time. + +### Evaluation modes + +Gates and rules each have an evaluation mode, which determines whether their results affect your deployment: + +- **Active**: The result counts. An active gate returns its actual result (`pass` or `fail`) to your pipeline, and an active rule's result counts toward the gate's result. +- **Dry run**: The result is recorded on the [Evaluations][6] page, but doesn't affect your deployment. A dry run gate always returns `pass` to your pipeline, and a dry run rule's result is excluded from the gate's result. -For setup instructions, see [Set up Deployment Gates][2]. After the setup is completed, you can track and analyze gate evaluations through the [Deployment Gates Evaluations][3] page: +Dry run lets you see how a gate or rule behaves against real deployments before it can block one, which is useful when onboarding or adding a new rule. When the results match what you expect, switch to active. -{{< img src="/deployment_gates/explore/deployment_gates_explorer.png" text="The Deployment Gate evaluation page in Datadog" style="width:100%" >}} +For JIT gates, set the evaluation mode with the `dry_run` field in the evaluation request (`dryRun` in `datadog-ci` configuration files). For preconfigured gates, use the {{< ui >}}Evaluation Mode{{< /ui >}} setting on the gate or rule. ## Further reading @@ -33,4 +97,8 @@ For setup instructions, see [Set up Deployment Gates][2]. After the setup is com [1]: /monitors/ [2]: /deployment_gates/setup -[3]: /deployment_gates/explore +[4]: /watchdog/faulty_deployment_detection/ +[5]: https://github.com/DataDog/datadog-ci/tree/master/packages/plugin-deployment#gate +[6]: https://app.datadoghq.com/ci/deployment-gates/evaluations +[7]: /watchdog +[8]: https://github.com/DataDog/deployment-gate-github-action diff --git a/hugo/content/en/deployment_gates/explore.md b/hugo/content/en/deployment_gates/explore.md deleted file mode 100644 index 23f441626cb0..000000000000 --- a/hugo/content/en/deployment_gates/explore.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Explore Deployment Gates -description: "View gate evaluations, identify frequently failing rules, analyze failure patterns, and track evaluation trends over time." -further_reading: -- link: "/deployment_gates/setup" - tag: "Documentation" - text: "Set up Deployment Gates" ---- - -To explore your Deployment Gates and rules evaluations, navigate to [{{< ui >}}Software Delivery{{< /ui >}} > {{< ui >}}Deployment Gates{{< /ui >}} > {{< ui >}}Evaluations{{< /ui >}}][1]. - -On this page you can: -* View recently completed gate evaluations and failure reasons -* Identify frequently failing rules and gates -* Analyze common failure patterns -* Track evaluation trends over time - -{{< img src="/deployment_gates/explore/deployment_gates_explorer.png" text="The Deployment Gate evaluation page in Datadog" style="width:100%" >}} - -## Further reading - -{{< partial name="whats-next/whats-next.html" >}} - -[1]: https://app.datadoghq.com/ci/deployment-gates/evaluations diff --git a/hugo/content/en/deployment_gates/setup/_index.md b/hugo/content/en/deployment_gates/setup/_index.md index 84869cc69601..75cc1f4ac3b4 100644 --- a/hugo/content/en/deployment_gates/setup/_index.md +++ b/hugo/content/en/deployment_gates/setup/_index.md @@ -1,6 +1,6 @@ --- title: Set Up Deployment Gates -description: "Compare Just-In-Time (JIT) and preconfigured Deployment Gates and follow the setup walkthrough for your chosen mode." +description: "Compare Just-In-Time (JIT) and preconfigured Deployment Gates and follow the setup walkthrough for your chosen configuration source." further_reading: - link: "/deployment_gates/setup/jit" tag: "Documentation" @@ -8,39 +8,20 @@ further_reading: - link: "/deployment_gates/setup/preconfigured" tag: "Documentation" text: "Set up preconfigured Deployment Gates" -- link: "/deployment_gates/explore" - tag: "Documentation" - text: "Learn about the Deployment Gates explorer" - link: "/api/latest/deployment-gates" tag: "API Reference" text: "Deployment Gates API reference" --- -Deployment Gates have two main components: - -- A **Gate** is defined for a service and environment (and optionally an identifier), and evaluates one or more rules to decide whether a deployment should proceed. -- A **Rule** is a type of evaluation performed as part of a gate, such as checking the status of a set of monitors or running APM Faulty Deployment Detection analysis on the deployed version. - -Gate evaluations are asynchronous — the API returns immediately with an evaluation ID, and the result resolves to `pass` or `fail` over time as the rules run. - -## Deployment Gate evaluation modes -Deployment Gates support two evaluation modes: Just-In-Time (JIT) and preconfigured. - - -| | **[JIT][1]** (default) | **[Preconfigured][2]** | -|---|---|---| -| **Where rules live** | Inline in your deployment configuration or CI step | Persisted in Datadog (UI, API, or Terraform) | -| **Setup in Datadog** | None | Create a gate and rules ahead of time | -| **Best for** | Rules-as-code, per-deployment flexibility, teams that own their own gate configuration | Shared rules across services, central management, non-CI editing | -| **How to evaluate** | Send rules in the evaluation request | Reference the gate by service, environment, and optionally identifier | - -You can use different modes across different gates if needed. +Choose where your Deployment Gates are defined, then follow the setup instructions. For a comparison of the two configuration sources, see [Configuration sources][1]. -If you're unsure where to start, use JIT. It requires no setup in Datadog and lets you iterate on rules directly in your deployment configuration. +{{< whatsnext desc="Set up Deployment Gates:" >}} + {{< nextlink href="/deployment_gates/setup/jit" >}}Just-In-Time (JIT): Define gates and rules in your deployment configuration, with no setup in Datadog.{{< /nextlink >}} + {{< nextlink href="/deployment_gates/setup/preconfigured" >}}Preconfigured: Create gates and rules in Datadog with the UI, API, or Terraform.{{< /nextlink >}} +{{< /whatsnext >}} ## Further reading {{< partial name="whats-next/whats-next.html" >}} -[1]: /deployment_gates/setup/jit -[2]: /deployment_gates/setup/preconfigured +[1]: /deployment_gates/#configuration-sources diff --git a/hugo/content/en/deployment_gates/setup/jit.md b/hugo/content/en/deployment_gates/setup/jit.md index 120abc351722..537e5c31d32c 100644 --- a/hugo/content/en/deployment_gates/setup/jit.md +++ b/hugo/content/en/deployment_gates/setup/jit.md @@ -5,9 +5,6 @@ further_reading: - link: "/deployment_gates/setup/preconfigured" tag: "Documentation" text: "Set up preconfigured Deployment Gates" -- link: "/deployment_gates/explore" - tag: "Documentation" - text: "Learn about the Deployment Gates explorer" - link: "/api/latest/deployment-gates" tag: "API Reference" text: "Deployment Gates API reference" diff --git a/hugo/content/en/deployment_gates/setup/preconfigured.md b/hugo/content/en/deployment_gates/setup/preconfigured.md index f4bff345ecea..60ac8b41a07f 100644 --- a/hugo/content/en/deployment_gates/setup/preconfigured.md +++ b/hugo/content/en/deployment_gates/setup/preconfigured.md @@ -5,9 +5,6 @@ further_reading: - link: "/deployment_gates/setup/jit" tag: "Documentation" text: "Set up Just-In-Time (JIT) Deployment Gates" -- link: "/deployment_gates/explore" - tag: "Documentation" - text: "Learn about the Deployment Gates explorer" - link: "/api/latest/deployment-gates" tag: "API Reference" text: "Deployment Gates API reference"