# Edge agent versions and upgrades This page lists every released version of the **Axiad edge agent**, what changed in each one, and how to move your agent from one version to another. It's for whoever runs the agent on your host. If you haven't installed the agent yet, start with **[Run the edge agent](./run-the-edge-agent.md)**. The agent never updates itself. You choose when to upgrade, and you can stay on an older version until you're ready. ## Which version should I run? Run the **latest version** in the table below unless Axiad support asks you to use a different one. When your administrator registers a new agent, the command they send you already names the version to use. To see which version you're running now, either: - ask your administrator — Mesh shows it on the agent's **Overview** tab, or - check the container on your host: ```bash docker inspect axiad-edge-agent --format '{{.Config.Image}}' ``` The part after the last `:` is the version, for example `...mesh-edge-agent:1.0.3`. ## Release history Select a version, or its **Details** button, to see everything that changed in it and anything to know before you upgrade or go back. **What's new** - **Stronger protection for your connector credentials.** The agent now adds an extra layer of protection to the passwords and API keys it keeps for your connectors. It applies this to your existing connectors automatically the first time 1.0.3 starts — there's nothing for you to do. - **Cleaner decommissioning.** When your administrator decommissions the agent in Mesh, the agent now removes its certificate, connector settings and credentials from your host by itself, then stops for good. If the agent is offline at the time, it tidies up as soon as it reconnects. If you're on an earlier version, see **Remove it** under [Keeping it running](./run-the-edge-agent.md#keeping-it-running) to tidy up the host yourself. - **Additional safeguards** for the instructions the agent receives from Mesh. - **Smoother upgrades and restarts.** If you start a new agent container before the old one has fully stopped, the new one now waits up to a minute for the old one to finish. If the old one is still running after that, the new one stops and tells you (`in use by another agent process`). - **More reliable certificate renewal.** Improvements to how the agent renews its certificate automatically. - Updates to the third-party components the agent is built on. **Upgrading to 1.0.3:** follow [Upgrade to a new version](#upgrade-to-a-new-version). No extra steps. **Going back from 1.0.3:** 1.0.3 saves the agent's settings in a new format that versions 1.0.2 and earlier don't understand. To go back to one of those, follow [Roll back to 1.0.2 or earlier](#roll-back-to-1-0-2-or-earlier) rather than just starting the old container — it's one extra step. - **New `agent status` command.** Check the agent's state from inside the container, as shown in [Step 3 of Run the edge agent](./run-the-edge-agent.md#step-3--verify-it-enrolled-and-connected). - **Clearer start-up messages.** If the enrollment token didn't make it into the container, the agent now says so plainly (`config: ENROLL_TOKEN is set but empty`). It also stops with a clear message if a `MESH_GATEWAY` setting points somewhere other than the address in your token, so it can't join the wrong Mesh environment by mistake. - **Clearer connection messages.** If a secure connection fails because of a certificate mismatch, the message now names both the host the certificate was issued for and the host the agent expected, which makes the cause easy to spot. - Updates to the third-party components the agent is built on. - A small compatibility update for the agent's connection to Mesh. Nothing changes in how you run the agent or what it does. - First release of the Axiad edge agent. Every version runs on Linux, on both **x86-64 (amd64)** and **ARM64** hosts. Docker picks the right one for your machine automatically. > **note** The image registry also holds tags named `beta-` followed by a number. These are pre-release builds — whatever their number, they are not newer releases than the ones listed here. Use one only if Axiad support asks you to. ## Upgrade to a new version An upgrade swaps the container for one running the new version. The agent's identity and settings live in its storage (the `mesh-edge-data` volume), which the new container reuses — so you **don't need a new enrollment token**, and your connectors carry on where they left off. In the commands below, replace `1.0.3` with the version you're upgrading to, and `axiad-edge-agent` with your container's name if it's different. ### Write down your current settings first > **warning** Whatever flags your running container actually has — a custom `--user`, an extra `-e`, a host directory instead of the named volume — only exist in that container's own settings. Check what's really running, not just what the example in this guide shows: ```bash # Storage — confirm the exact volume (or host path) and where it's mounted. If this # doesn't match -v mesh-edge-data:/var/lib/mesh-edge, use what's shown here instead # when you start the new container. docker inspect axiad-edge-agent --format '{{range .Mounts}}{{.Type}} {{.Name}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}' # User — if the value in quotes is not empty, pass the same --user value to the new # container. Otherwise it can fail with `permission denied` on its own storage. docker inspect axiad-edge-agent --format 'User: "{{.Config.User}}"' # Environment variable names in use (values are left out on purpose, so a token # doesn't end up in your terminal history). docker inspect axiad-edge-agent --format '{{range .Config.Env}}{{.}}{{"\n"}}{{end}}' | cut -d= -f1 ``` ### Step 1 — Download the new version ```bash docker pull axiadpublicregistry.azurecr.io/mesh-edge-agent:1.0.3 ``` ### Step 2 — Stop the current agent and keep it as a backup Rename the old container instead of removing it. If anything goes wrong, getting back is a rename and a start rather than rebuilding the container from memory. ```bash docker stop axiad-edge-agent docker rename axiad-edge-agent axiad-edge-agent-previous ``` ### Step 3 — Start the new version Use the same settings you wrote down above. This is the standard command from [Run the edge agent](./run-the-edge-agent.md#step-2--run-the-agent), with the token left empty because the agent already has its identity: ```bash docker run -d --name axiad-edge-agent --restart unless-stopped --user 0:0 \ -e ENROLL_TOKEN="" \ -e MESH_SSRF_ALLOW_PRIVATE=1 \ -e STRICT_CONFIG_SIGNING=true \ -v mesh-edge-data:/var/lib/mesh-edge \ axiadpublicregistry.azurecr.io/mesh-edge-agent:1.0.3 ``` ### Step 4 — Check that it's healthy Check it the same way as [Step 3 of Run the edge agent](./run-the-edge-agent.md#step-3--verify-it-enrolled-and-connected): ```bash docker logs axiad-edge-agent 2>&1 | grep -E 'agent.connect ok|heartbeat|permission denied' ``` You want to see `agent.connect ok` and a heartbeat, and no `permission denied` lines. Your administrator should see the new version on the agent's **Overview** tab in Mesh. ### Step 5 — Remove the backup when you're sure Keep the backup until you're confident you won't need to go back — for example, until each of the agent's connectors has completed a collection run on the new version. Both ways of [rolling back](#roll-back-to-the-previous-version) start from it. A stopped container does nothing in the meantime. When you're ready, remove it: ```bash docker rm axiad-edge-agent-previous ``` ## Roll back to the previous version If the new container won't start or keeps restarting, go back to the version you had. How you do that depends on the versions involved. Both procedures below start the backup container from [Step 2](#step-2--stop-the-current-agent-and-keep-it-as-a-backup). If you've already removed it, use the [Step 3](#step-3--start-the-new-version) command instead, with the version you're going back to in place of `1.0.3` and the settings you wrote down. ### Roll back to 1.0.3 or later If the version you're going back to is **1.0.3 or later**, remove the new container and start the backup: ```bash docker rm -f axiad-edge-agent docker rename axiad-edge-agent-previous axiad-edge-agent docker start axiad-edge-agent ``` ### Roll back to 1.0.2 or earlier Version 1.0.3 and later save the agent's settings in a format that 1.0.2 and earlier don't understand. So before you start the older version, run a quick one-time **prepare** step with the **newer** version. It converts the saved settings back to the older format. > **warning** Run the prepare step only when you're going back to 1.0.2 or earlier, and only as the one-off command below — never add `EDGE_AGENT_PREPARE_DOWNGRADE` to a container you keep running. 1. **Stop the newer agent.** The prepare step refuses to run while an agent is using the storage. ```bash docker stop axiad-edge-agent ``` 2. **Run the prepare step with the newer version**, using the same storage and `--user` as your agent: ```bash docker run --rm --user 0:0 \ -e EDGE_AGENT_PREPARE_DOWNGRADE=1 \ -v mesh-edge-data:/var/lib/mesh-edge \ axiadpublicregistry.azurecr.io/mesh-edge-agent:1.0.3 echo "exit code: $?" ``` It doesn't connect to Mesh and doesn't need a token. Check how it finished: | Exit code | What it means | What to do | | --- | --- | --- | | `4` | Done. The log ends with `stop this agent and install the older binary`. | Go to step 3. | | `2` | Some connectors have credentials the older version can't use yet. The message names them. | Start the newer agent again (`docker start axiad-edge-agent`). Ask your administrator to turn off those connectors on the agent's **Connectors** tab in Mesh. Once the agent's **Activity** tab shows **Config applied**, stop the agent and rerun this step. | | `5` | An agent is still running on this storage. Nothing was changed. | Stop it and rerun this step. | | `6` | Almost done — a final clean-up didn't finish. | Rerun this step until it exits with `4`. | | `1` | Something else went wrong. Nothing was changed. | Read the message, fix what it describes, and rerun. If you're stuck, contact Axiad support — we're happy to help. | 3. **Start the older version** from your backup (or, if you no longer have one, with the Step 3 command and the older version's tag): ```bash docker rm -f axiad-edge-agent docker rename axiad-edge-agent-previous axiad-edge-agent docker start axiad-edge-agent ``` 4. **Turn the connectors back on.** If your administrator turned off any connectors in step 2, they can turn them back on now. They'll work with the older version. ## Related - **[Run the edge agent](./run-the-edge-agent.md)** — install, run, and troubleshoot the agent. - **[Set up an on-prem connector](./set-up-on-prem-connector.md)** — register agents and manage connectors from the Mesh dashboard.