Core
PaaS v2.x
2

Environments #

An environment belongs to a project and contains applications.

Controller: org-environment

Base HTTP route:

/_/organizations/:organizationId/projects/:projectId/environments

Environment fields (name, size, ...) are passed as query parameters, not as a request body.

Create an environment #

const environment = await kuzzle.query({
  controller: 'org-environment',
  action: 'create',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  name: 'production',
  description: 'Production environment',
  size: 'M',
  initKeycloakRealm: 'true'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments?name=production&size=M

Optional parameters:

  • description: human-readable description.
  • size: environment size (see Environment sizes).
  • tier: deployment tier, one of uat, staging or prod.
  • initKeycloakRealm: set to the string 'true' to also provision a Keycloak realm for the environment.

List environments #

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

HTTP route:

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

Get an environment #

const environment = await kuzzle.query({
  controller: 'org-environment',
  action: 'get',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

GET /_/organizations/:organizationId/projects/:projectId/environments/:environmentId

Refresh an environment #

Reconciles an environment status with ArgoCD.

const environment = await kuzzle.query({
  controller: 'org-environment',
  action: 'refresh',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments/:environmentId/_refresh

Disable an environment #

Disables the environment and its applications.

await kuzzle.query({
  controller: 'org-environment',
  action: 'disable',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments/:environmentId/_disable

Enable an environment #

await kuzzle.query({
  controller: 'org-environment',
  action: 'enable',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments/:environmentId/_enable

Delete an environment #

Deletes the environment and tears down its external resources (Keycloak realm, then monitoring).

await kuzzle.query({
  controller: 'org-environment',
  action: 'delete',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

DELETE /_/organizations/:organizationId/projects/:projectId/environments/:environmentId

Identity and secrets #

The Keycloak realm, its first administrator, the SMTP key and the credentials sealed in the environment's Kubernetes secrets have their own page: Environment identity and secrets.

GitHub deployment environment #

Owner/admin actions that wire an environment to the GitHub Actions workflows of the project repository. The project must be connected to a GitHub repository first — see Projects. See the Continuous deployment guide for how the workflows use them.

Configure the GitHub Environment #

Creates the GitHub Environment named after the console environment on the project repository, and sets its KUZZLE_PAAS_ENVIRONMENT variable. Idempotent.

const environment = await kuzzle.query({
  controller: 'org-environment',
  action: 'configureGithubEnvironment',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments/:environmentId/github

Generate deployment credentials #

Generates the two credential families the repository workflows use, and stores them as GitHub secrets:

  • a Harbor robot account for this environment, stored as the environment secrets PAAS_REGISTRY_USERNAME / PAAS_REGISTRY_PASSWORD (used by the build workflow to push images);
  • a scoped API key of the organization's ci machine identity, stored as the repository secrets PAAS_ROBOT_USERNAME / PAAS_ROBOT_APIKEY (used to install private npm packages).

Calling it again rotates both: the new credential is stored first, then the previous ones are revoked. The GitHub Environment must be configured first.

const credentials = await kuzzle.query({
  controller: 'org-environment',
  action: 'generateGithubDeploymentCredentials',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments/:environmentId/github/credentials

Release branch and tier #

An environment is released from one branch of the project repository, its release branch; one branch can serve several environments. Its tier (uat, staging or prod) drives the protection of that branch. Both are required before a release can be cut from the environment. These actions require an owner or admin role.

List the release branches #

Lists the release branches declared in the repository's semantic-release configuration (.releaserc), with their channel. Returns an empty list when the configuration cannot be read (for example a JavaScript config file); any branch can then be mapped.

const branches = await kuzzle.query({
  controller: 'org-environment',
  action: 'listReleaseBranches',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project'
});
// [{ name: 'main', channel: null }, { name: 'beta', channel: 'beta' }]

HTTP route:

GET /_/organizations/:organizationId/projects/:projectId/environments/release-branches

Map the release branch #

Validates the branch against the declared release branches (when they can be read), creates it if it does not exist, protects it against force-pushes and deletion, and records it on the environment (release.branch). The tier-driven protection below is then applied.

const environment = await kuzzle.query({
  controller: 'org-environment',
  action: 'provisionReleaseBranch',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production',
  branch: 'main'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments/:environmentId/release-branch

Set the tier #

Sets the deployment tier of the environment (uat, staging or prod), then re-applies the protection of its release branch: when the branch serves at least one prod environment, a merge into it requires a pull request; otherwise that rule is removed. The outcome of the protection is recorded on the environment (release.protection) rather than failing the call.

const environment = await kuzzle.query({
  controller: 'org-environment',
  action: 'setTier',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production',
  tier: 'prod'
});

HTTP route:

POST /_/organizations/:organizationId/projects/:projectId/environments/:environmentId/tier

Environment sizes #

Supported sizes:

  • S
  • S_SLA
  • M
  • L

Environment statuses #

Known statuses:

  • Deploying
  • Deployed
  • Upgrading
  • Disabled
  • Errored