1.0 Introduction

This document provides a technical analysis and recommended framework for integrating Cisco Network Services Orchestrator (NSO) with Ansible/AWX. Many organizations leverage both platforms: NSO for its robust, model-driven network service lifecycle management, and Ansible for its procedural, agentless automation capabilities across the IT stack. Without a clear architectural strategy, operating these tools in parallel can lead to configuration drift, operational silos, and conflicting sources of truth. The objective is to establish a cohesive strategy that harnesses the core strengths of each platform to create a unified, scalable, and reliable automation ecosystem.

2.0 Core Technical Challenge

The fundamental challenge is orchestrating network changes in a hybrid environment where both a declarative, model-driven tool (NSO) and a procedural, imperative tool (Ansible) are present. Key issues that arise include:

• State Management: NSO maintains a highly consistent state of the network in its Configuration Database (CDB) and can detect out-of-band changes. Direct device configuration by Ansible on NSO-managed devices breaks this model, causing check-sync discrepancies and undermining NSO’s transactional integrity.
• Conflicting Source of Truth (SoT): Uncoordinated use can lead to ambiguity regarding the true intended state of the network. Is the SoT defined in NSO’s service models or in Ansible’s inventory and playbooks?
• Operational Complexity: Operators are forced to use two different systems for related tasks, increasing the cognitive load and potential for human error. For example, provisioning a network service in NSO and then manually running an Ansible playbook to update a monitoring server is inefficient and prone to failure.

3.0 Recommended Architectural Framework and Integration Patterns

A successful integration hinges on a clear demarcation of roles. NSO should be positioned as the authoritative engine for network configuration and service state, while Ansible/AWX serves as a versatile workflow orchestrator and API client.

3.1 Principle of Demarcation

• Cisco NSO: The master of network configuration. Its responsibilities include network service lifecycle management (Create, Read, Update, Delete), maintaining transactional integrity, configuration validation, and acting as the definitive Source of Truth (SoT) for the network devices under its control.
• Ansible/AWX: The orchestrator of broader IT workflows. Its role is to automate procedural tasks, manage server configurations, and integrate various systems. In relation to NSO, it should act primarily as a northbound client, invoking NSO’s APIs to trigger network service changes.

3.2 Primary Integration Pattern: Ansible/AWX as the NSO API Client

This is the most robust and recommended pattern. The workflow is as follows:

1. A user, CI/CD pipeline, or other system initiates a request via AWX.
2. AWX launches an Ansible playbook.
3. The playbook gathers the necessary variables (e.g., customer name, VLAN ID, IP address) and constructs a structured data payload (JSON or XML).
4. Using Ansible’s uri module, the playbook makes a RESTCONF API call (POST, PUT, PATCH, DELETE) to the appropriate NSO service model endpoint.
5. NSO receives the API call, validates the request against the YANG service model, calculates the required device configuration changes, and deploys them within a single transaction. NSO handles the complex rollback logic if any part of the deployment fails.

Best Practice: This pattern centralizes network logic within NSO’s service models, while Ansible handles the user-facing interaction and workflow integration. This keeps playbooks simple and focused on API interaction rather than complex device-specific logic.

3.3 Secondary Integration Pattern: NSO Triggering Ansible Actions

In some scenarios, a network change provisioned by NSO must trigger a subsequent action in an external IT system (e.g., updating an IPAM, registering a new VM in a monitoring tool).

NSO can be configured to call an Ansible playbook via an action package or a Kicker that executes an external script upon a successful commit.

Best Practice with NSO 6.2+: For this pattern, it is critical to leverage the commit-queue async-post-actions feature. This allows NSO to trigger the external Ansible job asynchronously. The NSO commit queue is not blocked while waiting for the potentially long-running playbook to complete, thus preserving NSO’s performance and scalability for concurrent transactions.

4.0 Key Implementation Considerations

• Enforce NSO as the Network SoT: It must be an operational mandate that any device managed by NSO is configured only through NSO’s northbound APIs. Direct CLI/Ansible changes to these devices must be prohibited to prevent state desynchronization.
• Design Abstract Service Models: Develop NSO YANG service models that expose a simple, logical interface. This abstraction hides the underlying device-specific command complexity from the Ansible layer, making the service easy to consume.
• Secure Credential Management: Utilize the credential management features within AWX/Tower to securely store and inject the API credentials for NSO. Avoid storing plaintext passwords in playbooks or source control.
• Idempotency and Error Handling: NSO’s transactional nature simplifies playbook design. The Ansible playbook’s primary responsibility is to ensure the desired service state is communicated to NSO. NSO’s API will provide clear success (e.g., HTTP 201/204) or failure (e.g., HTTP 4xx/5xx) responses, which the playbook must be written to handle gracefully.

5.0 Conclusion

By establishing a clear architecture where Ansible/AWX acts as the workflow orchestrator and API client to a model-driven NSO core, organizations can effectively combine the strengths of both platforms. This hybrid approach designates NSO as the authoritative engine for network state while leveraging Ansible’s flexibility for broader IT integration. This strategy mitigates the risks of a fragmented toolchain and builds a robust, scalable, and maintainable network automation fabric.