Cloud 7.06

Use Variables

Understanding variables, environment variables, project variables, env: prefix, and variable management.

Exam Critical: Understanding variables, environment variables, project vs environment level variables, and the env: prefix is ESSENTIAL for the exam!

Using Variables

mindmap root((Variables)) Variables magento env yaml build deploy global Control build process Little long term use Environment Variables Project Web CLI env prefix required Cascade to children Magento config Project Variables project variable set All environments Includes build Redeploy needed Environment Variables Per environment Sensitive data Inheritable option

Understanding Variables on Cloud

What Are Variables?

Purpose

Variables are another way to control the website and the build process.

  • Configure the website
  • Change how the build/deploy process behaves
  • Control deployment optimization
  • Set application configuration

Long-Term Use

Variables configured in .magento.env.yaml have little use long-term. They're primarily for controlling build/deploy behavior, not for permanent configuration changes.

Types of Variables

Three Variable Configuration Methods

Type Configuration Method Scope Purpose
Variables .magento.env.yaml All environments (in git) Build/deploy phase control
Environment Variables Project Web CLI (per environment) Specific environment + children Magento config, sensitive data
Project Variables magento-cloud project:variable:set All environments (including build) Global settings, build phase access

Variables in .magento.env.yaml

Phase-Based Variable Configuration

.magento.env.yaml

Available Phases

Build

Variables for build phase

Deploy

Variables for deploy phase

Post-Deploy

Variables for post-deploy phase

Global

Variables for all phases

Example Configuration

stage:
  global:
    SCD_ON_DEMAND: false
    SKIP_HTML_MINIFICATION: true
  
  build:
    SCD_STRATEGY: compact
    SCD_THREADS: 3
  
  deploy:
    CRON_CONSUMERS_RUNNER:
      cron_run: true
      max_messages: 1000
      consumers:
        - exportProcessor
        - inventoryQtyCounter
  
  post-deploy:
    TTFB_TESTED_PAGES:
      - "/"
      - "/customer/account/login"
Common Variables:
  • SCD_ON_DEMAND - Generate static content on demand
  • SCD_STRATEGY - Static content deployment strategy
  • SKIP_SCD - Skip static content deployment
  • SKIP_HTML_MINIFICATION - Skip HTML minification
  • CRON_CONSUMERS_RUNNER - Configure message queue consumers
  • VERBOSE_COMMANDS - Enable verbose command output

Environment Variables

Project Web CLI Configuration

What Are Environment Variables?

Environment variables are configured per environment in the Project Web CLI and cascade to child environments.

Example:
  • Set variable in integration environment
  • Variable cascades to all child integration branches
  • Each child can override if needed

The env: Prefix Requirement

Critical Rule

To use an environment variable to change Magento configuration settings, the variable name MUST start with env:

Examples:
env:CONFIG__DEFAULT__WEB__SECURE__USE_IN_FRONTEND
env:CONFIG__DEFAULT__CARRIERS__TABLERATE__ACTIVE
env:SCD_ON_DEMAND

Configuring in Project Web Interface

  1. Navigate to desired environment
  2. Click Settings → Variables
  3. Click Add Variable
  4. Enter variable name (with env: prefix if for Magento config)
  5. Enter value
  6. Select options:
    • ☑ Inheritable by child environments - Cascade to children
    • ☑ Sensitive - Hide value in UI
    • ☑ JSON value - Parse as JSON
  7. Save - triggers automatic redeployment

Difference: Variables vs Environment Variables

Side-by-Side Comparison

Aspect Variables (.magento.env.yaml) Environment Variables (Project Web CLI)
Configuration .magento.env.yaml file Project Web Interface → Settings → Variables
Scope All environments (committed to git) Per environment + optional cascade
Version Control Yes (in git) No (stored in Cloud platform)
Cascading N/A (same for all via git) Can cascade to child environments
Sensitive Data No (visible in git) Yes (can mark as sensitive)
Magento Config Limited (build/deploy control) Yes (with env: prefix)
Prefix Required No Yes (env: for Magento config)
Long-term Use Little (mainly build/deploy) Yes (configuration management)

Project Variables vs Environment Variables

Understanding the Difference

Project Variables

Characteristics:
  • Set using: magento-cloud project:variable:set
  • Apply to all environments (including build)
  • Available during build phase
  • Global across entire project
  • Cannot cascade (already global)
Setting Project Variable:
magento-cloud project:variable:set VARIABLE_NAME value
Example:
magento-cloud project:variable:set php:memory_limit 2G
Redeployment Required

Once you create a project variable, you need to re-deploy each environment.

Use Blank Commit:
git commit --allow-empty -m "Redeploying environments"
git push

This triggers redeployment without any code changes.

Environment Variables

