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 Utils, 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 as well as utilities collections:

ansible-galaxy collection install nokia.eda_utils_v1 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
    tls_skip_verify: true  # Set to false if you have valid TLS certificate used by EDA.
    eda_username: "admin"
    eda_password: "eda-demo" # Change to your EDA password
  hosts:
    localhost:
      ansible_connection: "local"

Enjoy the automation:

with transactionsdirect CRUD operations

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:
        baseUrl: "{{ eda_api_url }}"
        clientSecret: "{{ client_secret }}"
        username: admin
        password: "{{ eda_password }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
      register: token

    - name: Create banner for leafs
      nokia.eda_siteinfo_v1alpha1.banner:
        baseUrl: "{{ eda_api_url }}"
        authToken: "Bearer {{ token.result.access_token }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        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:
        baseUrl: "{{ eda_api_url }}"
        authToken: "Bearer {{ token.result.access_token }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        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:
        baseUrl: "{{ eda_api_url }}"
        authToken: "Bearer {{ token.result.access_token }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        description: "Banners creation"
        dryRun: false
        detailLevel: "detailed"
        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:
        baseUrl: "{{ eda_api_url }}"
        authToken: "Bearer {{ token.result.access_token }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        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:
        baseUrl: "{{ eda_api_url }}"
        authToken: "Bearer {{ token.result.access_token }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        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:
        baseUrl: "{{ eda_api_url }}"
        clientSecret: "{{ client_secret }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        username: admin
        password: "{{ eda_password }}"
      register: token

    - name: Create interface
      nokia.eda_interfaces_v1alpha1.interface:
        baseUrl: "{{ eda_api_url }}"
        authToken: "Bearer {{ token.result.access_token }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        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
- fabrics¹ - 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:

requirements.txt formatpyproject.toml format

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:

Core collection to leverage EDA's Core APIs (like Transactions, User management, Alarms, etc.)
Utilities collection to assist with authentication handling, diff calculation, 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 Utils, Core, and Interfaces collections:

ansible-galaxy collection install nokia.eda_utils_v1 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 version information:

API Version

This refers to the specific application API version for which the collection is built. In EDA, applications may have several API versions (e.g., v1alpha1, v1, v2, and so on). The collection's name will include the API version; for example, the eda_interfaces_v1alpha1 collection 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.

Collection Version

This is the version of the Collection itself, which is independent from the Application API version. It follows the Semantic Versioning principles and indicates changes to the collection's functionality, compatibility, documentation, and more. The collection version is visible in the Ansible Galaxy UI.

In summary, for the collection with the name eda_interfaces_v1alpha1 and version 1.0.0:

the EDA application this collection is built for is Interfaces

the Interfaces API version is v1alpha1

and the collection version is 1.0.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 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 - 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 username and password parameters to the nokia.eda_utils_v1.get_token module.

Default value for both username and password parameters is admin.

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

Here is an example of how to get the client secret using the get_client_secret module:

- name: Get client secret from keycloak
  hosts: all
  gather_facts: false
  tasks:
    - name: Get client secret
      nokia.eda_utils_v1.get_client_secret:
        baseUrl: "{{ eda_api_url }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        # all other parameters are at their default values:
        # clientId: eda
        # keycloakUrl: /core/httpproxy/v1/keycloak/
        # keycloakAdminUsername: admin
        # keycloakAdminPassword: admin
        # keycloakMasterRealm: master
        # keycloakAdminClientId: admin-cli
        # realm: eda
      register: client_secret

With the obtained client secret, the get_token module can be used to get the authentication token needed by other modules:

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

    - name: Create banner for leafs
      nokia.eda_siteinfo_v1alpha1.banner:
        baseUrl: "{{ eda_api_url }}"
        authToken: "Bearer {{ token.result.access_token }}"
        tlsSkipVerify: "{{ tls_skip_verify }}"
        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

Note

Collections were generated for the apps released alongside EDA 25.12.1. Older releases may work with the current collections, but their compatibility is not guaranteed.

For Core API it is core and for Utility modules it is utils ↩