Deploy Configurations

deploy Command¶

Deploy configurations to Arista EOS devices via eAPI with validation and diff support.

Synopsis¶

avd-cli deploy eos [OPTIONS]

Common Options¶

Option	Short	Type	Default	Description
`--inventory-path`	`-i`	Path	Required	Path to Ansible inventory directory
`--configs-path`	`-c`	Path	Auto	Path to configuration files (default: `<inventory>/intended/configs`)
`--dry-run`		Flag	`false`	Preview changes without applying them
`--diff`		Flag	`false`	Display full configuration differences
`--verify-ssl`		Flag	`false`	Enable SSL certificate verification
`--limit`	`-l`	Text	All	Filter devices by hostname or group patterns (repeatable, supports wildcards)
`--limit-to-groups`		Text	All	Deprecated. Use `--limit` instead. Deploy to specific groups
`--verbose`	`-v`	Flag	`false`	Show detailed deployment progress

See Environment Variables for configuration via environment variables.

Required variables in your inventory:

Variable	Required	Notes
`ansible_host`	Yes	IP/FQDN to connect to
`ansible_user`	Yes	eAPI username
`ansible_password`	Yes	eAPI password
`ansible_network_os`	No	`arista.eos.eos` (default). Non-EOS hosts are skipped
`ansible_httpapi_validate_certs`	No	SSL cert verification, default `false`. Overridden by `--verify-ssl` flag
`ansible_httpapi_use_ssl`	No	Must be `true` — HTTPS always used

Variable precedence (highest → lowest):

Host-level variables (highest priority)
Group-level variables
all.vars (lowest priority)

Quick Start¶

Basic Deployment¶

Deploy all configurations with validation:

avd-cli deploy eos -i ./inventory

Preview Changes (Recommended)¶

Always preview changes before applying:

avd-cli deploy eos -i ./inventory --dry-run --diff

Production Deployment¶

Deploy with SSL verification enabled:

avd-cli deploy eos -i ./inventory --verify-ssl

Key Features¶

🔍 Dry-Run Mode¶

Preview configuration changes without modifying devices.

avd-cli deploy eos -i ./inventory --dry-run

What happens:

✅ Connects to devices
✅ Generates configuration diffs
✅ Validates configurations
❌ Does NOT apply changes

Best Practice

Always run with --dry-run first to validate changes before live deployment.

📊 Configuration Diff¶

Display detailed configuration differences:

avd-cli deploy eos -i ./inventory --diff

Output example:

spine-1:
--- running-config
+++ intended-config
@@ -10,7 +10,7 @@
 hostname spine-1
 !
 interface Ethernet1
-   description old description
+   description new description
    no switchport

Note

Diff statistics (lines added/removed) are always shown in the status table. The --diff flag displays the full unified diff for each device.

🔒 SSL Verification¶

AVD CLI always uses HTTPS (eAPI over SSL) to communicate with devices. The --verify-ssl flag (or ansible_httpapi_validate_certs: true in inventory) controls whether the SSL certificate chain is validated.

--verify-ssl takes precedence over ansible_httpapi_validate_certs in inventory.

Lab EnvironmentProduction

# Default — SSL certificate validation disabled
avd-cli deploy eos -i ./inventory

Suitable for lab/dev environments with self-signed certificates.

# Enable SSL certificate validation
avd-cli deploy eos -i ./inventory --verify-ssl

Required for production to prevent man-in-the-middle attacks.

Advanced Options¶

Option	Type	Default	Description
`--no-session`	Flag	`false`	Skip config session validation (faster but riskier)
`--max-concurrent`	Integer	10	Maximum concurrent device deployments
`--timeout`	Integer	30	Connection timeout in seconds

Deployment Workflow¶

The deployment process follows these steps:

