docs: document existing ACR image deployment (#6967)

docs/SUMMARY.md

@@ -166,6 +166,7 @@
   * [Connect Expressjs With Mongodb Database](user-guide/use-cases/connect-expressjs-with-mongodb-database.md)
   * [Connect Django With Mysql Database](user-guide/use-cases/connect-django-with-mysql-database.md)
   * [Pull Helm Charts from OCI Registry](user-guide/use-cases/oci-pull.md)
+  * [Deploy an Image from Azure Container Registry](user-guide/use-cases/deploy-existing-acr-image.md)
 * [Telemetry Overview](user-guide/telemetry.md)
 * [Devtron on Graviton](reference/graviton.md)
 * [Release Notes](https://github.com/devtron-labs/devtron/releases)

docs/user-guide/creating-application/workflow/ci-pipeline.md

@@ -232,9 +232,13 @@ Linked CI pipelines can't trigger builds. They rely on the source CI pipeline to
 
 ### 3. Deploy Image from External Service
 
-For CI pipeline, you can receive container images from an external services via webhook API.
+Devtron can receive container images from an external service through a webhook API.
 
-You can use Devtron for deployments on Kubernetes while using an external CI tool such as Jenkins or CircleCI. External CI feature can be used when the CI tool is hosted outside the Devtron platform. However, by using an external CI, you will not be able to use some of the Devtron features such as Image scanning and security policies, configuring pre-post CI stages etc. 
+You can use Devtron for deployments on Kubernetes while using an external CI tool such as Jenkins or CircleCI. Use External CI when the CI tool is hosted outside Devtron. However, External CI does not support some Devtron features such as image scanning, security policies, and pre-build or post-build stages.
+
+{% hint style="info" %}
+To deploy an image that was built manually and already exists in Azure Container Registry, see [Deploy an Image from Azure Container Registry](../../use-cases/deploy-existing-acr-image.md#deploy-an-existing-acr-image).
+{% endhint %}
 
 
 * Create a [new](../../create-application.md) or [clone](../../cloning-application.md) an application.
@@ -298,7 +302,7 @@ You can send the Payload script to your CI tools such as Jenkins and Devtron wil
 curl --location --request POST \
 'https://{domain-name}/orchestrator/webhook/ext-ci/{pipeline-id}' \
 --header 'Content-Type: application/json' \
---header 'token: {token}' \
+--header 'api-token: {token}' \
 --data-raw '{
     "dockerImage": "445808685819.dkr.ecr.us-east-2.amazonaws.com/orch:23907713-2"
 }'

docs/user-guide/use-cases/README.md

@@ -11,3 +11,5 @@ In this comprehensive guide, you will find a wide range of use cases, illustrati
 [Connect Expressjs With Mongodb Database](connect-expressjs-with-mongodb-database.md)
 
 [Connect Django With Mysql Database](connect-django-with-mysql-database.md)
+
+[Deploy an Image from Azure Container Registry](deploy-existing-acr-image.md)

docs/user-guide/use-cases/deploy-existing-acr-image.md

@@ -0,0 +1,85 @@
+# Deploy an Image from Azure Container Registry
+
+You can use an existing Azure Container Registry (ACR) with Devtron in either of the following ways:
+
+* [Build an image manually in Devtron and push it to ACR](#build-and-push-an-image-to-acr)
+* [Deploy an image that already exists in ACR](#deploy-an-existing-acr-image)
+
+## Build and Push an Image to ACR
+
+Use this method when Devtron should build the image from source code, but the build should start only when a user triggers it.
+
+### Prerequisites
+
+* An ACR repository and credentials that can push images to it.
+* A Git repository containing the application source code.
+
+### Steps
+
+1. Go to **Global Configurations** → **Container/OCI Registry** and [add the ACR registry](../global-configurations/container-registries.md#azure). Use the ACR login server, for example, `myregistry.azurecr.io`, and configure [Registry Credential Access](../global-configurations/container-registries.md#registry-credential-access) for the target cluster.
+2. In the application's [Build Configuration](../creating-application/docker-build-configuration.md#store-container-image), select the ACR registry and enter the target container repository.
+3. In **App Configuration** → **Workflow Editor**, create a **Build and Deploy from Source Code** workflow.
+4. In the build stage, set **Trigger Build Pipeline** to **Manually** and create the pipeline.
+5. Go to **Build & Deploy**, click **Select Material**, choose the Git commit, and click **Start Build**. Devtron builds the image and pushes it to the configured ACR repository.
+6. In the CD pipeline, click **Select Image**, choose the image produced by the build, and click **Deploy**.
+
+## Deploy an Existing ACR Image
+
+Use this method when the image was built outside Devtron and is already available in ACR. Devtron registers the image through an External CI webhook; it does not rebuild or copy the image.
+
+### Prerequisites
+
+* The complete image reference, including its tag, for example, `myregistry.azurecr.io/backend:v1.0.0`.
+* Pull access from the target Kubernetes cluster to the ACR registry.
+
+For an AKS cluster that already has pull access to ACR, no additional registry secret is required. Otherwise, create an image pull secret in the namespace used by the Devtron environment:
+
+```bash
+kubectl create secret docker-registry acr-pull-secret \
+    --namespace <target-namespace> \
+    --docker-server=<registry-name>.azurecr.io \
+    --docker-username=<username> \
+    --docker-password=<password>
+```
+
+Add the secret to the application's **Base Deployment Template**:
+
+```yaml
+imagePullSecrets:
+  - name: acr-pull-secret
+```
+
+{% hint style="warning" %}
+Avoid entering credentials directly in commands that might be stored in shell history. Use your organization's approved secret-management method where possible.
+{% endhint %}
+
+### Create a Manual Deployment Pipeline
+
+1. Create or select an application and configure its **Base Deployment Template**.
+2. Go to **App Configuration** → **Workflow Editor** and click **+ New Workflow**.
+3. Select **Deploy image from external service**.
+4. Select the target environment and set **When do you want to deploy** to **Manual**.
+5. Configure the deployment strategy and click **Create Pipeline**.
+6. Click **Show webhook details** and select or generate an API token. Only a super-admin can select or generate the token from this page.
+
+### Register the Existing Image
+
+Use the cURL request generated on the **Webhook Details** page, or send the following request with the complete ACR image reference:
+
+```bash
+curl --location --request POST \
+    'https://<devtron-host>/orchestrator/webhook/ext-ci/<pipeline-id>' \
+    --header 'Content-Type: application/json' \
+    --header 'api-token: <api-token>' \
+    --data-raw '{
+        "dockerImage": "myregistry.azurecr.io/backend:v1.0.0"
+    }'
+```
+
+A successful request adds the image to the manual deployment pipeline. Go to **Build & Deploy**, click **Select Image**, select the registered ACR image, and click **Deploy**.
+
+{% hint style="info" %}
+With a manual deployment pipeline, receiving the webhook does not deploy the image automatically. It makes the image available for selection in the CD pipeline.
+{% endhint %}
+
+If the deployment reports `ImagePullBackOff`, verify that the image reference is correct and that the target namespace can authenticate to ACR. See [Registry Credential Access](../global-configurations/container-registries.md#registry-credential-access) for more information.