EKS Deployment
===============

This page covers Neo Code Agents whose **Deployment Type** is **EKS Deployment**, where Neo runs your container on the platform's cluster. If your agent uses **External URL**, you deploy it yourself and the platform calls it.

Deploying and undeploying require the **Deploy / Undeploy Remote Agent** permission. See :doc:`permissions`.

.. Screenshot needed: the Deployment status strip above Remote Agent Details (neo-code-agent-deployment-status.png)

How It Works
-------------

You supply an image in AWS ECR and its runtime settings (see :doc:`creating`). On deploy, the platform pulls that image, runs it on the cluster, and resolves the agent's address for you.

That address is internal to the cluster and is not published externally, so an EKS-hosted agent is not reachable from the public internet.

Your container serves the same contract as any other Neo Code Agent — ``POST /run``, described in :doc:`service_contract` — and listens on port ``8080``.

Deploying
----------

A deploy is triggered in one of three ways:

* **On creation** — choosing EKS and saving runs the deploy immediately. The save button reads **Create & Deploy**.
* **On update** — saving an existing EKS agent redeploys it. The button reads **Save & Deploy**.
* **From the dashboard** — the **…** menu on the agent's card offers **Deploy**.

The deploy then runs in the background. If it does not start, the agent is still saved and you can deploy again from the dashboard.

Deployment Status
------------------

A **Deployment** strip appears above the agent's details on the Settings page, showing the current status badge, when it was last deployed, and any error message. A **refresh** icon re-reads the status — it does not update on its own.

.. list-table::
   :widths: 26 74
   :header-rows: 1

   * - Badge
     - Meaning
   * - **Not Deployed**
     - No deploy has run, or the agent has been undeployed. The agent cannot serve traffic.
   * - **Deploying**
     - The deploy is in progress. Refresh to follow it.
   * - **Deployed**
     - Running and reachable inside the cluster.
   * - **Update In Progress**
     - A redeploy of an already-running agent is under way.
   * - **Undeploying**
     - The running workload is being removed.
   * - **Failed**
     - The deploy did not complete. The error message on the strip is the place to start.

The agent's card on **Home** shows the same status.

Undeploying
------------

**Undeploy** stops the agent serving traffic but keeps the agent and its configuration in the platform, so you can redeploy later from the same settings.

The button appears on the Deployment strip when the status is **Deployed**, and from the card's **…** menu.

Deleting an EKS Agent
----------------------

An agent can be deleted when its deployment status is **Not Deployed** or **Failed**. Undeploy first, wait for the status to settle, then delete.

Deletion is also refused while someone holds edit mode on the agent — ask them to release it.

Troubleshooting
----------------

.. list-table::
   :widths: 38 62
   :header-rows: 1

   * - Symptom
     - What to check
   * - Status sticks on **Deploying**
     - Click refresh — the badge does not poll. If it does not move, the image may be unpullable or the pod unschedulable; ask your platform administrator to inspect the cluster.
   * - Status is **Failed**
     - Read the error message on the Deployment strip. Most often a wrong **Image URI** or **Image Tag**, an IAM role that cannot pull from ECR, or resource requests the cluster cannot satisfy.
   * - **Deployed**, but calls fail
     - Confirm your container serves ``POST /run`` and listens on port 8080. See :doc:`service_contract`.
   * - Saved settings did not take effect
     - Reopen the agent and check **Resource Limits**, **Environment Variables**, **Node Selector**, and **Autoscaling Configuration** still hold well-formed JSON, then deploy again.
   * - No **Deploy** or **Undeploy** option
     - You lack the **Deploy / Undeploy Remote Agent** permission, or the status does not permit that action.