Skip to content
Hexel StudioDocs

Environment freeze

Freeze an environment so agents can't change anything in it, mark it degraded, in maintenance or in an emergency, and lift the freeze.

On this page

An environment state applies to every agent that runs in one of your organization's environments (env_..., see Workspaces). The most useful is frozen: while an environment is frozen, Titan refuses every action that would change something there, and reads still run.

States

stateWhat Titan does
(not listed)Active, the default. Nothing changes.
frozenTitan refuses every action whose capability is not read-only, before policy is evaluated, with the reason environment_frozen. An action that was already approved is not run either. Read-only capabilities still run.
degraded, maintenance, emergencyTitan refuses nothing itself. The state is passed to your policy as environment.state, so your own rules can match it (for example, require approval for writes during maintenance).

Each state needs a reason_code: CHANGE_FREEZE, OPERATOR_REQUEST, SECURITY_INCIDENT, MAINTENANCE_WINDOW or POLICY_VIOLATION.

A freeze holds until you lift it. If Titan can't reach the service that signs environment states, the last states stay in force, and a deployment that has published states but can't load them refuses changes (reason environment_state_unavailable) rather than letting them through.

Freeze an environment

Environment states belong to a Titan deployment. Use the deployment's id (td-..., from Titan → Deployments in the console). You need titan:policy:read to read the states and titan:policy:publish to change them.

  1. Read the current states and their version:

    Bash
    curl -i https://api.hexelstudio.com/v1/titan/management/deployments/$TITAN_DEPLOYMENT_ID/environment-states \
  -H "Authorization: Bearer $ACCESS_TOKEN"

    The response lists environments, the version in force (also sent as the ETag header), and enforced.

  2. Replace the list. Send every environment that should not be active; an environment you leave out becomes active again. Send the version from step 1 in If-Match, so that you don't overwrite a change someone else made since:

    Bash
    curl -X PUT https://api.hexelstudio.com/v1/titan/management/deployments/$TITAN_DEPLOYMENT_ID/environment-states \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "<version>"' \
  -d '{
    "environments": [
      { "environment_id": "env_0123456789abcdef", "state": "frozen", "reason_code": "CHANGE_FREEZE" }
    ]
  }'

    If the states changed since you read them, the request fails with 412 and nothing changes. Read them again and retry.

The deployment's page in the console also shows its environment states.

Lift a freeze

Send the list again without the environment, or with {"environments": []} to make every environment active.

Check that it is enforced

The read returns enforced. On Titan Cloud it is true. When enforced is false, the states are stored but Titan does not apply them, and the console shows them as not enforced.

Every action Titan refuses because of a freeze is recorded in the Agent Ledger with the reason environment_frozen. To find them, filter with reason_code=environment_frozen.