Skip to content

Ansible Collections For Nokia Event Driven Automation Platform#

Ansible is an open-source automation platform that allows you to automate tasks across a wide range of IT environments. It uses a simple, human-readable language to describe automation tasks, making it accessible to both developers and operations teams.
In order to extend the platform and meet specific needs and target environments, Ansible allows users to create custom modules and plugins that are packaged as Ansible collections and hosted at Ansible Galaxy.

Nokia provides a set of Ansible collections specifically designed for the Event Driven Automation (EDA) platform that allow users to automate interactions with the EDA platform and manage the resources under its management.

These collections do not provide modules for Nokia EDA platform installation.

Quick Start

Create a python virtual environment with packages required by the collections. The example below uses uv:

curl -LO https://github.com/nokia-eda/ansible-collections/blob/main/pyproject.toml
uv sync

Install Nokia EDA Ansible collections for the Core API and for the EDA applications you want to automate. The example below installs a collection for the Core API and for the Interfaces application:

ansible-galaxy collection install nokia.eda_core_v1 nokia.eda_interfaces_v1alpha1

Create the inventory file with the connection and authentication variables:

all:
  vars:
    eda_api_url: "https://eda.netdevops.me:9443" # Change to your EDA API URL
    client_secret: "k9NeZZK4LT6hHypzgy3djteFITEkUUaR" # Get client secret, see Authentication section
    eda_username: "admin"
    eda_password: "eda-demo"
  hosts:
    localhost:
      ansible_connection: "local"

Enjoy the automation:

You would want to use transactions all the time:

- name: Create Two Banners
  hosts: all
  gather_facts: false
  tasks:
    - name: Fetch EDA access token
      nokia.eda_utils_v1.get_token:
        base_url: "{{ eda_api_url }}"
        client_secret: "{{ client_secret }}"
        username: admin
        password: "{{ eda_password }}"
      register: token

    - name: Create banner for leafs
      nokia.eda_siteinfo_v1alpha1.banner:
        base_url: "{{ eda_api_url }}"
        auth_token: "Bearer {{ token.result.access_token }}"
        resource:
          metadata:
            labels:
              some-label: ansible-demo
            namespace: eda
            name: demo-leaf-banner
          spec:
            loginBanner: "This is a demo banner provisioned by Ansible on leafs"
            nodeSelector:
              - eda.nokia.com/role=leaf
        # the `state` attribute should not be present
        # to register the resource value as it is defined in a variable banner_leafs
        # state: present
      register: banner_leafs

    - name: Create banner for spines
      nokia.eda_siteinfo_v1alpha1.banner:
        base_url: "{{ eda_api_url }}"
        auth_token: "Bearer {{ token.result.access_token }}"
        resource:
          metadata:
            labels:
              some-label: ansible-demo
            namespace: eda
            name: demo-spine-banner
          spec:
            loginBanner: "This is a demo banner provisioned by Ansible on leafs"
            nodeSelector:
              - eda.nokia.com/role=spine
      register: banner_spines

    - name: Run transaction
      nokia.eda_core_v1.transaction.v2.transaction:
        base_url: "{{ eda_api_url }}"
        auth_token: "Bearer {{ token.result.access_token }}"
        description: "Banners creation"
        dryRun: false
        resultType: "normal"
        retain: true
        crs:
          - type:
              create:
                value: "{{ banner_leafs.result }}"
          - type:
              create:
                value: "{{ banner_spines.result }}"
      register: tx

    - name: print response
      ansible.builtin.debug:
        var: tx

    - name: Get TX execution result
      nokia.eda_core_v1.transaction.v2.result.execution:
        base_url: "{{ eda_api_url }}"
        auth_token: "Bearer {{ token.result.access_token }}"
        transactionId: "{{ tx.result.id }}"
        waitForComplete: true
        failOnErrors: true
      register: result_execution

    - name: print response
      ansible.builtin.debug:
        var: result_execution

    - name: Get TX summary
      nokia.eda_core_v1.transaction.v2.result.summary:
        base_url: "{{ eda_api_url }}"
        auth_token: "Bearer {{ token.result.access_token }}"
        transactionId: "{{ tx.result.id }}"
      register: result_summary

    - name: print response
      ansible.builtin.debug:
        var: result_summary