Load Inventory: Parse Ansible inventory to discover devices and credentials
Load Configurations: Read device configuration files from configs directory
Connect: Establish eAPI connections to target devices
Validate: Apply configs in a temporary session for validation (default)
Deploy: Commit validated configurations to devices
Report: Display results with diff statistics and errors

Configuration Validation¶

Default Mode (Recommended)¶

By default, configurations are validated using EOS config sessions before being applied:

avd-cli deploy eos -i ./inventory

How it works:

Creates temporary config session
Applies configuration to session
Validates syntax and semantics
Commits if valid, automatically rolls back if invalid

Recommended for Production

Config session validation provides safety and automatic rollback.

Fast Mode (Lab Only)¶

Skip validation for faster deployment in lab environments:

avd-cli deploy eos -i ./inventory --no-session

Use with Caution

No validation performed
No automatic rollback
Invalid config can disrupt device operation
Only use in lab environments

Credentials¶

Credentials are read from standard Ansible inventory variables. Define them at all.vars for global defaults, or override per group/host:

inventory.yml

all:
  vars:
    ansible_user: admin
    ansible_password: admin123
    ansible_network_os: arista.eos.eos
    ansible_httpapi_use_ssl: true
    ansible_httpapi_validate_certs: false
  children:
    spines:
      hosts:
        spine-1:
          ansible_host: 192.168.0.10
        spine-2:
          ansible_host: 192.168.0.11
    leafs:
      vars:
        ansible_user: leaf_admin          # Override username for all leafs
      hosts:
        leaf-1:
          ansible_host: 192.168.0.20
          ansible_password: leaf_secret   # Override password for this host only

Non-EOS hosts are skipped

Hosts with ansible_network_os set to anything other than arista.eos.eos (e.g., cisco.ios.ios) are automatically skipped by deploy eos with a warning. Hosts without ansible_network_os default to arista.eos.eos.

Usage Examples¶

Selective Deployment¶

The --limit option supports flexible device filtering for phased rollouts:

Group names: SPINES, LEAFS, BORDER_LEAFS
Hostname patterns: spine*, leaf-[12]*, border-?
Exact hostnames: spine-01, leaf-1a

Wildcard patterns:

* - Matches any characters: spine* matches spine-01, spine-02, spineA
? - Matches single character: leaf-? matches leaf-1, leaf-a
[...] - Matches character set: leaf-[12]a matches leaf-1a, leaf-2a

Examples:

# Deploy to specific group
avd-cli deploy eos -i ./inventory -l spines --dry-run
avd-cli deploy eos -i ./inventory -l spines

# Deploy to devices matching pattern
avd-cli deploy eos -i ./inventory -l "spine*"

# Deploy to specific devices
avd-cli deploy eos -i ./inventory -l spine-01 -l spine-02

# Mix hostname and group filters
avd-cli deploy eos -i ./inventory -l "spine*" -l BORDER_LEAFS

# Phased rollout
avd-cli deploy eos -i ./inventory -l spines --dry-run
avd-cli deploy eos -i ./inventory -l spines
avd-cli deploy eos -i ./inventory -l leafs --dry-run
avd-cli deploy eos -i ./inventory -l leafs

Deployment Filtering

Unlike generation, deployment filtering affects which devices receive configuration pushes via eAPI. Only devices matching the filter patterns will be contacted.

Custom Configuration Path¶

Use a custom configuration directory:

avd-cli deploy eos -i ./inventory -c ./custom-configs

Configuration files must be named <hostname>.cfg.

High Concurrency Deployment¶

Deploy to many devices simultaneously:

avd-cli deploy eos -i ./inventory --max-concurrent 20

Extended Timeout¶

Increase timeout for slow networks or large configurations:

avd-cli deploy eos -i ./inventory --timeout 120

Output¶

Deployment Plan¶

Deployment Plan (live deployment)
  Mode: merge
  Targets: 4 devices
  Concurrency: 10
  Credentials: admin / ********

⠼ Deploying to 4 devices...

Results Table¶

                      Deployment Status
