> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Distribute Traffic Between Canary Deployments

> Use ngrok to validate how features or versions of your services behave by distributing production traffic randomly or via a specific header.

export const domain_0 = undefined

Canary deployments are a trusted method for rolling out new features or major versions of your services.
By controlling who accesses the new version, either through the random distribution of traffic or a specific header attached to requests from certain customers, you can see exactly if and where something breaks before releasing it to all your users.

With ngrok, you can handle ingress to canary deployments by:

* Choosing between random distribution across all your customers or applying a specific header to some customers' requests to opt them in to a new version, that is, a feature flag.
* Applying different policies to each version depending on how they behave.
* Testing a migration from one environment to another, like on-premises VMs to a cloud-based Kubernetes cluster.

## 1. Create endpoints for your services

Start internal [Agent Endpoints](/gateway/agent-endpoints/), replacing `$PORT` based on where your service listens, for each of your services on the systems where they run.
You can also use one of the [SDKs](/agent-sdks/#example-usage) or the [Kubernetes Operator](/getting-started/kubernetes/ingress/).

```bash theme={null}
ngrok http $PORT --url https://service.internal
ngrok http $PORT --url https://service-canary.internal
```

## 2. Reserve a domain

Navigate to the [**Domains** section](https://dashboard.ngrok.com/domains) of the ngrok dashboard and click **New +** to reserve a free static domain like {<code>{domain_0}</code> || `https://your-service.ngrok.app`} or a [custom domain](/gateway/custom-domains/) you already own.

We'll refer to this domain as `$NGROK_DOMAIN` from here on out.

## 3. Create a Cloud Endpoint

Navigate to the [**Endpoints** section](https://dashboard.ngrok.com/endpoints?sortBy=updatedAt\&orderBy=desc) of the ngrok dashboard, then click **New +** and **Cloud Endpoint**.

In the **URL** field, enter the domain you just reserved to finish creating your [Cloud Endpoint](/gateway/cloud-endpoints/).

## 4. Add canary routing with Traffic Policy

While viewing your new Cloud Endpoint in the dashboard, copy one of the two policies below and paste it into the Traffic Policy editor.
The choice depends on whether you want to distribute traffic randomly or by a header like `x-canary`.

<Tabs>
  <Tab title="Random distribution">
    ```yaml theme={null}
    on_http_request:
      - expressions:
          - "rand.double() <= 0.2"
        actions:
          - type: forward-internal
            config:
              url: https://service-canary.internal

      - actions:
          - type: forward-internal
            config:
              url: https://service.internal
    ```

    **What's happening here?**
    This policy first returns a random `double` between `0` and `1`.
    If that double is less than or equal to `0.2`, it routes the request to your canary deployment, effectively routing 20% of incoming traffic to the canary.

    The policy then routes the remaining 80% of traffic to your stable version.
  </Tab>

  <Tab title="By header">
    ```yaml theme={null}
    on_http_request:
      - expressions:
          - "req.headers.exists_one(x, x == 'x-canary')"
          - "req.headers['x-canary'].join(',') == 'true'"
        actions:
          - type: forward-internal
            config:
              url: https://service-canary.internal

      - actions:
          - type: forward-internal
            config:
              url: https://service.internal
    ```

    **What's happening here?**
    This policy checks the incoming request for the presence of the `x-canary` and validates that its value is `true`.
    If both are true, then the policy routes the request to your canary deployment.

    In the absence of an `x-canary: true` header, the policy route traffic to your stable version.
  </Tab>
</Tabs>

## 5. Try out your endpoints

Visit the domain you reserved either in the browser or in the terminal using a tool like `curl`.
If you chose random distribution, you should see each service responding at roughly the percentage you defined.
If you choose to distribute by header, add `x-canary: true` to your requests to verify ngrok is routing traffic to your canary.

## 6. Tweak the distribution to your canary

If you opted for random distribution, you should increase the volume of traffic forwarded to your canary at regular intervals as you gain confidence in its stability.
For example, to split traffic evenly between your two versions:

```yaml theme={null}
on_http_request:
  - expressions:
      - "rand.double() <= 0.5"
    actions:
      - type: forward-internal
        config:
          url: https://service-canary.internal

  - actions:
      - type: forward-internal
        config:
          url: https://service.internal
```

## 7. Cut over to the new version and clean up

When you promote your canary deployment to stable, you can edit your policy to route traffic to the new version and close down the ngrok agent forwarding to `https://service.internal`.

```yaml theme={null}
on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://service-canary.internal
```

If you want to maintain `https://service.internal` as the canonical name for the stable production deployment, you can:

1. Start another agent forwarding to your new version at this canonical internal URL.
2. Edit your policy to route to it.
3. Shut down the agent forwarding to `https://service-canary.internal`.

## What's next?

* View your [Traffic
  Inspector](https://dashboard.ngrok.com/traffic-inspector) to see how your canary behaves with production traffic, which may signal that you pause or roll back the deployment entirely.
* Learn how to implement [blue-green deployments](/gateway/examples/blue-green-deployments) if you prefer faster rollouts at the expense of maintaining two production environments.
* Explore other common gateway setups, like [multiplexing to many
  services](/gateway/examples/multiplex) or shipping a [custom "maintenance mode"](/gateway/examples/maintenance-mode/) during an outage or planned downtime.
* Start automating your deployment strategies with the ngrok [API](/api/) or the [Kubernetes Operator](/k8s/).