Arista Networks

Arista Networks

Certified
Enterprise Edition

Run commands, checks and guarded image upgrades on Arista EOS switches through eAPI, and manage configlets, image bundles and change controls on CloudVision.

How to use the Arista plugin

Automate Arista EOS switches from Kestra through eAPI (JSON-RPC runCmds over HTTPS): run commands, check a switch before and after an upgrade, stage and activate an image, reload, wait for the return, commit or roll back. The cvp tasks drive Arista CloudVision (CVP on-prem and CVaaS): inventory, configlets, image bundles, tasks and change controls. See CloudVision below.

Authentication

The eos tasks share the same connection properties. The cvp tasks have their own, see CloudVision.

  • host, username, password are required. Store the password as a secret and set the connection once for all tasks with plugin defaults.
  • port defaults to 443. connectTimeout (10 s) and requestTimeout (60 s) can be raised.
  • caCertificate takes the PEM of the CA that signed the switch certificate. For a lab with a self-signed certificate set insecureTrustAllCertificates: true, which disables certificate and host name validation.
  • eAPI is always called over HTTPS, there is no plain HTTP mode.
  • eAPI must be enabled on the switch: management api http-commands, protocol https, no shutdown.

The password is never logged and never part of an output.

Tasks

  • eos.RunCommands: run CLI commands, JSON results with automatic text fallback (error 1003), store: true writes results to a file.
  • eos.Check: phase: PRE (checks flash, redundancy, writes the snapshot) and phase: POST (adds interface, compares with the snapshot). Returns version, modelName, bootupTimestamp, status (ok/ko), checksPassed, checksFailed and snapshot. A failed check returns ko, it does not fail the task. The version comparison belongs to the flow.
  • eos.Activate: idempotent copy of the image from an HTTP host, SHA-512 verification, boot system. No reload. Fails with ActivateFailed and a stage (COPY, CHECKSUM, BOOT, SPACE).
  • eos.Reload: write memory then reload now, never sent twice (guard on snapshot boot time and targetVersion). Output alreadyReloaded.
  • eos.WaitForReturn: waits for eAPI, a new boot time, the MLAG peer, the MLAG reload delay and a stabilisation window. Outputs measured durations.
  • eos.Commit: write memory, optional removal of the previous image (off by default).
  • eos.Rollback: checks the previous image is on flash, boot system, write memory, guarded reload. Output bootupTimestamp is the baseline for the following WaitForReturn (previousBootupTimestamp). Wrap that WaitForReturn in an If on outputs.<id>.alreadyReloaded == false: when no reload was sent there is no boot to wait for. Fails with RollbackFailed, never retries.
  • eos.ConfigSession: DIFF (dry run), APPLY (optionally with commitTimer), CONFIRM, ABORT on a named EOS config session, MERGE or REPLACE mode.

Errors

Error messages start with a stable name: DeviceUnreachable (retryable while the switch reboots), AuthFailure (HTTP 401, never retried), CommandError (eAPI code and message), ActivateFailed, RollbackFailed.

Do not set a task level retry on Reload or Rollback: it does not filter by error type. WaitForReturn retries connection errors itself.

Upgrade one MLAG pair, one peer at a time

Backup peer first, the primary only once the backup passed its post-check, with a fresh pre-check of the primary just before it is touched. Any failed post-check rolls the peer back and stops the flow. The target version comes from an input, the credentials from secrets.

id: arista_mlag_pair_upgrade
namespace: company.network

inputs: 
  - id: backup_host
    type: STRING
  - id: primary_host
    type: STRING
  - id: target_version
    type: STRING
    defaults: 4.36.0F
  - id: image_url
    type: STRING
    defaults: http://images.lab.example.com: 8082/eos/4.36.0F/EOS-4.36.0F.swi

pluginDefaults: 
  - type: io.kestra.plugin.ee.arista.eos
    forced: false
    values: 
      username: "{{ secret('ARISTA_USERNAME') }}"
      password: "{{ secret('ARISTA_PASSWORD') }}"
      caCertificate: "{{ secret('ARISTA_CA_PEM') }}"