┌────────────┬──────────┬──────────┬────────────┬────────────────────────┐
│ Hostname   │ Status   │ Duration │ Diff (+/-) │ Error                  │
├────────────┼──────────┼──────────┼────────────┼────────────────────────┤
│ spine-1    │ success  │ 2.34s    │ +15 / -3   │                        │
│ spine-2    │ success  │ 1.89s    │ +45 / -10  │                        │
│ leaf-1     │ success  │ 3.12s    │ +12 / -2   │                        │
│ leaf-2     │ failed   │ 5.00s    │ -          │ Connection timeout     │
└────────────┴──────────┴──────────┴────────────┴────────────────────────┘

Summary:
  ✓ Success: 3
  ✗ Failed: 1

⚠  1 deployment(s) failed

Columns:

Status: success, failed, or skipped
Duration: Time taken for deployment
Diff (±): Configuration changes (additions in green, deletions in red)
Error: Failure reason if applicable

Full Diff Output (–diff)¶

With --diff flag, view complete configuration changes:

spine-1:
--- running-config
+++ intended-config
@@ -10,7 +10,7 @@
 hostname spine-1
 !
 interface Ethernet1
-   description old description
+   description new description
    no switchport

Exit Codes¶

Code	Description
0	All deployments successful
1	One or more deployments failed

Best Practices¶

1. Always Dry-Run First

Preview changes before applying:

avd-cli deploy eos -i ./inventory --dry-run --diff

2. Incremental Deployment

Deploy to groups or patterns separately:

# Spines first (group name)
avd-cli deploy eos -i ./inventory -l spines

# Or by pattern
avd-cli deploy eos -i ./inventory -l "spine*"

# Then leafs
avd-cli deploy eos -i ./inventory -l leafs

# Or specific devices
avd-cli deploy eos -i ./inventory -l leaf-01 -l leaf-02

3. Version Control

Commit configurations before deployment:

git add inventory/intended/configs/
git commit -m "feat: update OSPF configuration"
git push

4. Test in Lab First

Validate in non-production environment:

# Lab
avd-cli deploy eos -i ./lab-inventory --dry-run

# Production (with SSL)
avd-cli deploy eos -i ./prod-inventory --verify-ssl

5. Backup Configurations

Always backup before major changes:

ansible-playbook backup-configs.yml -i inventory/inventory.yml

6. Use Config Session Validation

Enable validation for production (default):

# Production - with validation
avd-cli deploy eos -i ./inventory

# Lab only - skip validation for speed
avd-cli deploy eos -i ./lab-inventory --no-session

7. Adjust Timeouts

Set appropriate timeouts based on network:

Lab/Fast: 30s (default)
Production/WAN: 60-120s
Large configs: 120s+

avd-cli deploy eos -i ./inventory --timeout 120

8. Secure Credentials

Use Ansible Vault for sensitive data:

ansible-vault encrypt_string 'password' --name 'ansible_password'

9. Limit Concurrency

Don’t overwhelm production devices:

avd-cli deploy eos -i ./prod-inventory --max-concurrent 5

CI/CD Integration¶

GitHub Actions¶

.github/workflows/deploy.yml

name: Deploy Configurations

on:
  push:
    branches: [main]
    paths: ['inventory/intended/configs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install avd-cli
        run: pip install avd-cli

      - name: Dry-run
        run: avd-cli deploy eos -i ./inventory --dry-run --diff

      - name: Deploy
        if: github.ref == 'refs/heads/main'
        run: avd-cli deploy eos -i ./inventory --verify-ssl

GitLab CI¶

.gitlab-ci.yml

deploy:
  stage: deploy
  script:
    - pip install avd-cli
    - avd-cli deploy eos -i ./inventory --dry-run --diff
    - avd-cli deploy eos -i ./inventory --verify-ssl
  only:
    - main
  changes:
    - inventory/intended/configs/**