Manage DeploymentsRemote ExecutionCore configuration

Configure state store backend

Starting with Airflow 3.3 (Astro Runtime 3.3), tasks and asset watchers can persist state between runs through the Airflow worker-side state store. Remote Execution Agents store this state in a backend that you control, so it stays in your execution plane. This guide covers the default configuration that the Remote Execution Agent Helm chart applies and how to configure object storage for production.

Overview

Airflow 3.3 introduces a worker-side state store that tasks and asset watchers use to persist small state values between runs. For example, an asset watcher uses it to track its position in an event stream. By default, Airflow stores this state in the metadata database. With Remote Execution, the metadata database resides in the Astro orchestration plane, so a custom state store backend keeps the data in storage that you control instead. This is the same pattern as the XCom backend.

Agent Client 1.8.0 and later enforce this on Astro Runtime 3.3 and later images: agents don’t start until you set the AIRFLOW__WORKERS__STATE_STORE_BACKEND environment variable. Runtime versions earlier than 3.3 don’t include the state store, and agents apply no state store configuration there.

Prerequisites

Default configuration

Remote Execution Agent Helm chart 2.3.0 and later configure the state store backend automatically. The stateStoreBackend value defaults to the object storage backend from the Common IO provider:

values.yaml
1stateStoreBackend: airflow.providers.common.io.state_store.backend.StateStoreObjectStorageBackend

The chart sets AIRFLOW__WORKERS__STATE_STORE_BACKEND to this class on every agent component. If you don’t configure a storage path yourself, the chart also applies a local file path default:

AIRFLOW__COMMON_IO__STATE_STORE_OBJECTSTORAGE_PATH=file:///usr/local/airflow/state-store
Local path default is for evaluation only

With the local file path, each agent Pod writes state to its own container filesystem: state isn’t shared between Pods and doesn’t survive Pod restarts. Configure shared object storage for production deployments.

Configure object storage for production

Point the state store at shared object storage by setting the storage path in commonEnv:

values.yaml
1stateStoreBackend: airflow.providers.common.io.state_store.backend.StateStoreObjectStorageBackend
2
3commonEnv:
4  - name: AIRFLOW__COMMON_IO__STATE_STORE_OBJECTSTORAGE_PATH
5    value: "s3://<connection-id>@<bucket-name>/<path-to-state-store>"

The path format and authentication follow the same patterns as the XCom backend, and you can reuse the same bucket and connection with a different path prefix. See Configure XCom backend for cloud-specific instructions for AWS S3, Azure Blob Storage, and GCP Cloud Storage, including bucket setup, workload identity, and connection configuration.

After updating your values, apply the configuration:

1helm upgrade astro-agent astronomer/astro-remote-execution-agent -f values.yaml

Configure the backend on chart versions earlier than 2.3.0

Helm chart versions earlier than 2.3.0 don’t include the stateStoreBackend value. Before you move agents to a Runtime 3.3 image, either upgrade to chart 2.3.0 or later, or set the environment variables on all agent components through commonEnv:

values.yaml
1commonEnv:
2  - name: AIRFLOW__WORKERS__STATE_STORE_BACKEND
3    value: "airflow.providers.common.io.state_store.backend.StateStoreObjectStorageBackend"
4  - name: AIRFLOW__COMMON_IO__STATE_STORE_OBJECTSTORAGE_PATH
5    value: "s3://<connection-id>@<bucket-name>/<path-to-state-store>"

Custom backend classes

If you use a different state store backend class, set stateStoreBackend to your class and configure its settings through commonEnv. The chart only applies the local path default for the object storage backend.

Verify configuration

After applying your configuration:

  1. Confirm all agent Pods start successfully. On Runtime 3.3 images, an agent fails to start with a validation error if AIRFLOW__WORKERS__STATE_STORE_BACKEND isn’t set.
  2. Trigger a Dag that uses the state store, for example through an asset watcher.
  3. Verify that state objects appear under your configured storage path.

Next steps