Skip to content

AI Playbook: 06 - Environment Promotion

This playbook describes the process for promoting a validated set of Toolkit YAML configurations from a source environment (e.g., dev) to a target environment (e.g., prod). It relies on the standard Cognite Toolkit CLI to ensure a safe and auditable deployment process.

Trigger: Manual execution by a designated release manager or lead engineer.\ Input: A validated and approved set of YAML configurations in the cognite_toolkit_configs/ directory.\ Prerequisite: The configuration must have been generated by the 05_TOOLKIT_YAML_SYNC.md playbook and approved via a pull request.

1. Playbook Goal

To provide a standardized, safe, and repeatable process for deploying changes across different CDF environments, minimizing the risk of errors and ensuring that production changes are deliberate and well-documented.

2. Promotion Workflow: Dev to Prod

This workflow assumes a standard dev -> prod promotion path.

Step 2.1: Generate a Deployment Plan (Diff)

  • Action: Before applying any changes, generate a "dry run" report that shows exactly what the Toolkit will create, update, or delete in the target environment.

  • Details: The release manager executes the cognite-toolkit diff command, comparing the local YAML configuration against the state of the production environment.

  • Command:

cognite-toolkit diff \
  --project <my-cdf-project> \
  --env prod \
  --module-path cognite_toolkit_configs/ \
  > prod_deployment_plan.txt
  • Human-in-the-Loop: The release manager must carefully review the prod_deployment_plan.txt. This is the final manual gate to ensure that the changes to be applied are exactly what is expected. If any discrepancies are found, the promotion process is halted immediately.

Step 2.2: Execute the Deployment (Apply)

  • Action: Once the deployment plan is approved, the release manager executes the cognite-toolkit apply command to deploy the changes to the production environment.

  • Details: This command synchronizes the state of the production environment with the local YAML configuration.

  • Command:

cognite-toolkit apply \
  --project <my-cdf-project> \
  --env prod \
  --module-path cognite_toolkit_configs/ \
  --yes # Automatically confirm, as the plan was already reviewed

Step 2.3: Post-Deployment Smoke Test

  • Action: Immediately after deployment, run a series of automated "smoke tests" against the production environment to verify that the core components of the solution are healthy.

  • Details: These are typically lightweight, read-only checks.

  • Example Script (tools/run_smoke_tests.py):

# Example smoke tests
# - Verify that the deployed data models exist.
# - Check that a sample of assets can be retrieved.
# - Confirm that key transformations have run successfully in the last hour.
  • Outcome: If any smoke test fails, it triggers an immediate alert to the operations team to investigate.

3. Rollback Procedure

In the event of a critical issue discovered post-deployment, a rollback is necessary.

  • Action: Re-apply the previous version of the YAML configuration.

  • Details: The "docs-as-code" approach using Git makes this straightforward. The release manager can simply check out the commit hash of the last known good configuration and re-run the apply command from Step 2.2 using that version of the code.

  • Command Example:

# Check out the previous stable commit
git checkout <commit_hash_of_last_good_config>

# Re-apply the old configuration to revert the changes
cognite-toolkit apply \
  --project <my-cdf-project> \
  --env prod \
  --module-path cognite_toolkit_configs/ \
  --yes

Note: This playbook intentionally leverages the existing, robust functionality of the Cognite Toolkit CLI. The value of the playbook is in codifying the process and ensuring that deployments are always preceded by a diff review and followed by smoke tests.