Characteristics:
  • Configured per environment
  • Usually unique per environment
  • Can contain sensitive data
  • Can cascade through child environments
  • Must select "Inheritable by child environments" to enable cascade
Setting Environment Variable (CLI):
magento-cloud variable:set env:VARIABLE_NAME value -e integration
Example:
magento-cloud variable:set env:SCD_ON_DEMAND true -e integration --inheritable

Comparison Table

Feature Project Variables Environment Variables
Command project:variable:set variable:set -e [env]
Scope All environments Specific environment
Build Phase ✅ Available ❌ Not available
Deploy Phase ✅ Available ✅ Available
Sensitive Data Can mark as sensitive Can mark as sensitive
Inheritance N/A (global) Optional (child environments)
Redeployment Manual (blank commit) Automatic

When to Use Variables

Use Cases

Use .magento.env.yaml Variables When:

  • Controlling build/deploy behavior (SCD strategy, threads, etc.)
  • Configuration should be same across all environments
  • Need to version control the settings
  • Optimizing deployment performance
  • Enabling/disabling features during build

Use Environment Variables When:

  • Overriding Magento configuration per environment
  • Storing sensitive data (API keys, passwords)
  • Different values needed per environment (integration vs production)
  • Need to cascade settings to child branches
  • Don't want settings in version control

Use Project Variables When:

  • Setting needs to be global across all environments
  • Variable needed during build phase
  • PHP configuration (memory_limit, etc.)
  • Global application settings

Common Configuration Examples

Practical Examples

Example 1: Enable Table Rate Shipping (Environment Variable)

Project Web Interface → Settings → Variables
Name: env:CONFIG__DEFAULT__CARRIERS__TABLERATE__ACTIVE
Value: 1

Example 2: Set Redis Session Storage (Environment Variable)

Name: env:CONFIG__DEFAULT__SYSTEM__FULL_PAGE_CACHE__CACHING_APPLICATION
Value: 2

Example 3: SCD On Demand (Environment Variable - Integration)

Name: env:SCD_ON_DEMAND
Value: true
☑ Inheritable by child environments

Example 4: Build Optimization (.magento.env.yaml)

stage:
  build:
    SCD_STRATEGY: compact
    SCD_THREADS: 3
    SKIP_HTML_MINIFICATION: true

Example 5: PHP Memory Limit (Project Variable)

magento-cloud project:variable:set php:memory_limit 2G

Inheritance and Cascading

How Variables Cascade

Environment Variable Cascading

In the Project Web Interface, you must select "Inheritable by child environments" to enable cascading.

Example Hierarchy:
Integration (parent)
  ├── feature-1 (child)
  ├── feature-2 (child)
  └── bugfix-3 (child)

If you set a variable in Integration with inheritance enabled:

  • feature-1, feature-2, and bugfix-3 all inherit the variable
  • Children can override with their own value
  • Parent value used if child doesn't override

Best Practices

Variable Management

Do's

  • Use env: prefix for Magento configuration overrides
  • Mark sensitive variables as "Sensitive" in UI
  • Use inheritance for variables that should cascade
  • Version control .magento.env.yaml changes
  • Document variables and their purpose
  • Use project variables for build phase needs
  • Test in integration before applying to production

Don'ts

  • Don't commit secrets to .magento.env.yaml
  • Don't forget env: prefix for Magento config
  • Don't set conflicting variables in multiple places
  • Don't forget to redeploy after setting project variables
  • Don't overuse variables - use when necessary

Troubleshooting

Common Issues

Issue 1: Variable Not Taking Effect

Possible Causes:
  • Missing env: prefix for Magento configuration
  • Variable set but environment not redeployed
  • Typo in variable name
  • Child environment overriding parent value
Solution:
  1. Verify variable name includes env: prefix
  2. Check variable is set: magento-cloud variable:list
  3. Redeploy environment or push blank commit
  4. Check if child has override

Issue 2: Project Variable Not Available in Build

Solution:

Ensure you're using project:variable:set (not just variable:set). Only project variables are available during build phase.

Exam Tips

Key Points to Remember

  • Variables in .magento.env.yaml: Control build/deploy, little long-term use
  • Four phases: build, deploy, post-deploy, global
  • Environment variables: Configured per environment in Project Web CLI
  • env: prefix REQUIRED: For Magento configuration changes
  • Cascading: Environment variables cascade to child environments (if enabled)
  • Project variables: magento-cloud project:variable:set
  • Apply to all environments: Including build phase
  • Redeploy needed: git commit --allow-empty after project variable
  • Environment variables: Per environment, can contain sensitive data
  • "Inheritable by child environments": Must select in UI for cascade
  • Automatic redeploy: Environment variables trigger auto-redeploy
  • Manual redeploy: Project variables require blank commit
Previous: Cloud 7.05 Multisite Configuration Practice Cloud 7.06