---
title: "Promote Deployment"
method: POST
path: "/api/v1/deployments/{deployment_id}/promote"
tags: ["deployments"]
---

# Promote Deployment

`POST /api/v1/deployments/{deployment_id}/promote`

## Request

- Base URL: `https://api.mengi.cloud` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mengi.cloud/api/v1/deployments/{deployment_id}/promote`
- Auth: none declared

Promote/migrate a deployment to another cluster.

This copies the deployment configuration to a new cluster without
migrating any state or persistent data. The new deployment will
start fresh on the target cluster.

The promotion is performed asynchronously by the worker. The new
deployment is created with PROMOTING status and will transition
to RUNNING when complete.

Use cases:
- Shared vCluster → Dedicated cluster (scaling up)
- Dedicated cluster → Dedicated cluster (region/provider change)
- Dedicated cluster → Shared vCluster (scaling down for cost savings)

## Path parameters

- `deployment_id` string, uuid, required

## Request body

- DeploymentPromotionRequest: Request to promote/migrate a deployment to another cluster.
  - `target_cluster_id` string, uuid, required
  - `new_name` string, nullable
  - `delete_source` boolean
  - `overrides` DeploymentUpdate
    - `name` string, nullable
    - `config` object, nullable
    - `cpu_request` number, nullable
    - `memory_request_mb` integer, nullable
    - `replicas` integer, nullable
    - `container_port` integer, nullable
    - `storage_size_gb` integer, nullable
    - `environment_variables` EnvironmentVariable[], nullable
      - `name` string, required
      - `value` string, nullable
      - `secret_ref` string, nullable
    - `docker_image` string, nullable
    - `volumes` VolumeConfig[], nullable
      - `path` string, required
      - `sizeGb` integer
      - `purpose` string, nullable
    - `helm_chart_version` string, nullable
    - `custom_values_yaml` string, nullable
    - `image_update_strategy` string, nullable
    - `image_update_constraint` string, nullable
    - `image_allow_tags` string, nullable
    - `image_ignore_tags` string, nullable
    - `custom_domain` string, nullable
    - `failover_health_route` boolean, nullable
    - `helm_ingress_values` boolean, nullable
    - `health_checks` HealthChecksConfig: Container health check configuration (stored in the deployment config). On update, an empty object clears any overrides and restores automatic detection.
      - `liveness` HealthCheckProbe: One container health check (liveness or readiness probe). All fields except `enabled` are optional: an unset `type` keeps the auto-detected HTTP/TCP choice, an unset `path` keeps the detected endpoint, and unset timings keep the platform defaults.
        - `enabled` boolean
        - `type` 'http' | 'tcp', nullable
        - `path` string, nullable
        - `initial_delay_seconds` integer, nullable
        - `period_seconds` integer, nullable
        - `timeout_seconds` integer, nullable
        - `failure_threshold` integer, nullable
      - `readiness` HealthCheckProbe: One container health check (liveness or readiness probe). All fields except `enabled` are optional: an unset `type` keeps the auto-detected HTTP/TCP choice, an unset `path` keeps the detected endpoint, and unset timings keep the platform defaults.
        - `enabled` boolean
        - `type` 'http' | 'tcp', nullable
        - `path` string, nullable
        - `initial_delay_seconds` integer, nullable
        - `period_seconds` integer, nullable
        - `timeout_seconds` integer, nullable
        - `failure_threshold` integer, nullable
      - `startup` HealthCheckProbe: One container health check (liveness or readiness probe). All fields except `enabled` are optional: an unset `type` keeps the auto-detected HTTP/TCP choice, an unset `path` keeps the detected endpoint, and unset timings keep the platform defaults.
        - `enabled` boolean
        - `type` 'http' | 'tcp', nullable
        - `path` string, nullable
        - `initial_delay_seconds` integer, nullable
        - `period_seconds` integer, nullable
        - `timeout_seconds` integer, nullable
        - `failure_threshold` integer, nullable
    - `additional_ports` AdditionalPort[], nullable
      - `port` integer, required
      - `name` string, nullable
      - `protocol` 'TCP' | 'UDP', nullable
    - `backups` BackupsConfig: Scheduled backup configuration (stored in the deployment config). Backups capture the deployment's namespace: workload configuration, in-namespace secrets, and all persistent volume data. Managed databases are excluded — they have their own backup mechanism. Requires a dedicated cluster and the "backups" feature flag.
      - `enabled` boolean
      - `schedule` 'hourly' | 'daily' | 'weekly'
      - `retention_days` integer
    - `command` string[], nullable
    - `args` string[], nullable

## Response `200`

Successful Response

- DeploymentPromotionResponse: Response after promoting a deployment.
  - `source_deployment_id` string, uuid, required
  - `new_deployment_id` string, uuid, required
  - `target_cluster_id` string, uuid, required
  - `source_deleted` boolean, required
  - `message` string, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-20** `4ae9b375cdbb`: 1 info
  - added the new optional request property `overrides/anyOf[subschema #1: DeploymentUpdate]/helm_ingress_values`

[Operation history](https://skmtc.dev/mengi/apis/mengi-cloud/changes/api/v1/deployments/:deployment_id/promote/post.md)

---

[API](https://skmtc.dev/mengi/apis/mengi-cloud.md) · [All operations](https://skmtc.dev/mengi/apis/mengi-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/mengi/apis/mengi-cloud/revisions/4ae9b375cdbb?raw)