cv_workflow¶

Note

Always use the FQCN (Fully Qualified Collection Name) arista.avd.cv_workflow when using this plugin.

Deploy various objects to CloudVision

Synopsis¶

The arista.avd.cv_workflow module is an Ansible Action Plugin providing the following capabilities:

Verify Devices are in the CloudVision inventory.
Verify Devices are in the Inventory & Topology Studio.
Update the Device hostname in the Inventory & Topology Studio as needed.
Create Workspace and build, submit, abandon as needed.
Deploy device-specific EOS configurations using Static Configuration Studio.
Deploy a full hierarchy of containers and configlets using Static Configuration Studio.
Create and associate Device and Interface Tags.
Approve, run, cancel Change Controls as needed.
Decommission devices marked with is_deployed: false from CloudVision (requires inventory_mode: controlled and CloudVision 2025.1.0 or later).

Parameters¶

Argument	Type	Required	Default	Value Restrictions	Description
`cv_servers`	list	True	None	-	List of hostnames or IP addresses for CloudVision instance to deploy to.
`cv_token`	str	False	None	-	Service account token. It is strongly recommended to use Vault for this.
`cv_username`	str	False	None	-	Username to use if `cv_token` is missing. Not supported for CVaaS.
`cv_password`	str	False	None	-	Password to use if `cv_token` is missing. Not supported for CVaaS. It is strongly recommended to use Vault for this.
`cv_verify_certs`	bool	optional	True	-	Verifies CloudVison server certificates.
`cv_deploy_future`	dict	optional	None	-	Opt-in to future `cv_deploy` behaviors which will become default behaviors in a future major version.
`use_system_certs`	bool	optional	False	-	Use system certificates instead of Python's bundled certificate store. Honors `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables.
`proxy_host`	str	False	None	-	FQDN/IP of the HTTP CONNECT proxy server.
`proxy_port`	int	optional	8080	-	TCP port of the HTTP CONNECT proxy server.
`proxy_username`	str	False	None	-	Authentication username for the HTTP CONNECT proxy server.
`proxy_password`	str	False	None	-	Authentication password for the HTTP CONNECT proxy server. It is strongly recommended to use Vault for this.
`configuration_dir`	str	True	None	-	Path to directory containing .cfg files with EOS configurations.
`structured_config_dir`	str	False	None	-	Path to directory containing files with AVD structured configurations. If found, the `serial_number` or `system_mac_address` will be used to identify the Device on CloudVision. Any tags found in the structured configuration metadata will be applied to the Device and/or Interfaces.
`structured_config_suffix`	str	optional	yml	-	File suffix for AVD structured configuration files.
`device_list`	list	False	None	-	List of devices to deploy. The names are used to find AVD structured configuration and EOS configuration files.
`strict_tags`	bool	optional	False	-	If `true` other tags associated with the devices will get removed. Otherwise other tags will be left as-is.
`skip_missing_devices`	bool	optional	False	-	If `true` anything that can be deployed will get deployed. Otherwise the Workspace will be abandoned on any issue.
`inventory_mode`	str	optional	loose	Valid values: - `loose` - `controlled`	Controls how devices with `is_deployed: false` are handled. - `loose` (default): Devices with `is_deployed: false` are silently skipped. No changes are made to CloudVision for these devices. - `controlled`: Devices with `is_deployed: false` are decommissioned from CloudVision. CloudVision removes device-specific containers and all device and interface tag assignments associated with the device. CloudVision does not remove configlets or tag definitions. After decommission staging succeeds, AVD removes any leftover flat-layout device configlet, including for devices using the manifest layout. The supplied static configuration manifest remains authoritative and is reconciled after decommission staging. AVD does not delete tag definitions. Requires CloudVision 2025.1.0 or later when set to `controlled`.
`strict_system_mac_address`	bool	optional	False	-	If `true`, raise an exception if the input data contains devices with a duplicated system_mac_address but unique serial_number values. Otherwise, just issue a warning.
`configlet_name_template`	str	optional	AVD-${hostname}	-	Python String Template to use for creating the configlet name for each device configuration.
`static_config_manifest`	dict	optional	None	-	Deploy a manifest of containers and configlets to CloudVision using the Static Configuration Studio.
`preserve_existing_containers`	bool	optional	False	-	Preserve existing manifest-managed root containers and their children when they are not declared in the current manifest. This enables partial manifests managing separate root-level branches. Existing manifest-managed container order is preserved, and newly declared containers are appended. Manually created root containers are always preserved and ordered after the manifest-managed containers.
`configlets`	list	optional	None	-	A list of dictionaries defining configlets to be pushed to the Configlet Library. Each dictionary in the list must follow this data model: - name (`str`, required): Unique name for the configlet. - file (`str`, required): Filesystem path to the text file containing the configlet body. Relative to the current working directory.
`containers`	list	optional	None	-	A list of dictionaries defining the root containers in the hierarchy. Each dictionary in the list must follow this data model: - name (`str`, required): Name for the container. Sibling containers must have unique names. - tag_query (`str`, required): A query string used to match devices based on their assigned tags. - description (`str`, optional): An optional description for the container. - match_policy (`str`, optional, default: "match_all"): The match policy to determine how devices with a matching tag inherit a child container configlets. Valid choices are `match_all` or `match_first`. - preserve_existing_sub_containers (`bool`, optional, default: `false`): Preserve existing manifest-managed child containers under this container when they are not declared in the current manifest. This enables partial manifests managing sibling branches under a shared parent. Existing manifest-managed child container order is preserved, and newly declared child containers are appended. - configlets (`list` of `str`, optional): A list of configlet names to apply to this container. Must be defined in the `configlets` section. - sub_containers (`list` of `dict`, optional): A nested list of container dictionaries that follow this same data model, allowing for a full hierarchy.
`workspace`	dict	optional	None	-	CloudVision Workspace to create or use for the deployment.
`name`	str	optional	None	-	Optional name to use for the created Workspace. By default the name will be `AVD <timestamp>`.
`description`	str	optional	None	-	Optional description to use for the created Workspace.
`id`	str	optional	None	-	Optional ID to use for the created Workspace. If there is already a workspace with the same ID, it must be in the 'pending' state.
`requested_state`	str	optional	built	Valid values: - `pending` - `built` - `submitted` - `abandoned` - `deleted`	The requested state for the Workspace. - `pending`: Leave the Workspace in pending state. - `built`: Build the Workspace but do not submit. - `submitted` (default): Build and submit the Workspace. - `abandoned`: Build and then abandon the Workspace. Used for dry-run where no changes will be committed to CloudVision. - `deleted`: Build, abort and then delete the Workspace. Used for dry-run where no changes will be committed to CloudVision and the temporary Workspace will be removed to avoid "clutter".
`force`	bool	optional	False	-	Force submit the workspace even if some devices are not actively streaming to CloudVision.
`build_warnings`	dict	optional	None	-	Configuration for Workspace build warnings handling.
`enabled`	bool	optional	True	-	Fetch and expose Workspace build warnings.
`suppress_patterns`	list	optional	[]	-	Arbitrary list of regex patterns used with fullmatch to suppress EOS CLI warnings.
`suppress_portfast`	bool	optional	False	-	Suppress Workspace build warnings related to the usage of the `portfast` feature on switchports.
`max_sync_retries`	int	optional	5	-	Maximum number of retry attempts to synchronize Workspace. Requires CloudVision 2026.2.0 or later.
`change_control`	dict	optional	None	-	CloudVision Change Control to create for the deployment.
`name`	str	optional	None	-	Optional name to use for the created Change Control. By default the name generated by CloudVision will be kept.
`description`	str	optional	None	-	Optional description to use for the created Change Control.
`requested_state`	str	optional	pending approval	Valid values: - `pending approval` - `approved` - `running` - `completed`	The requested state for the Change Control. - `pending approval` (default): Leave the Change Control in "pending approval" state. - `approved`: Approve the Change Control but do not start. - `running`: Approve and start the Change Control. Do not wait for the Change Control to be completed or failed. - `completed`: Approve and start the Change Control. Wait for the Change Control to be completed.
`timeouts`	dict	optional	None	-	Timeouts for long running operations. May need to be adjusted for large inventories.
`workspace_build_timeout`	float	optional	300.0	-	Time to wait for Workspace build before failing.
`change_control_creation_timeout`	float	optional	300.0	-	Time to wait for Change Control creation before failing.
`return_details`	bool	optional	False	-	If `true` all details will be returned to Ansible and can be registered. For large inventories this can affect performance, so it is disabled by default.
`preview_features`	dict	optional	None	-	Enable preview features of the plugin. Preview features may change or be removed without notice.
`read_from_validated_inputs`	bool	optional	False	-	When enabled, structured configurations are loaded from validated JSON files in `tmp_dir` instead of `structured_config_dir`. This requires the `arista.avd.validate_inputs` plugin to run first in the same playbook to generate the validated files.
`tmp_dir`	str	False	None	-	Path to the AVD temporary directory containing validated input files. Must be the same path as used for the `arista.avd.validate_inputs` plugin. Required when `preview_features.read_from_validated_inputs` is `true`.