tasks: 
  - id: backup_pre
    type: io.kestra.plugin.ee.arista.eos.Check
    host: "{{ inputs.backup_host }}"
    phase: PRE
    imageUrl: "{{ inputs.image_url }}"

  - id: backup_pre_gate
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.backup_pre.status != 'ok' }}"
    then: 
      - id: backup_pre_failed
        type: io.kestra.plugin.core.execution.Fail
        errorMessage: "Pre-check failed on {{ inputs.backup_host }}: {{ outputs.backup_pre.checksFailed }}"

  - id: backup_activate
    type: io.kestra.plugin.ee.arista.eos.Activate
    host: "{{ inputs.backup_host }}"
    imageUrl: "{{ inputs.image_url }}"

  - id: backup_reload
    type: io.kestra.plugin.ee.arista.eos.Reload
    host: "{{ inputs.backup_host }}"
    targetVersion: "{{ inputs.target_version }}"
    snapshot: "{{ outputs.backup_pre.snapshot }}"

  - id: backup_wait
    type: io.kestra.plugin.ee.arista.eos.WaitForReturn
    host: "{{ inputs.backup_host }}"
    snapshot: "{{ outputs.backup_pre.snapshot }}"

  - id: backup_post
    type: io.kestra.plugin.ee.arista.eos.Check
    host: "{{ inputs.backup_host }}"
    phase: POST
    snapshot: "{{ outputs.backup_pre.snapshot }}"

  - id: backup_post_gate
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.backup_post.status != 'ok' or outputs.backup_post.version != inputs.target_version }}"
    then: 
      - id: backup_rollback
        type: io.kestra.plugin.ee.arista.eos.Rollback
        host: "{{ inputs.backup_host }}"
        snapshot: "{{ outputs.backup_pre.snapshot }}"
      - id: backup_rollback_wait_gate
        type: io.kestra.plugin.core.flow.If
        condition: "{{ outputs.backup_rollback.alreadyReloaded == false }}"
        then: 
          - id: backup_rollback_wait
            type: io.kestra.plugin.ee.arista.eos.WaitForReturn
            host: "{{ inputs.backup_host }}"
            previousBootupTimestamp: "{{ outputs.backup_rollback.bootupTimestamp }}"
      - id: backup_rollback_post
        type: io.kestra.plugin.ee.arista.eos.Check
        host: "{{ inputs.backup_host }}"
        phase: POST
        snapshot: "{{ outputs.backup_pre.snapshot }}"
      - id: backup_failed
        type: io.kestra.plugin.core.execution.Fail
        errorMessage: "Post-check failed on {{ inputs.backup_host }}, rolled back (post-rollback check: {{ outputs.backup_rollback_post.status }}): {{ outputs.backup_post.checksFailed }}"

  - id: backup_commit
    type: io.kestra.plugin.ee.arista.eos.Commit
    host: "{{ inputs.backup_host }}"

  - id: primary_pre
    type: io.kestra.plugin.ee.arista.eos.Check
    host: "{{ inputs.primary_host }}"
    phase: PRE
    imageUrl: "{{ inputs.image_url }}"

  - id: primary_pre_gate
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.primary_pre.status != 'ok' }}"
    then: 
      - id: primary_pre_failed
        type: io.kestra.plugin.core.execution.Fail
        errorMessage: "Pre-check failed on {{ inputs.primary_host }}: {{ outputs.primary_pre.checksFailed }}"

  - id: primary_activate
    type: io.kestra.plugin.ee.arista.eos.Activate
    host: "{{ inputs.primary_host }}"
    imageUrl: "{{ inputs.image_url }}"

  - id: primary_reload
    type: io.kestra.plugin.ee.arista.eos.Reload
    host: "{{ inputs.primary_host }}"
    targetVersion: "{{ inputs.target_version }}"
    snapshot: "{{ outputs.primary_pre.snapshot }}"

  - id: primary_wait
    type: io.kestra.plugin.ee.arista.eos.WaitForReturn
    host: "{{ inputs.primary_host }}"
    snapshot: "{{ outputs.primary_pre.snapshot }}"

  - id: primary_post
    type: io.kestra.plugin.ee.arista.eos.Check
    host: "{{ inputs.primary_host }}"
    phase: POST
    snapshot: "{{ outputs.primary_pre.snapshot }}"

  - id: primary_post_gate
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.primary_post.status != 'ok' or outputs.primary_post.version != inputs.target_version }}"
    then: 
      - id: primary_rollback
        type: io.kestra.plugin.ee.arista.eos.Rollback
        host: "{{ inputs.primary_host }}"
        snapshot: "{{ outputs.primary_pre.snapshot }}"
      - id: primary_rollback_wait_gate
        type: io.kestra.plugin.core.flow.If
        condition: "{{ outputs.primary_rollback.alreadyReloaded == false }}"
        then: 
          - id: primary_rollback_wait
            type: io.kestra.plugin.ee.arista.eos.WaitForReturn
            host: "{{ inputs.primary_host }}"
            previousBootupTimestamp: "{{ outputs.primary_rollback.bootupTimestamp }}"
      - id: primary_rollback_post
        type: io.kestra.plugin.ee.arista.eos.Check
        host: "{{ inputs.primary_host }}"
        phase: POST
        snapshot: "{{ outputs.primary_pre.snapshot }}"
      - id: primary_failed
        type: io.kestra.plugin.core.execution.Fail
        errorMessage: "Post-check failed on {{ inputs.primary_host }}, rolled back (post-rollback check: {{ outputs.primary_rollback_post.status }}): {{ outputs.primary_post.checksFailed }}"

  - id: primary_commit
    type: io.kestra.plugin.ee.arista.eos.Commit
    host: "{{ inputs.primary_host }}"

