Guide to Deployments 2.0
You've probably read the SQD Cloud Deployments 2.0 Release Notes, and now you’re ready to dive deeper into how it works. So let's get started!
The new deployments system is built on two new concepts:
-
Slots: Given a squid name and an organization, slot name uniquely identifies a squid deployment.
- Slots directly replace versions from the old workflow. Unlike versions, they are identified by short strings, not numbers.
- You can specify a slot on deployment or omit it. In the latter case the Cloud will create a new slot with a random identifier.
- Deploying to an already occupied slot will result in updating the initial deployment.
-
Tags: A way to label deployments.
Tags rules:
- Each tag can be assigned to only one deployment among those that have the same name + organization. Assigning an existing tag moves it.
- Multiple tags can be assigned to any one deployment.
Tags uses:
- Each tag added to the slot adds a new custom endpoint.
- You can address deployments by their tags to perform various operations, including redeployment.
Both tags and slots can be specified in squid manifest as well as via command line, giving rise to a variety of possible workflows. Let's take a look at a few common scenarios.
Zero-downtime updates
The functionality in this section mirrors the now-deprecated production aliases.
As you develop your squid you will sometimes need to re-sync it from scratch. With tags you can do this without a maintenance downtime. Here's how:
-
Take your squid (or the the EVM template if you just want something to test this with) and open its manifest (
squid.yaml
by default). Remove any deployment references:version:
(old)slot:
(new)tag:
(new)
This is needed because we'll let the Cloud auto generate a slot identifier for us. The top of your manifest file should look something like this:
manifestVersion: subsquid.io/v0.1
name: my-squid
description: 'The very first... -
Deploy the squid with
sqd deploy .
while in the project folder. Once complete, you’ll see a message like this:=================================================
A new squid my-org/my-squid@fj0anc has been successfully created
=================================================fj0anc
is the slot name that Cloud automatically assigned to your squid deployment. Here's how this deployment looks like in the app:At this stage you can already access your deployment's API via a slot-based URL. However, that API will go down if we reset the deployment's database. Instead, let us use a tag-based URL that can be redirected to an API of another deployment.
-
Assign a tag to your deployment:
sqd tags add production -n my-squid -s fj0anc
This assigns the
production
tag to the deployment, making the API accessible via:https://my-org.squids.live/my-squid:production/api/graphql
Use this URL to access the API in your frontend app.
Now, let's say you've made some changes to your codebase and need to re-sync your squid from scratch. Follow these steps:
-
Make one more deployment of your squid. For that you can just re-run
sqd deploy .
: since no slot, version or tag is supplied in the manifest, the Cloud will automatically create a new slot for you. Your Cloud deployments might now look like this: -
Wait for your new deployment to sync, then test its API using its slot-based (canonical) URL:
https://my-org.squids.live/my-squid@u293zi/api/graphql
-
When you're ready to switch, simply reassign the
production
tag to the new deployment:sqd tags add production -n my-squid -s u293zi
The tag-based URL will now point to the new deployment,
u293zi
, with the switch typically taking just a few seconds. -
Finally, if you no longer need the old deployment, remove it by slot:
sqd rm -n my-squid -s fj0anc
Multiple major versions
One common scenario occurs when you release a breaking change and need to maintain several major versions of your API. With tags, you can keep all these major versions under the same squid name.
Let’s say you’ve introduced a breaking change to the squid from the previous example. Deploy your new version as follows:
sqd deploy .
# then, assuming that the new deployment got slot f69x40
sqd tags add production-v1 -n my-squid -s f69x40
Alternatively, you can use the --add-tag
option of sqd deploy
to do the same thing without having to handle the autogenerated slot name:
sqd deploy . --add-tag production-v1
This will produce exactly the same result. Here's how it may look like in the Cloud app:
Now you have two independent APIs accessible by tag-based URLs and you can perform zero-downtime updates on each.
Development workflows
In the previous section we considered the situation when multiple tags are used to denote major versions of the API. However, the exact same approach can be used to separate, for example, development from production:
When working on your development deployment, you’ll likely need to perform a variety of operations on it, frequently and without the concern of downtime. For that, all Squid CLI commands allow addressing deployments by tag. For example, to access logs of your development
deployment use
sqd logs -n my-squid -t development
This command allows you to pull logs directly from the deployment tagged development
, without needing to remember or specify the slot name.
Moreover, you can update your development
-tagged deployment without having to know its slot name:
sqd deploy . -t development
It's even possible to ensure that whenever you deploy from the current directory, the deployment goes to the slot tagged development
. Simply add the following line to squid.yaml
:
tag: development
This may serve as a safeguard, preventing accidental deployments to production or the creation of unintended deployments.
Next steps
Now that you've seen how slots and tags can help you with some common tasks, you may want to use them to design new workflows uniquely suitable for the needs of your project. Here are some resources that may help you with that:
-
The output of
sqd <command> --help
commands, especially ofsqd deploy --help
All the flags you can use to refer to deployments and to disable protective user prompts are described there.
-
The detailed changelog that (for now) doubles as the reference documentation page. It describes the new system by comparing it to the old one that was based on versions and production aliases.
-
If you used the old system or witnessed the migration of your organization, you may want to take a look at the Backwards compatibility section of the changelog.