Versioning

Restate comes with different solutions to update the services, to simplify development and evolution of your codebase without sacrificing Restate's strong guarantees.

Inspecting deployments

To check which deployments are currently serving your services, do the following:

CLI

restate services list

Output

NAME REVISION FLAVOR DEPLOYMENT TYPE DEPLOYMENT ID

🌎 TicketObject 1 HTTP 2 dp_14LsPzGz9HBxXIeBoH5wYUh

🌎 CartObject 1 HTTP 2 dp_14LsPzGz9HBxXIeBoH5wYUh

🌎 CheckoutService 1 HTTP 2 dp_14LsPzGz9HBxXIeBoH5wYUh

To list only the deployments, you can do restate deployments list.

Note that deployment IDs start with dp_. You can use it to describe the deployment:

restate deployment describe dp_14LsPzGz9HBxXIeBoH5wYUh

curl

curl localhost:9070/services/Greeter

Output

{

"name": "Greeter",

"revision": 2,

"endpoint_id": "Z3JlZXRlci12Mi8",

[...]

}

Note that deployment IDs start with dp_. You can use it to describe the deployment:

curl localhost:9070/deployments/Z3JlZXRlci12Mi8

Output

{

"id": "Z3JlZXRlci12Mi8",

"uri": "http://greeter-v2/",

"additional_headers": {},

"protocol_type": "BidiStream",

"services": [

{

"name": "Greeter",

"revision": 2

}

]

}

Deploying new service versions

As described in the deployment docs, deployments are immutable, and are assumed to be reachable throughout the entire lifecycle of an invocation. To deploy an updated version of a service, you need to deploy and register a new deployment.

For example, let's assume there is a Greeter service deployed at http://greeter-v1/. To update it, we deploy a new revision at http://greeter-v2/, and then register it:

CLI

restate deployments register http://greeter-v2/

curl

curl localhost:9070/deployments -H 'content-type: application/json'

-d '{"uri": "http://greeter-v2/"}'

Output

{

"id": "Z3JlZXRlci12Mi8",

"services": [

{

"name": "Greeter",

"revision": 2

}

]

}

When the services at the new endpoint were already registered before, Restate will treat them as new revisions. New invocations are always routed to the latest service revision, while old invocations will continue to use the previous deployment. So new invocations will be routed to http://greeter-v2/, while existing invocations continue execution at http://greeter-v1/ (e.g. sleeping/waiting invocations) until completion.

caution

It must be guaranteed that the old deployment lives until all the existing invocations complete.

State compatibility

When updating Virtual Objects, the new revisions will continue to use the same state created by previous revisions. You must ensure state entries are evolved in a backward compatible way.

Removing services

You cannot remove a single service, but you can remove the deployment containing it.

Before you remove a deployment, you need to ensure the following:

1. Make sure that there are no other handlers with business logic that calls this service.
2. If several services are bundled in the same deployment, you can't remove only one of them. You have to remove the whole deployment. So make sure that you first deploy the services you want to keep in a separate new deployment.
3. Make the service private to avoid accepting new HTTP requests.
4. Check whether the service has pending invocations via restate services status, and wait until the service is drained (i.e. no ongoing invocations).

When all prerequisites are fulfilled, you can remove the deployment containing the service via:

CLI

restate deployments remove dp_14LsPzGz9HBxXIeBoH5wYUh

If the deployment isn't drained yet but you still want to remove it, use the --force flag.

curl

curl -X DELETE localhost:9070/deployments/dp_14LsPzGz9HBxXIeBoH5wYUh?force=true