CloudVision (CVP and CVaaS)

The cvp tasks call the CloudVision REST APIs over HTTPS: the legacy /cvpservice API for inventory, configlets, image bundles and tasks, and the resource API (/api/resources/changecontrol/v1) for change controls (CVP 2021.2 or later, or CVaaS). Image upload, Studios and Workspaces, and telemetry queries are not covered.

Gotchas:

  • CVP 2025.2 and later needs the networkprovisioning service enabled for the legacy provisioning API (configlet and image bundle assignment, containers).
  • The inventory comes from /cvpservice/inventory/devices?provisioned=true. Devices are matched on FQDN, hostname, serial number or IP, and keyed by systemMacAddress. That API only returns the key of the parent container of a device, so GetInventory reads /cvpservice/inventory/containers once to resolve the container name, which stays empty when the container is not found.
  • ChangeControl CREATE takes taskIds only: it does not describe device actions itself, stage the tasks first with Configlet, ImageBundle or GetTasks.

Authentication

  • host is required (www.cv-prod-<region>.arista.io for CVaaS, or your on-prem CVP). port defaults to 443, connectTimeout to 10 s, requestTimeout to 60 s.
  • authType: SERVICE_ACCOUNT_TOKEN (default, CVaaS and on-prem): set token to a service account token, sent as a bearer token.
  • authType: USER_PASSWORD (on-prem only): set username and password. The task logs in, reuses the session cookie for the run and logs out at the end.
  • caCertificate takes the PEM of the CA that signed the CloudVision certificate. An on-prem CVP with a self-signed certificate needs it, or insecureTrustAllCertificates: true for a lab.
  • Store token and password as secrets and set the connection once with plugin defaults on io.kestra.plugin.ee.arista.cvp. Token, password and session cookie are never logged and never part of an output.

Tasks

  • cvp.GetInventory: devices with hostname, serial number, model, EOS version, streaming status and container. Optional filter on hostname, serial number or model. fetchType (FETCH, FETCH_ONE, STORE, NONE) chooses the output, use STORE for large inventories.
  • cvp.Configlet: action: CREATE | UPDATE | DELETE | ASSIGN | UNASSIGN on a configlet name. config is inline or a kestra:// URI. device or container target the assignment. Idempotent: output changed is false when nothing had to be written, and content is compared ignoring line endings and trailing spaces. dryRun: true writes nothing and returns the diff (only then, so secrets in a configlet stay out of run outputs). ASSIGN, UNASSIGN and UPDATE of an assigned configlet return the CloudVision taskIds. When ASSIGN finds the configlet already assigned, nothing is written and taskIds is empty: the pending tasks cannot be attributed to this run with certainty, so pick them with GetTasks or skip the change control (see the example below).
  • cvp.ImageBundle: action: CREATE | UPDATE | DELETE | APPLY on an image bundle name. images are names of images already uploaded to CloudVision. Idempotent like Configlet, APPLY returns taskIds, empty when the bundle is already applied (same reason as Configlet).
  • cvp.GetTasks: CloudVision tasks by status (PENDING by default, FAILED, COMPLETED, CANCELLED), with the same fetchType as GetInventory. Tasks are executed through a change control, not here.
  • cvp.ChangeControl: action: CREATE | APPROVE | EXECUTE | WAIT. CREATE takes taskIds and name. The id is changeControlId, or derived from name: a change control with that id and the same taskIds is returned instead of a second one, one with other tasks fails with ChangeControlConflict. Use a unique name per run, for example with {{ execution.id }}. EXECUTE never starts a change control twice: when it is no longer PENDING or APPROVED, nothing is sent and alreadyExecuted is true. WAIT polls (pollInterval 10 s, at least 1 s, timeout 30 min) to COMPLETED, FAILED or CANCELLED. CloudVision has no failed status: a change control that ends COMPLETED with an error is reported as FAILED, and the failing stage comes from stageStates. With failOnError (default), WAIT fails on FAILED and CANCELLED. WAIT can run alone with a changeControlId, for example after a worker restart.

