Discovery Preflight

Step 1: Environment Discovery

1. Ask for the MWAA environment name (or detect from context).

2. Fetch environment config:

   Copy

   aws mwaa get-environment --name <env>

   Extract: Airflow version, SourceBucketArn, DagS3Path, RequirementsS3Path, RequirementsS3ObjectVersion, PluginsS3Path, PluginsS3ObjectVersion, StartupScriptS3Path, StartupScriptS3ObjectVersion, AirflowConfigurationOptions, LoggingConfiguration, WeeklyMaintenanceWindowStart, WebserverAccessMode, KmsKey.

3. Fetch requirements.txt from S3 using the exact object version the environment references (artifacts may be versioned):

   Copy

   aws s3api get-object --bucket <bucket-name-from-SourceBucketArn> --key <RequirementsS3Path> \
     --version-id <RequirementsS3ObjectVersion> /dev/stdout

   SourceBucketArn is an ARN (arn:aws:s3:::my-bucket) — use the bare bucket name (after s3:::) for --bucket and s3://, not the ARN. If no version ID is set, fall back to aws s3 cp s3://<bucket-name-from-SourceBucketArn>/<RequirementsS3Path> -.

4. List DAGs via REST API:

   Copy

   aws mwaa invoke-rest-api --name <env> --method GET --path /dags

   Returns up to 100 DAGs per call (default limit). For environments with

   100 DAGs, paginate with --query-parameters '{"limit":"100","offset":"0"}' and increment offset until total_entries is reached.

5. Identify shared utilities: check for dags/common/, dags/utils/, or sys.path manipulation in local code.

6. Compute the S3 layout for the new or test environment (New-environment and Rehearsed upgrades only — skip for the Direct in-place upgrade): Derive paths for the new or test environment’s mutable artifacts, named after that environment’s name (<new-env> for the New-environment upgrade, <test-copy> for the Rehearsed in-place upgrade). Convention:

   • DAG path: dags-<env-name>/ (in same bucket)
   • requirements path: requirements-<env-name>.txt
   • plugins path: plugins-<env-name>.zip (if your current environment has plugins)
   • startup path: startup-<env-name>.sh (if your current environment has a startup script)

   Record these paths in the plan. The approach reference seeds them from your current environment’s artifacts and uses them at environment creation time. Separate paths ensure the new or test environment’s changes (AF3-fixed DAGs, target-updated requirements, and any plugin/startup changes) never affect your current environment, and vice versa.

Step 2: Pre-flight Safety Checks

1. S3 versioning: Check bucket versioning status:

   Copy

   aws s3api get-bucket-versioning --bucket <bucket-name-from-SourceBucketArn>

   If not enabled, recommend enabling and wait for user confirmation before proceeding.

2. Constraints file validation: Once the target version is selected (Step 4), download that version’s constraints file (see the constraint-file URL template in mwaa-version-matrix.md), cross-reference with current requirements.txt. Flag packages that conflict. Report blockers before proceeding.

3. KMS key-policy reuse check (approaches that create a new or test environment — New-environment and Rehearsed upgrades only): the new or test environment reuses your current environment’s KmsKey (Step 1) but gets a NEW environment ARN. Inspect the CMK key policy/grants (aws kms get-key-policy, aws kms list-grants) for conditions scoped to your current environment’s ARN; if present, add the new or test environment’s ARN/role before creating it, or create-environment/runtime encryption fails AccessDenied.

4. Execution-role trust-policy check (approaches that create a new or test environment — New-environment and Rehearsed upgrades only): if the new or test environment reuses your current environment’s execution role and that role’s trust policy has an aws:SourceArn condition scoped to your current environment’s ARN (the confused-deputy guard recommended in deploying-mwaa.md), create-environment succeeds but the new or test environment’s tasks fail AssumeRole at runtime. Inspect the role’s trust policy (aws iam get-role) for aws:SourceArn/aws:SourceAccount conditions scoped to your current environment’s ARN; if present, add the new or test environment’s ARN before creating it.

Step 3: Refresh Version Matrix

Fetch https://docs.aws.amazon.com/mwaa/latest/userguide/airflow-versions.html (opens in a new tab) and derive supported_versions, eos_versions, python_by_version, and latest_by_major (see mwaa-version-matrix.md). On fetch failure, retry or ask the user for the supported set — do not plan against assumed versions (MWAA validates the target at execution time). Map the source version to its Python version via the matrix (GetEnvironment does not return Python).

Step 4: Target Selection

Ask the user for the target Airflow version; offer the maximum supported version (“latest supported”) as the default. Validate:

• target is in supported_versions (creatable/available), and
• target is strictly newer than the source.

On failure, report the reason and re-prompt. Example: source 2.4.3, target 2.5.1 -> reject (“2.5.1 is past end-of-support; choose 2.7.2 or newer, or a 3.x version”). If the source is below 2.4.3, inform the user this is below supported upgrade paths; recommend manual intervention or recreation and do not proceed automatically.

Step 5: Plan the Upgrade Path (no execution)

Detection only; version jumps are EXECUTED later by the engine (Phase 7) on the new or test environment or your current environment, depending on the chosen approach. Apply the version-jump rules in mwaa-version-matrix.md to produce an ordered list of version jumps. For each version jump record from, to, python_change (crosses a Python-line boundary), and crosses_major (2.x -> 3.x). Also record eos_source (true if the source version is in eos_versions; informational — every remaining approach can upgrade away from an EOS source). The 2.11.x stepping-stone version is skipped only when the source is already 2.11.x (Python 3.12).