But you can also use direct CRUD operations if you need them.

- name: Create an interface
  hosts: all
  gather_facts: false
  tasks:
    - name: Fetch EDA access token
      nokia.eda_utils_v1.get_token:
        base_url: "{{ eda_api_url }}"
        client_secret: "{{ client_secret }}"
        username: admin
        password: "{{ eda_password }}"
      register: token

    - name: Create interface
      nokia.eda_interfaces_v1alpha1.interface:
        base_url: "{{ eda_api_url }}"
        auth_token: "Bearer {{ token.result.access_token }}"
        resource:
          metadata:
            labels:
              ansible: "true"
            name: leaf1-ethernet-1-14
            namespace: eda
          spec:
            enabled: true
            lldp: true
            members:
              - enabled: true
                interface: ethernet-1-14
                node: leaf1
            type: interface
        state: present
      register: response

    - name: print variable
      ansible.builtin.debug:
        var: response

EDA APIs and Collections#

Nokia EDA offers unprecedented extensibility to its users by allowing them to install EDA applications at any time. Its API surface is therefore also highly dynamic and extensible. The inherent extensibility of the API means that instead of a single collection for EDA, there is a standalone collection for EDA Core API and a collection per each EDA application provided by Nokia.
An Ansible user will therefore install collections for each EDA application they want to automate as well as the EDA Core API collection.

The collections are published on Ansible Galaxy under the nokia namespace and follow the eda_<collection-name>_<api-version> name pattern.

This documentation site provides detailed information about each collection, including installation instructions, usage examples, and argument specification and is split into the two sections:

  • Core collections - the collections for the EDA Core API and Utilities collection
  • Application collections - the collections for all Nokia-provided applications that you will find in the Nokia App Catalog.

The fully qualified collection name (FQCN) like nokia.eda_fabrics_v1alpha1 consists of the following parts:

  • nokia - the namespace
  • eda_fabrics_v1alpha1 - the collection name, where
    • eda - a static prefix indicating the collection is part of the EDA platform
    • fabrics1 - the application name this collection is built for. The name matches the app name as seen in the UI or defined in the app manifest and contains modules for managing resources provided by this application.
    • v1alpha1 - the application API version

Installation#

External dependencies#

Ansible is a Python-based framework that users can install with pip, uv or any other Python package manager.

The Nokia EDA collections requires ansible-core >= 2.15.0

Besides requiring the ansible-core package itself, the users of Nokia EDA collections would also need to install the external dependencies used by all Nokia EDA collections:

deepdiff >= 8.5.0
pydantic >= 2
python_dateutil >= 2.8.2
typing-extensions >= 4.7.1
urllib3 >= 2.1.0, < 3.0.0

dependencies = [
    "ansible-core >= 2.17",
    "deepdiff >= 8.5.0",
    "pydantic >= 2.11.7",
    "python-dateutil >= 2.9.0.post0",
    "typing-extensions >= 4.7.1",
    "urllib3 >= 2.1.0",
]

When using uv as a package manager, you can setup the suitable virtual environment with downloading the pyproject.toml file and installing the dependencies listed in it:

curl -LO https://github.com/nokia-eda/ansible-collections/blob/main/pyproject.toml
uv sync

Collections#

With the virtual environment created with the external dependencies installed users can proceed with installing the Nokia EDA collections.

A user would typically need to install several collections - the Core collection to leverage EDA's Core APIs (like Transactions, User management, Alarms, etc.) and one or more Application collections for the specific EDA applications they want to automate with Ansible.