Errors

Error messages start with a stable name and include the CloudVision host and the failing call: CvpUnreachable (connection, TLS or timeout), CvpAuthFailure (HTTP 401 or 403, never retried), CvpRequest (HTTP status, CloudVision error code and message), ChangeControlFailed (change control id and failing stage), ChangeControlTimeout, ChangeControlConflict, ConfigletExists, ImageBundleExists. HTTP 429 is retried up to three times, honoring Retry-After (30 s at most).

Do not set a task level retry on ChangeControl with EXECUTE: it does not filter by error type. A change control waiting for a manual approval stays PENDING: WAIT ends with ChangeControlTimeout and the last known status. CloudVision may refuse the approval by the account that created the change control, according to your approval policy: the refusal is returned as a CvpRequest error.

Push a configlet, run it as a change control, then check the switch

The EOS Check before and after proves the switch is still healthy once CloudVision has pushed the change.

id: arista_cvp_configlet_rollout
namespace: company.network

pluginDefaults: 
  - type: io.kestra.plugin.ee.arista.cvp
    forced: false
    values: 
      host: www.cv-prod-us-central1-b.arista.io
      token: "{{ secret('CVP_TOKEN') }}"
  - type: io.kestra.plugin.ee.arista.eos
    forced: false
    values: 
      username: "{{ secret('ARISTA_USERNAME') }}"
      password: "{{ secret('ARISTA_PASSWORD') }}"
      caCertificate: "{{ secret('ARISTA_CA_PEM') }}"

tasks: 
  - id: pre_check
    type: io.kestra.plugin.ee.arista.eos.Check
    host: leaf1.lab.example.com
    phase: PRE

  - id: configlet
    type: io.kestra.plugin.ee.arista.cvp.Configlet
    action: CREATE
    name: ntp-servers
    config: |
      ntp server 10.0.0.1
      ntp server 10.0.0.2

  - id: assign
    type: io.kestra.plugin.ee.arista.cvp.Configlet
    action: ASSIGN
    name: ntp-servers
    device: leaf1

  # taskIds is empty when the configlet was already assigned, there is nothing to run then
  - id: if_tasks
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.assign.taskIds is not empty }}"
    then: 
      - id: cc
        type: io.kestra.plugin.ee.arista.cvp.ChangeControl
        action: CREATE
        name: "ntp-servers {{ execution.id }}"
        taskIds: "{{ outputs.assign.taskIds }}"

      - id: approve
        type: io.kestra.plugin.ee.arista.cvp.ChangeControl
        action: APPROVE
        changeControlId: "{{ outputs.cc.changeControlId }}"

      - id: execute
        type: io.kestra.plugin.ee.arista.cvp.ChangeControl
        action: EXECUTE
        changeControlId: "{{ outputs.cc.changeControlId }}"

      - id: wait
        type: io.kestra.plugin.ee.arista.cvp.ChangeControl
        action: WAIT
        changeControlId: "{{ outputs.cc.changeControlId }}"

  - id: post_check
    type: io.kestra.plugin.ee.arista.eos.Check
    host: leaf1.lab.example.com
    phase: POST
    snapshot: "{{ outputs.pre_check.snapshot }}"