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

Create a Keycloak realm #

Provisions a Keycloak realm for an existing environment.

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

HTTP route:

POST /organizations/:organizationId/projects/:projectId/environments/:environmentId/_keycloak

Rotate the Scaleway SMTP API key #

Rotates the transactional-email credential of an environment. Every environment owns its own Scaleway SMTP API key, created with its Keycloak realm; this action mints a new one and pushes it everywhere it is used — the environment's Keycloak realm, its Kubernetes secret and the deployed applications, whose rendered values are rewritten so they read the credential by reference — then revokes the previous key.

Rewriting the applications changes their pod template, so they restart and pick the new key up on their own. That rewrite is not cosmetic: nothing else re-renders an application that is already deployed, so without it the pods would never receive the SMTP variables, however many times they are redeployed. Their sending fails for the few seconds the restart takes.

Use it when a key has been corrupted or revoked outside the console. The secret key is returned once and never again.

const apiKey = await kuzzle.query({
  controller: 'org-environment',
  action: 'createScalewaySmtpApiKey',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});
// { access_key, secret_key, secretName, keycloakUpdated, rewrittenApplications }

HTTP route:

POST /organizations/:organizationId/projects/:projectId/environments/:environmentId/scaleway/smtp-api-key

Rotate the Keycloak client secret #

Regenerates the OIDC client secret of an environment's Keycloak realm, publishes it in the environment's Kubernetes secret, and rewrites the deployed applications so they read it by reference instead of carrying its value. That rewrite changes the pod template, so the applications restart and pick up the new secret on their own.

Use it when the secret's value may have been read by a third party: regenerating is what makes the copies already taken useless. The previous secret stops authenticating immediately, so the applications are unauthenticated for the few seconds separating the regeneration from their restart.

Nothing secret is returned: the value never transits through the caller.

const rotation = await kuzzle.query({
  controller: 'org-environment',
  action: 'rotateKeycloakClientSecret',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  environmentId: 'production'
});
// { realmName, secretName, rewrittenApplications }

HTTP route:

POST /organizations/:organizationId/projects/:projectId/environments/:environmentId/keycloak/client-secret

GitHub deployment environment #

Owner/admin actions to wire an environment to GitHub Actions deployments (the project must be connected to a GitHub repository first — see Projects):

• configureGithubEnvironment — creates the native GitHub Environment on the project repository (POST .../environments/:environmentId/github).
• generateGithubDeploymentCredentials — creates a per-environment Harbor robot account and propagates it as GitHub secrets (POST .../environments/:environmentId/github/credentials).

Environment sizes #

Supported sizes:

• S
• S_SLA
• M
• L

Environment statuses #

Known statuses:

• Deploying
• Deployed
• Upgrading
• Disabled
• Errored