Notes¶

When interacting with CVaaS the regional URL where the tenant is deployed should be used, e.g: cv_servers: [www.cv-prod-euwest-2.arista.io] To see the full list of regional URLs, please visit the cv_deploy role documentation.
To generate service accounts check cv_deploy role documentation or the CloudVision Help Center.

Examples¶

---
- name: Configuration deployment with CVP
  hosts: FABRIC
  connection: local
  gather_facts: false
  tasks:
    - name: Provision CVP with AVD configuration
      run_once: true
      delegate_to: localhost
      arista.avd.cv_workflow:
        cv_servers: ["www.arista.io"]
        cv_token: "<insert vaulted service account token here>"
        # cv_verify_certs: true
        # cv_deploy_future:
        #   use_system_certs: false
        # proxy_host: "proxy.local.domain"
        # proxy_port: "8080"
        # proxy_username: "avd_user"
        # proxy_password: "avd_password"
        configuration_dir: "{{ inventory_dir }}/intended/configs"
        structured_config_dir: "{{ inventory_dir }}/intended/structured_configs"
        # structured_config_suffix: "yml"
        device_list: "{{ ansible_play_hosts }}"
        # strict_tags: false
        # skip_missing_devices: false
        # inventory_mode: loose
        # strict_system_mac_address: false
        # configlet_name_template: "AVD-${hostname}"
        # static_config_manifest:
        #   configlets:
        #     - name: "GLOBAL_NTP_SERVERS"
        #       file: "configlets/global_ntp.txt"
        #     - name: "CORP_BANNER"
        #       file: "configlets/corp_banner.txt"
        #   containers:
        #     - name: "Global"
        #       tag_query: "device:*"
        #       match_policy: "match_all"
        #       configlets:
        #         - name: "GLOBAL_NTP_SERVERS"
        #       sub_containers:
        #         - name: "Data Centers"
        #           tag_query: "topology_network_type:datacenter"
        #           configlets:
        #             - name: "CORP_BANNER"
        workspace:
        #   name:
        #   description:
        #   id: <uuid or similar>
          requested_state: submitted
          force: true
          build_warnings:
            # enabled: true
            suppress_patterns: [".*/32 IPv4 address is not configured on the interface.*"]
            # suppress_portfast: false
          # max_sync_retries: 5
        change_control:
        #   name:
        #   description:
          requested_state: "approved"
        # timeouts:
        #   workspace_build_timeout: 300.0
        #   change_control_creation_timeout: 300.0
        # return_details: false

Authors¶

Arista Ansible Team (@aristanetworks)