Glue 09 10 Migration

Upgrade an AWS Glue ETL job from Glue version 0.9 or 1.0 to Glue 4.0. Uses the run-fail-fix-rerun loop: update the job to Glue 4.0, run it, diagnose failures against a known breaking-change catalogue, patch the script or configuration, and repeat until the job succeeds or the fix attempt limit (5 iterations) is exhausted. If not able to upgrade, reverts the job and script to their original state.

Reference Documentation

• references/migration-notes.md -- Failure categories, detection patterns, code-level fixes, dependency version reference, and migration path notes (fact-checked against official Glue and Spark migration guides)

Workflow

Prerequisites

Before starting, confirm:

1. Job name — the exact Glue job name to upgrade.
2. AWS credentials — glue:GetJob/GetJobRun/GetJobRuns/StartJobRun/UpdateJob/BatchStopJobRun, s3:GetObject/s3:PutObject on the script bucket, logs:DescribeLogStreams/GetLogEvents/FilterLogEvents on /aws-glue/jobs/*, iam:GetRole and iam:PassRole on the job execution role.
3. Source Glue version — call glue:GetJob and verify GlueVersion is "0.9" or "1.0". Halt for any other version.
4. S3 write permission — verify script bucket is writable by attempting a s3:PutObject of a 0-byte probe to script_location + ".write-check", then delete it. If the write fails, ask the user for the correct S3 location to use for storing the updated script.
5. No active runs — call glue:GetJobRuns; confirm no RUNNING or STARTING state.

MUST NOT proceed if any prerequisite cannot be confirmed.

Constants

MAX_FIX_ATTEMPTS      = 5
MAX_TRANSIENT_RETRIES = 2
MAX_OOM_RETRIES       = 2
MAX_POLL_DURATION_SEC = 7200  # fallback if no successful run history available
POLL_TIMEOUT_FACTOR   = 1.5   # if history available: timeout = 1.5 × last successful run duration
POLL_INTERVAL_SEC     = 30
BACKUP_S3_SUFFIX      = ".glue40-upgrade-backup"

Step 1: Gather Job Information

Complexity routing: All jobs follow the same pipeline. ML transforms are a hard blocker (HALT in step 1.5). Jobs using the Encryption SDK take a two-step path (Step 1A then main loop). All other jobs proceed directly through the run-fail-fix loop.

1.1. Call glue:GetJob(JobName=<job_name>). Store as original_job_definition. Upload as JSON to <script_s3_directory>/.glue40-upgrade-backup.original_job_definition.json via s3:PutObject (where <script_s3_directory> is the S3 prefix up to the last / of script_location). 1.2. Extract: script_location, original_glue_version, original_default_args, original_worker_type, original_num_workers, original_max_capacity, execution_role, python_version. 1.2b. Call glue:GetJobRuns (max 5 runs). Find the most recent SUCCEEDED run and record its ExecutionTime (seconds) as last_success_duration. If no successful run exists, set last_success_duration = null. 1.3. Download job script from S3. Store as original_script_text. 1.4. Backup script — copy script to script_location + BACKUP_S3_SUFFIX using s3:GetObject (download) + s3:PutObject (upload to backup path). MUST NOT skip. 1.5. Hard blocker checks (evaluate in this order):

• ML transforms — check if job script references MLTransform or create_dynamic_frame with transform_type set, OR if Job.Command.Name is gluestreaming with ML features. If detected → HALT immediately: "BLOCKED: ML transforms not supported in Glue 4.0." (takes precedence over all other checks)
• Encryption SDK in args/script/SecurityConfiguration → do NOT halt. Run two-step upgrade: execute Step 1A below, then continue to Step 2.
• Python 2 in config → record as preflight fix, do NOT halt.

Step 1A: Intermediate Upgrade to Glue 2.0 (Encryption SDK path only)

1A.1. Call glue:UpdateJob: set GlueVersion="2.0", Command.PythonVersion="3", WorkerType="G.1X", NumberOfWorkers = the greater of 2 or the integer (truncated) value of the job's current MaxCapacity. Add "--user-jars-first": "true" to DefaultArguments. MUST NOT pass MaxCapacity. 1A.2. Initialize: intermediate_fix_attempt=0, intermediate_fingerprints=set(). 1A.3. Call glue:StartJobRun. Poll to completion (same 30s interval and 1.5× history timeout rules as Step 3). 1A.4. SUCCEEDED → continue to Step 2 (now upgrade to 4.0). FAILED → classify failure and apply fix using the same catalogue in references/migration-notes.md. 1A.5. Increment intermediate_fix_attempt. If >= MAX_FIX_ATTEMPTS → HALT: "BLOCKED: Intermediate Glue 2.0 upgrade failed after 5 attempts. Revert and inspect manually." → go to Step 7. 1A.6. Cycle detection: if fingerprint already seen → HALT → Step 7. 1A.7. Repeat from 1A.3 until SUCCEEDED or budget exhausted.