Deployments #

A deployment applies the version of a release to one environment. It runs in three phases:

Build. The console dispatches the build.yml workflow of the project's GitHub repository, with the release version and the target environment. The workflow builds one image per deployable application, with the configuration of that environment, and pushes it to the project registry (Harbor), tagged with the release version.
Apply. Once the build run has succeeded, the console applies the images through ArgoCD: the Kuzzle backend first, then every other deployable application (web applications, and custom applications marked as deployable).
Rollout. The console follows the ArgoCD health of the environment. The deployment only succeeds once the environment is Healthy.

Controller: org-deployment

Base HTTP route:

/_/organizations/:organizationId/projects/:projectId/deployments

Deployments are scoped to a project. Any project member can deploy and roll back; an external collaborator can only read deployments. See the Continuous deployment guide for the repository side.

Deploy a release #

Dispatches the build of releaseId for environmentId and returns the deployment document right away. Follow it with refresh.

const deployment = await kuzzle.query({
  controller: 'org-deployment',
  action: 'create',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production',
  releaseId: '<release-id>'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/deployments?environmentId=production&releaseId=<release-id>

Requirements:

the release has a version (its release run has completed — see Refresh a release);
the environment has a release branch mapped: the build runs on that branch, from the release tag;
the environment has a Kuzzle backend application. Before dispatching the build, the console writes the address of that backend on the environment's GitHub Environment (VUE_APP_BACKEND_HOST, VUE_APP_BACKEND_PROTO, VUE_APP_BACKEND_PORT, VUE_APP_BACKEND_SSL), so the web application is built against it;
the repository has a build.yml workflow that can be dispatched with the inputs release_tag, environment and console_dispatch_id.

Refresh a deployment #

Moves the deployment forward and returns it. Idempotent and safe to poll:

while the build runs, it reads the workflow run;
when the build has succeeded, it applies the images and moves to deploying;
while deploying, it reads the ArgoCD health: Healthy settles to succeeded; Degraded, or no Healthy state within 15 minutes, settles to failed.

const deployment = await kuzzle.query({
  controller: 'org-deployment',
  action: 'refresh',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  deploymentId: '<deployment-id>'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/deployments/:deploymentId/_refresh

The platform also refreshes in-flight releases and deployments that nobody is polling, every 5 minutes, so a deployment reaches its end even when no client follows it.

Statuses #

Status	Meaning
`pending`	The build was dispatched; its run is not visible yet.
`building`	The build run is in progress.
`deploying`	The images were applied; ArgoCD is rolling them out.
`succeeded`	The environment is `Healthy` with the new images.
`failed`	See `failure.phase`: `build` (the build run failed — see `buildRun.htmlUrl`), `apply` (the build succeeded but applying the images failed — see `failure.message`), or `deploy` (the images were applied but the environment did not become healthy — see `failure.message` and `failure.resources`, the unhealthy Kubernetes resources reported by ArgoCD).
`rolled-back`	The previous images were re-applied with `rollback`.

succeeded, failed and rolled-back are final: deploying again creates a new deployment.

Roll back a deployment #

Re-applies, application by application (backend first), the images that were running before this deployment, and marks it rolled-back. Fails when the deployment recorded no previous images (it never reached the apply phase).

A rollback re-applies older images, not older data. When the deployment brought a backend version that migrated its stored data, the previous image may no longer read it. This is the case of IoT Platform v4 when it starts encrypting its secrets with the application encryption key: after its first start, rolling back to a version without that encryption leaves network providers unloaded and tenant mail accounts unavailable. Fix forward by deploying a newer version instead.

const deployment = await kuzzle.query({
  controller: 'org-deployment',
  action: 'rollback',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  deploymentId: '<deployment-id>'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/deployments/:deploymentId/_rollback

List deployments #

Lists the deployments of a project, most recent first.

const deployments = await kuzzle.query({
  controller: 'org-deployment',
  action: 'list',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project'
});

HTTP route:

GET /_/organizations/:organizationId/projects/:projectId/deployments

Get a deployment #

const deployment = await kuzzle.query({
  controller: 'org-deployment',
  action: 'get',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  deploymentId: '<deployment-id>'
});

HTTP route:

GET /_/organizations/:organizationId/projects/:projectId/deployments/:deploymentId

See Data models for the shape of a deployment.