Upgrading a deployment in place
When a new version of a tenant and module takes over, the old version drains: its running instances finish on it. Since 0.6.20, a channel only the old version declares stays served by it, starts included, until it retires at zero running instances. Another owner cannot take such an endpoint meanwhile.
The packages
orders1.0.0:start(POST /orders) parks an order on a receive task waiting onrelease(POST /orders/release, correlated byid). A second process starts onlegacy(POST /orders/legacy) and replieslegacy handled by orders 1.0.0.orders2.0.0: keepsstart, waits onconfirm(POST /orders/confirm) instead, and has noreleaseand nolegacy.audit1.0.0, another module (another owner), bindsPOST /orders/release.
Steps
- Package and deploy
orders1.0.0; start two orders,A-1andA-2. Both park onrelease. - Deploy
orders2.0.0.SUTRA.DEPLOY.ENDPOINT.SUPERSEDEDsays 1.0.0 drains, its instances finish on it, and names the endpoints it keeps:POST /orders/release, POST /orders/legacy. GET /sutra/deployments: 1.0.0 is underdraining, with 2 running instances underdrainingInstances.POST /orders/legacystill runs, on 1.0.0.- Deploy
audit: refused with409,SUTRA.DEPLOY.ENDPOINT.COLLISION, naming 1.0.0 and its 2 running instances. Nothing is stored. - Release
A-1andA-2onPOST /orders/release: both finish on 1.0.0. - On the next sweep 1.0.0 retires:
drainingis empty, andPOST /orders/legacyis404. - Deploy
auditagain: it lands. sutra linton a package that sendsq:send destination="local://acme/orders/2.0.0/start":SUTRA.CONFIG.SEND.LOCAL_DESTINATION_CROSSES_PACKAGE, exit 1. Send on an outbound channel the other package listens on instead.
$ sutra package orders-1 --out out1
packaged out1/orders-1.sutra (deploymentId dep-9f805df1cff68d20777326e9)
[exit 0]
$ sutra deploy out1/orders-1.sutra --api --engine-url http://localhost:8080
deployed dep-9f805df1cff68d20777326e9 (slot acme--orders--1.0.0, rev 1) — Active
[exit 0]
$ curl -X POST /orders -H 'X-API-Key: walk-key' -d '{"id":"A-1"}'
[HTTP 200]
$ curl -X POST /orders -H 'X-API-Key: walk-key' -d '{"id":"A-2"}'
[HTTP 200]
$ sutra package orders-2 --out out2
packaged out2/orders-2.sutra (deploymentId dep-200e1644e8045c4c02c0e3d0)
[exit 0]
$ sutra deploy out2/orders-2.sutra --api --engine-url http://localhost:8080
[WARN] SUTRA.DEPLOY.ENDPOINT.SUPERSEDED — deployment acme--orders--2.0.0 takes over from acme--orders--1.0.0, an earlier deployment of the same tenant and module. acme--orders--1.0.0 drains: it takes no new work, and its running instances finish on it. Channels only it declares stay served by it until it retires: POST /orders/release, POST /orders/legacy.
deployed dep-200e1644e8045c4c02c0e3d0 (slot acme--orders--2.0.0, rev 1) — Active
[exit 0]
$ curl /sutra/deployments
{"active":[{"deploymentId":"dep-200e1644e8045c4c02c0e3d0","slot":"acme--orders--2.0.0","phase":"Active","ready":true}],"pending":[],"draining":["dep-9f805df1cff68d20777326e9"],"drainingInstances":{"dep-9f805df1cff68d20777326e9":2},"failed":[]}
$ curl -X POST /orders/legacy -H 'X-API-Key: walk-key' -d '{}'
legacy handled by orders 1.0.0
[HTTP 200]
$ sutra package audit --out outa
packaged outa/audit.sutra (deploymentId dep-dbd1c12988671263d273fbe1)
[exit 0]
$ sutra deploy outa/audit.sutra --api --engine-url http://localhost:8080
[ERROR] SUTRA.DEPLOY.ENDPOINT.COLLISION — engine rejected the deployment (HTTP 409 Conflict): {"code":"SUTRA.DEPLOY.ENDPOINT.COLLISION","error":"[SUTRA.DEPLOY.ENDPOINT.COLLISION] http endpoint 'POST /orders/release' stays with draining deployment acme--orders--1.0.0 (2 running instances) until it retires"}
[exit 1]
$ curl -X POST /orders/release -H 'X-API-Key: walk-key' -d '{"id":"A-1"}'
[HTTP 200]
$ curl -X POST /orders/release -H 'X-API-Key: walk-key' -d '{"id":"A-2"}'
[HTTP 200]
$ # wait for the sweep
$ curl /sutra/deployments
{"active":[{"deploymentId":"dep-200e1644e8045c4c02c0e3d0","slot":"acme--orders--2.0.0","phase":"Active","ready":true}],"pending":[],"draining":[],"drainingInstances":{},"failed":[]}
$ curl -X POST /orders/legacy -H 'X-API-Key: walk-key' -d '{}'
{"type":"urn:bpm:diag:SUTRA.RESOLVE.CHANNEL.UNKNOWN","title":"SUTRA.RESOLVE.CHANNEL.UNKNOWN","status":404,"detail":"No channel bound at 'POST /orders/legacy'","code":"SUTRA.RESOLVE.CHANNEL.UNKNOWN"} [HTTP 404]
$ sutra deploy outa/audit.sutra --api --engine-url http://localhost:8080
deployed dep-dbd1c12988671263d273fbe1 (slot acme--audit--1.0.0, rev 1) — Active
[exit 0]
$ sutra lint crossing
[ERROR] SUTRA.CONFIG.SEND.LOCAL_DESTINATION_CROSSES_PACKAGE — deployment acme/sender/1.0.0 (dep-ffffffffffffffffffffffff): process 'send' node 'Send' sends to 'local://acme/orders/2.0.0/start', which is not a 'transport: local' inbound channel of this package (local://acme/sender/1.0.0/<channel>). A local address does not cross packages, versions of one package included: send on an outbound channel the other package listens on
1 error(s), 1 warning(s)
[exit 1]
If you undeploy the new version
Undeploying 2.0.0 gives 1.0.0 back every channel it declares, the ones it shared with 2.0.0
included, until 1.0.0 retires. Here a new order C-1 on the shared POST /orders starts on 1.0.0
(the admin instance list for 1.0.0 counts 2), both orders finish on it, and once it retires
POST /orders is 404, because nothing serves it any more.
$ sutra package orders-1 --out out1
packaged out1/orders-1.sutra (deploymentId dep-9f805df1cff68d20777326e9)
[exit 0]
$ sutra deploy out1/orders-1.sutra --api --engine-url http://localhost:8080
deployed dep-9f805df1cff68d20777326e9 (slot acme--orders--1.0.0, rev 1) — Active
[exit 0]
$ curl -X POST /orders -H 'X-API-Key: walk-key' -d '{"id":"A-1"}'
[HTTP 200]
$ sutra package orders-2 --out out2
packaged out2/orders-2.sutra (deploymentId dep-200e1644e8045c4c02c0e3d0)
[exit 0]
$ sutra deploy out2/orders-2.sutra --api --engine-url http://localhost:8080
[WARN] SUTRA.DEPLOY.ENDPOINT.SUPERSEDED — deployment acme--orders--2.0.0 takes over from acme--orders--1.0.0, an earlier deployment of the same tenant and module. acme--orders--1.0.0 drains: it takes no new work, and its running instances finish on it. Channels only it declares stay served by it until it retires: POST /orders/release, POST /orders/legacy.
deployed dep-200e1644e8045c4c02c0e3d0 (slot acme--orders--2.0.0, rev 1) — Active
[exit 0]
$ sutra undeploy acme--orders--2.0.0 --api --engine-url http://localhost:8080
undeployed slot acme--orders--2.0.0 — Draining
[exit 0]
$ curl /sutra/deployments
{"active":[],"pending":[],"draining":["dep-9f805df1cff68d20777326e9"],"drainingInstances":{"dep-9f805df1cff68d20777326e9":1},"failed":[]}
$ curl -X POST /orders -H 'X-API-Key: walk-key' -d '{"id":"C-1"}'
[HTTP 200]
$ # instances on 1.0.0 (dep-9f805df1cff68d20777326e9)
2
$ curl -X POST /orders/release -H 'X-API-Key: walk-key' -d '{"id":"A-1"}'
[HTTP 200]
$ curl -X POST /orders/release -H 'X-API-Key: walk-key' -d '{"id":"C-1"}'
[HTTP 200]
$ # wait for the sweep
$ curl /sutra/deployments
{"active":[],"pending":[],"draining":[],"drainingInstances":{},"failed":[]}
$ curl -X POST /orders -H 'X-API-Key: walk-key' -d '{"id":"D-1"}'
{"type":"urn:bpm:diag:SUTRA.RESOLVE.CHANNEL.UNKNOWN","title":"SUTRA.RESOLVE.CHANNEL.UNKNOWN","status":404,"detail":"No channel bound at 'POST /orders'","code":"SUTRA.RESOLVE.CHANNEL.UNKNOWN"} [HTTP 404]
What to watch for
- A version that keeps starting work on the channels it kept never retires. Watch
drainingInstances. - In a deployments folder, removing 1.0.0’s file stops its channels.
- Versions already draining when you upgrade the engine to 0.6.20 stop serving as before.
SUTRA.DEPLOY.ENDPOINT.CHANNEL_CHANGEDandSTART_ON_WAITwarn at deploy when 2.0.0 changes a channel 1.0.0 has instances parked on (not shown in this run; the tier-2 suite covers them).
See also One endpoint, one deployment, which covers how the other deployment paths behave.