Creating documentations for ZDT and Version Pininning

content/en/docs/deployment/mendix-cloud-deploy/environments.md

@@ -147,7 +147,7 @@ Follow these steps to deploy packages to selected environments using the **Deplo
     * If you launched the wizard by selecting an environment, the first screen of the wizard is the **Select Package** tab. Use it to select a package from the repository.
     * If you launched the wizard by selecting a package, the first screen of the wizard is the **Select Environment** tab. Use it to select the target environment for your package.
 3. On the **Configure Environment** tab, review the [constants](/refguide/constants/) and adjust them as required.
-4. In the **Other Options** tab, choose whether to stage the package without deploying, and when to create the backup: either before or after deploying the new package. The app is unavailable while the backup runs.
+4. In the **Other Options** tab, choose whether to stage the package without deploying, and when to create the backup: either before or after deploying the new package. The app is unavailable while the backup runs. You can also choose to deploy with [zero-downtime](/developerportal/deploy/zero-downtime/).
 5. On the **Deploy** tab, review the deployment settings:
     1. To see an overview of the configuration for this deployment, click **View Summary**. This summary displays the selected package, selected backup option, and any changed constants or [scheduled events](/refguide/scheduled-events/).
     2. Review this summary, then click **Deploy Now**.
@@ -217,3 +217,7 @@ The Technical Contact can only see services that have been licensed for their co
 Team members who have a role with **Cloud Access** can see which services are enabled or disabled.
 
 Once a service has been enabled for an app, Technical Contacts can selectively enable it for each environment. For more information, refer to the [Services](/developerportal/deploy/environments-details/#services) section of the *Environment Details* page.
+
+## Read More
+
+* [Version Pinning](/developerportal/deploy/version-pinning/)

content/en/docs/deployment/mendix-cloud-deploy/version-pinning.md

@@ -0,0 +1,93 @@
+---
+title: "Version Pinning"
+linktitle: "Version Pinning"
+url: /developerportal/deploy/version-pinning/
+weight: 80
+description: ""
+
+#Do NOT remove any of the anchors in this document as they are all referenced from other documents
+---
+
+{{% alert color="warning" %}}
+This feature is in Limited Availability. For more information, see [Release Status](/releasenotes/release-status/#limited-availability).
+{{% /alert %}}
+
+## Introduction
+
+Mendix Cloud provides version pinning to guarantee consistency and predictability when promoting your Mendix applications between different environments on Mendix Cloud (Kubernetes). For example, when you move an application from an acceptance environment to a production environment, version pinning ensures that the exact same underlying platform configuration is reused. This includes components critical to how your application runs in Mendix Cloud, such as runtime images, buildpacks, and supporting services, all of which remain identical across environments.
+
+By maintaining a consistent runtime stack, version pinning effectively eliminates subtle environmental differences, leading to more reliable and predictable application behavior throughout your development and deployment landscape.
+
+{{% alert color="warning" %}}
+This feature is only applicable to promotions between environments on Mendix Cloud (Kubernetes).
+{{% /alert %}}
+
+## Prerequisites
+
+You must meet the following conditions to use version pinning:
+
+* **Company-level enablement** – Version Pinning must first be enabled at the company-level.
+* **Mendix Cloud (Kubernetes) environment** – Your Mendix applications must be deployed to and running within environments hosted on Mendix Cloud (Kubernetes)
+* **Environment promotion** – You must be promoting an application from one environment to another (for example from test to acceptance, or acceptance to production).
+* **Same application, same company** – Both the source and target environments must belong to the same application within the same company.
+
+## Understanding Version Pinning
+
+Version pinning ensures that the platform configuration used for your application remains consistent across different stages of your deployment pipeline. This includes:
+
+* **Initial deployment** – When you deploy a new application build (or perform a first-time deployment), Mendix Cloud automatically uses the latest validated platform configuration available for that deployment.
+* **Environment promotion** – When you promote an application from a source environment (e.g., acceptance) to a target or higher environment (e.g., production), version pinning automatically reuses the exact same platform configuration that was active in the source environment. This ensures that the combination of runtime images, buildpacks, and supporting components you tested in your source environment is precisely what runs in the target environment.
+
+### Key Advantages
+
+Using version pinning provides the following benefits for your Mendix application lifecycle:
+
+* **Environments consistency** – Guarantees that what you test and validate in one environment is precisely what runs in higher-level environments.
+* **Improved stability** – Eliminates unexpected differences in runtime behavior that can arise from environmental variations.
+* **Enhanced security and compliance** – Ensures your applications consistently run on the latest, patched components, as managed by Mendix Cloud.
+* **Zero manual setup** – The pinning process is automatically handled by Mendix Cloud, requiring no additional manual configuration steps.
+
+## Version Pinning Workflow
+
+Version pinning integrates seamlessly into your deployment workflow, whether you're using the Mendix Cloud Portal or the Mendix Cloud API. The diagram below illustrates these two primary methods:
+
+{{< figure src="/attachments/deployment/mendix-cloud-deploy/version-pinning/version-pinning-workflow.png" alt="Sequence diagram showing version pinning workflows via Cloud Portal and API.">}}
+
+### Option 1 – Promote via Mendix Cloud Portal
+
+{{< figure src="/attachments/deployment/mendix-cloud-deploy/version-pinning/version-pinning-via-cloud-portal.png" >}}
+
+Initiate a promotion directly through the Mendix Cloud Portal:
+
+1. **Action** – Click **Promote** by following the steps in [Deploying a Package](/developerportal/deploy/environments/#deploy-wizard).
+2. **Configuration reading** – The Mendix Cloud Portal reads the current platform configuration details from your source environment.
+3. **Deployment with pinning** – The application is then deployed to the target environment, using this pinned configuration.
+4. **Confirmation** – The Cloud Portal displays a banner or confirmation message indicating that the runtime stack configuration has been successfully pinned from the source to the target environment, guaranteeing a consistent deployment outcome. 
+    {{< figure src="/attachments/deployment/mendix-cloud-deploy/version-pinning/version-pinning-banner.png" >}}
+
+### Option 2 – Deployment via API
+
+{{< figure src="/attachments/deployment/mendix-cloud-deploy/version-pinning/version-pinning-using-start-api.png" >}}
+
+For automated or programmatic deployments, use the Mendix Cloud API:
+
+1. **API call** – Call the Mendix Cloud Start API, specifying the target environment and including the `pinEnvironment` parameter to indicate the source environment from which to pin the configuration.
+
+    ```http
+    POST /api/1/apps/{AppID}/environments/{Environment}/start?pinEnvironment={SourceEnvironmentId}
+    ```
+
+2. **Configuration fetching** – The Start API fetches the platform configuration.
+3. **Deployment with pinning** – The application is deployed to the target environment, using these fetched, identical configuration versions.
+4. **Job ID return** – The API returns a success response, typically including a `JobId`, confirming the initiation of the pinned deployment.
+
+## Expected Behavior Scenarios
+
+The following table summarizes the expected behavior of version pinning in different deployment scenarios:
+
+| Scenario                                    | Behavior                                                      |
+| :------------------------------------------ | :------------------------------------------------------------ |
+| Deploying a new MDA or first-time deployment | Uses the latest Mendix Cloud platform configuration           |
+| Promoting between environments              | Uses the same platform configuration as the source environment |
+
+

content/en/docs/deployment/mendix-cloud-deploy/zero-downtime.md

@@ -0,0 +1,118 @@
+---
+title: "Zero Downtime"
+linktitle: "Zero Downtime"
+url: /developerportal/deploy/zero-downtime/
+weight: 80
+description: ""
+
+#Do NOT remove any of the anchors in this document as they are all referenced from other documents
+---
+
+{{% alert color="warning" %}}
+This feature is in Limited Availability. For more information, see [Release Status](/releasenotes/release-status/#limited-availability).
+{{% /alert %}}
+
+## Introduction
+
+Zero-Downtime Deployment (ZDT) is a deployment capability that enables Mendix applications to apply certain configuration updates without any service interruption. This feature ensures continuous application availability during configuration changes, allowing end users to remain connected throughout the deployment process.
+
+With ZDT, Mendix Cloud intelligently manages the deployment process, ensuring your application remains online and fully functional throughout updates to reduce the impact of routine maintenance and configuration changes and enhance the overall reliability and user experience of your Mendix applications.
+
+## Prerequisites
+
+To leverage the benefits of zero-downtime deployment, your Mendix application and deployment environment must meet the following criteria:
+
+* **Mendix runtime version** – Must be running on Mendix Runtime version 10.24 or higher.
+* **Application instances** – The application must be configured to run with a single runtime instance.
+* **Change type** – The deployment must involve only [configuration-level changes](/developerportal/deploy/zero-downtime/#zdt-application).
+* **Deployment platform** – Must be deployed on Mendix Cloud(Kubernetes).
+
+{{% alert color="info" %}}
+No special setup is required to enable ZDT. When your application and deployment meet these prerequisites, ZDT is automatically applied for eligible changes and can be controlled directly by Technical Contacts through the [Environment Settings](/developerportal/deploy/environments/#environment-settings).
+{{% /alert %}}
+
+## How Zero-Downtime Deployment Works
+
+{{< figure src="/attachments/deployment/mendix-cloud-deploy/zero-downtime/zdt-process.png" alt="Sequence diagram illustrating the Zero-Downtime Deployment process, showing user initiating deployment, Mendix Cloud starting a new app version in the background while the current version serves users, the new version preparing configuration and reporting ready, Mendix Cloud gracefully stopping the old version, and finally directing traffic to the new version without user interruption." >}}
+
+When an eligible configuration change is deployed with ZDT enabled, Mendix Cloud orchestrates the following steps:
+
+1. **Initiate deployment** – A user or automated process triggers a deployment in Mendix Cloud.
+2. **Current version active** – The existing application version continues to serve all user traffic without interruption.
+3. **New version spin-up** – Mendix Cloud starts a new instance of your application, adding the updated configuration, in the background. This new version prepares its configuration.
+4. **Health check & readiness** – Once the new instance is fully operational and passes all internal health checks, it reports its readiness to Mendix Cloud.
+5. **Graceful shutdown of old version** – Mendix Cloud then gracefully stops the old application version, ensuring any ongoing processes or sessions are handled appropriately.
+6. **Traffic reroute** – Mendix Cloud directs all incoming user traffic to the newly deployed, healthy application version.
+7. **Continuous user experience** – The end-user experiences no downtime or interruption, as they are continuously served by a running instance of the application throughout the entire deployment process.
+
+## Managing Zero-Downtime Deployment
+
+By default, this option is off. In this state, your app will use the standard restart process during deployment. This default setting ensures stability and compatibility with existing application behavior.
+
+Technical Contacts can decide whether to attempt a zero-downtime deployment by selecting the **Deploy without downtime** option on the **Other Options** tab when [deploying a package](/developerportal/deploy/environments/#deploy-wizard). If you enable this option, Mendix Cloud will attempt a zero-downtime deployment, if your environment meets eligibility criteria.
+
+When a technical contact enables ZDT, the Cloud Portal displays a reminder to review any custom **before-shutdown** or **after-startup** microflows. This is crucial to confirm they won't cause issues during the period when two versions of your application might be running concurrently.
+
+### When ZDT Applies {#zdt-application}
+
+Zero-downtime deployment is specifically designed for changes that do not require rebuilding or replacing your application package. These are typically configuration-only updates.
+
+Examples of changes that qualify for ZDT include:
+
+* Restarting the environment 
+* Updating environment variables or constants
+* Adjusting log-level settings
+* Changing resource limits, such as CPU or memory allocation
+* Rotating credentials or API keys
+* Other configuration updates made directly through the Cloud Portal
+During these types of updates, Mendix Cloud performs the deployment in a way that keeps your environment continuously available.
+
+### When ZDT Does Not Apply
+
+Zero-downtime deployment will not apply under the following conditions:
+
+* Mendix Runtime version is less than 10.24
+* Application runs with more than one runtime instance
+* Upgrading to a new Mendix Runtime version
+* Deploying a new MDA (application model update)
+* Changes involve database structure updates
+    {{< figure src="/attachments/deployment/mendix-cloud-deploy/zero-downtime/zdt-scaling-process.png" >}}
+
+For these scenarios, the Cloud Portal will display the standard restart message before deployment:
+{{< figure src="/attachments/deployment/mendix-cloud-deploy/zero-downtime/zdt-scaling-messages.png" >}}
+
+## Expected ZDT Behavior
+
+The table below illustrates the expected behavior for various types of deployment changes:
+
+| Scenario                                        | Expected Behavior                                                    |
+| :------------------------------------------------------ | :------------------------------------------------------------------- |
+| Changing constants, environment variables, or log levels | Deployment completes without downtime.                              |
+| Adjusting CPU or memory settings                        | App remains available while the update completes.                    |
+| Uploading a new MDA or changing the data model          | Application restarts briefly (standard restart required).            |
+| Upgrading to a new Mendix Runtime version               | Standard restart required.                                           |
+
+### Before Deployment
+
+When a deployment qualifies for zero-downtime, the **Deploy Wizard** clearly communicates this in the final step via a banner indicating that the environment will be updated with zero downtime, ensuring continuous availability during the update.
+
+### During Deployment
+
+{{< figure src="/attachments/deployment/mendix-cloud-deploy/zero-downtime/zdt-deployment.png" >}}
+For eligible environments, the **Deploy Wizard** clearly indicates that the upcoming deployment will be performed without downtime. If a later deployment involves model or runtime changes, the standard restart flow will automatically be used, and the banner will update accordingly.
+
+### First Deployment
+
+When you deploy an application on Mendix Runtime 10.24 or higher for the very first time, the environment is automatically prepared for future zero-downtime deployments. This initial deployment behaves like a regular one, but from the next deployment onward, eligible configuration changes can be applied without downtime.
+
+### During a Zero-Downtime Deployment Failure
+
+{{< figure src="/attachments/deployment/mendix-cloud-deploy/zero-downtime/zdt-error.png" >}}
+
+If a zero-downtime deployment fails, an error message appears in the **Deploy Wizard**. The application itself remains running and available, because the previous version of the app continues to serve traffic.
+You can review the error details in the wizard and re-deploy once the issue is resolved.
+
+## Summary
+
+Zero-downtime deployment ensures that supported Mendix applications remain available during configuration updates.
+If you see the **Zero-Downtime** badge in your Cloud Portal environment, you can safely deploy configuration changes knowing your app will stay online throughout the process.