Skip to content
Ansible Developer Tools

Migrating from EE Mode

The previous Ansible extension (pre-v27 / main branch) offered an “Execution Environment mode” controlled by ansible.executionEnvironment.* settings. When enabled, every Ansible tool invocation was routed through podman run --rm or docker run --rm, running inside a container while your editor stayed on the host.

This mode has been replaced by a Dev Container-based workflow that provides a superior development experience with less complexity. This guide walks you through the migration.

What changed

Section titled “What changed”
Feature Previous (main) Current (next)
EE development ansible.executionEnvironment.enabled + 6 related settings Dev Containers
Tool execution Routed through podman/docker run --rm Native — tools run directly in the container
Debugging Not available inside EE Full Python debugging inside Dev Container
Terminal Host terminal, commands proxied Container terminal with full access
EE inspection Via ansible-navigator Native tree view with vendored introspection
Collections/packages Copied to host cache Available directly in the container

Settings that no longer exist

Section titled “Settings that no longer exist”

The following settings from the previous extension are not available in the current version. Each has a recommended replacement.

ansible.executionEnvironment.enabled

Section titled “ansible.executionEnvironment.enabled”

Was: Master toggle for EE mode.

Replace with: Open your project in a Dev Container using the EE image. See Dev Containers.

ansible.executionEnvironment.image

Section titled “ansible.executionEnvironment.image”

Was: EE image reference (default: ghcr.io/ansible/community-ansible-dev-tools:latest).

Replace with: Set the image field in .devcontainer/devcontainer.json:

{
  "image": "your-ee-image:tag"
}

ansible.executionEnvironment.containerEngine

Section titled “ansible.executionEnvironment.containerEngine”

Was: auto | podman | docker selection for container commands.

Replace with: Dev Containers handles engine selection automatically. Configure via dev.containers.dockerPath in VS Code settings if needed.

ansible.executionEnvironment.containerOptions

Section titled “ansible.executionEnvironment.containerOptions”

Was: Extra engine flags (e.g., --net=host) appended to every run command.

Replace with: Use runArgs in .devcontainer/devcontainer.json:

{
  "runArgs": ["--net=host"]
}

ansible.executionEnvironment.volumeMounts

Section titled “ansible.executionEnvironment.volumeMounts”

Was: Array of {src, dest, options} objects mounted into every container invocation.

Replace with: Use mounts in .devcontainer/devcontainer.json for data directories:

{
  "mounts": [
    "source=/path/to/roles,target=/usr/share/ansible/roles,type=bind"
  ]
}

For SSH access, use SSH agent forwarding instead of mounting key directories. VS Code Dev Containers automatically forward the host SSH agent into the container. See SSH keys troubleshooting.

ansible.executionEnvironment.pull.policy and pull.arguments

Section titled “ansible.executionEnvironment.pull.policy and pull.arguments”

Was: Control when and how the EE image was pulled (always | missing | never | tag).

Replace with: Dev Containers pulls the image when you first open the container. To force a fresh pull, rebuild the container: Dev Containers: Rebuild Container.

Step-by-step migration

Section titled “Step-by-step migration”

  1. Identify your EE image

    Check your current settings for the image name:

    "ansible.executionEnvironment.image": "registry.example.com/my-ee:latest"

  2. Ensure the image has dev tools

    If your EE doesn’t include ansible-dev-tools, layer it on:

    FROM registry.example.com/my-ee:latest
    USER root
    RUN pip3 install --no-cache-dir ansible-dev-tools
    USER 1000

    Build: podman build -t my-ee-with-devtools:latest .

    See Add ansible-dev-tools to an EE for details.

  3. Generate devcontainer config

    Use ansible-creator with your EE (or layered) image:

    Terminal window
    ansible-creator add resource devcontainer /path/to/project \
      --image my-ee-with-devtools:latest

    Or right-click an EE in the sidebar and select Add Dev Container (prefills --image).

  4. Migrate volume mounts

    Convert each volumeMount entry to a Dev Container mounts entry:

    Previous format Dev Container format
    {"src": "/data/roles", "dest": "/roles", "options": "ro"} "source=/data/roles,target=/roles,type=bind,readonly"
    {"src": "${HOME}/.ssh", "dest": "/root/.ssh"} Use SSH agent forwarding instead (see troubleshooting)

  5. Remove old settings

    Delete the ansible.executionEnvironment block from .vscode/settings.json:

    {
      // Remove this entire block:
      "ansible.executionEnvironment.enabled": true,
      "ansible.executionEnvironment.image": "...",
      "ansible.executionEnvironment.containerEngine": "podman",
      "ansible.executionEnvironment.volumeMounts": [...]
    }

  6. Reopen in container

    Install the Dev Containers extension, then press Ctrl+Shift+P and select Dev Containers: Reopen in Container.

What you gain

Section titled “What you gain”
  • Full terminal access inside the EE — run ad-hoc commands, debug Python, test playbooks interactively
  • Python debugging — set breakpoints in custom modules and plugins
  • Consistent linting — ansible-lint runs against the same Python environment and collections your playbooks target
  • Simplified configuration — one devcontainer.json replaces seven settings
  • No subprocess routing — no more TTY/escaping issues from host-side docker run / podman run proxies

ansible-navigator with EEs

Section titled “ansible-navigator with EEs”

If you previously used ansible-navigator run with EE flags (--ee true --eei <image>), navigator continues to work inside the Dev Container. Since you are already inside the EE, run navigator with --ee false (the default when EE mode is disabled):

Terminal window
ansible-navigator run playbook.yml --ee false
Section titled “Related”