To install the collections use the ansible-galaxy command provided with the Ansible installation. For example, if a user wants to manage interfaces in EDA platform with transactions support, they would install both Core and Interfaces collections:

ansible-galaxy collection install nokia.eda_core_v1 nokia.eda_interfaces_v1alpha1
If you want to install all collections

In case you don't want to pick and choose collections and want to install all we have to offer, you can take the all-collections.yaml file and use it with the ansible-galaxy command:

ansible-galaxy collection install -r all-collections.yaml

Versioning#

Collections include two types of versioning information:

API Version

This refers to the specific application API version for which the provider is built. In EDA, applications may have several API versions (e.g., v1alpha1, v1, v2, and so on). The provider's name will include the API version; for example, the interfaces-v1alpha1 provider is designed to be used with the Interfaces v1alpha1 API version.

This means automation users should focus on the API version supported, rather than the installed application version.

Provider Version

This is the version of the Terraform provider itself, which is independent of the Application API version. It follows Semantic Versioning principles and indicates changes to the provider's functionality, compatibility, documentation, and more. The provider version is visible in the registry UI and in the Git repository where the provider's code is stored.

In summary, for the provider with the name interfaces-v1alpha1 and version 0.1.0:

  • the application this provider is built for is Interfaces
  • the Interfaces API version is v1alpha1
  • and the provider version is 0.1.0.

Configuration#

Nokia EDA collections have to be provided with the configuration values to reach and authenticate with the EDA REST API.

Connection mode#

All collections use REST API to interact with EDA. The ansible_connection=local parameter instructs Ansible not to connect to any remote hosts, but instead run the tasks locally. Users can define the connection parameters in multiple places, here is an example that uses the inventory file:

ansible-inventory.yaml
all:
  hosts:
    localhost:
      ansible_connection: "local"

EDA API URL#

With eda_api_url users set the address of the EDA API server. This is the same address that is used to access the EDA UI and it must be provided with the URL schema and port.

To centrally set the variable for all collection one can use the same inventory file:

ansible-inventory.yaml
all:
  vars:
    eda_api_url: "https://try.eda.demo:9443" # Change to your EDA API URL
  hosts:
    localhost:
      ansible_connection: "local"

Authentication#

Naturally, all collections have to authenticate against the EDA API server in order to perform actions.

Ansible collections, like other non-browser-based API clients, use the Resource Owner Password Credentials Grant OAuth flow for authentication. This flow requires the API client to provide the following parameters:

EDA API Client ID

The api_client_id is an identifier for your API client. It is used to authenticate your requests to the EDA API. By default EDA comes with a pre-created client id of eda. Administrators can create other API client IDs.

Default value: eda.

EDA Client Secret

The client_secret variable contains a secret that is associated with the API Client ID; Stored in Keycloak identity manager and is used in the OAuth Resource Owner Password Credentials Grant to authenticate the API client.

Read more about authentication against EDA API in the API documentation.

In production environments the system administrator retrieves the API client secret from Keycloak and provides it to the trusted API clients. The Utilities collection contains a module nokia.eda_utils_v1.get_client_secret that can be used to retrieve the client secret from Keycloak by providing keycloak authentication data.

EDA Username and Password

The API client - Ansible - should have credentials of the EDA user it authenticates as. This is done by providing the eda_username and eda_password parameters in the provider configuration.

Default value for both is admin.

The nokia.eda_utils_v1.get_client_secret and nokia.eda_utils_v1.get_token modules from the Utilities collection can be used to perform authentication against the EDA API.

Known Issues#

  1. Certificate verification of the EDA API server is not enforced and can't be enabled in this release.
  2. Collections (beta version) were generated for the apps coming with EDA 25.8.1. Older releases won't be added.
  3. When creating resources using individual modules with state: present (not via Transaction) the response object does not contain the resource manifest.

  1. For Core API it will be core and for Utility modules it will be utils ↩