Use the Programmable Installer

The Programmable Installer is a spec-driven automation platform for deploying and operating Cisco software stacks—including Network Services Orchestrator (NSO), Crosswork Network Controller (CNC), Crosswork Data Gateway (CDG), and Business Process Automation (BPA)—on enterprise Linux (RHEL family) and associated infrastructure where applicable (VMware vCenter, OpenShift, KVM, air-gapped Kubernetes). The system separates declarative intent (YAML specifications and optional guided intent generation) from execution (Ansible roles and playbooks), with a Python control plane that packages artifacts, verifies bundles before long-running installs, prepares encrypted secrets, and orchestrates validation gates.

This white paper explains the architectural layers, primary data flows, implementation patterns (including a hybrid data-driven artifact verification model), deployment modes (native, containerized, online, air-gapped), and the validation and logging frameworks. For delivery and platform organizations, the platform aims to reduce manual toil, surface misconfiguration and missing binaries early, and standardize automation across products and topologies while preserving environment-specific parameterization.

Keywords: infrastructure automation, declarative deployment, Ansible, YAML specification, air-gap packaging, artifact verification, Crosswork, NSO, CNC, CDG, BPA, validation policy, DevOps.

Enterprise installation of multi-tier network automation and orchestration products is traditionally high-touch: long runbooks, many manual steps, version skew between sites, and failures that surface hours into a process (missing NEDs, wrong OVA paths, incomplete air-gap image sets). That pattern increases cost, elongates change windows, and makes audits harder.

The Programmable Installer treats an installation as a program parameterized by a specification: topology, versions, platform choice (vCenter vs OpenShift vs vanilla VMs), file paths, and entitlements. Automation is idempotent where possible, repeatable across customers, and front-loaded with checks so that “not ready” is a fast, explicit outcome before cluster or product install.

• Declarative: Operators describe what must be deployed; playbooks implement how.
• Data-driven verification: Expected artifacts are derived from tables and rules rather than ad-hoc scripts per release, when patterns are stable.
• Policy-gated quality: Pre- and post-deployment validation runs under hierarchical policies, with structured reports and optional ticketing integration.
• Multi-modal operation: Interactive menus for first-time users; CLI and frozen binaries for CI/CD-style repetition; Docker-based flows for standardized runtime images.

1. Specifications express intent; they can reference paths and non-secret parameters. Secrets must flow through Ansible Vault workflows not plain-text spec fields where avoidable.
2. Artifact storage must be integrity-protected; verification focuses on presence and naming alignment with the spec—extend with organizational controls (checksums, signed bundles) where policy requires.
3. Installer-to-target SSH is a high-privilege path; compromise of the installer host is high impact. Hardening and access control are operational prerequisites.

1. Declarative first: User intent in YAML; automation interprets it consistently.
2. Separation of planning and execution: Python plans, verifies, and orchestrates gates; Ansible executes infrastructure and product steps.
3. Composable automation: Site-level playbooks import focused playbooks (preinstall, Kubernetes tracks, product installs).
4. Progressive disclosure: Interactive setup for onboarding; flags and scripts for advanced automation.
5. Same codebase, multiple runtimes: Native AlmaLinux/RHEL paths and Docker-based paths share one repository layout.
6. Explicit air-gap support: Package on a connected machine; transfer a bundle; install prerequisites and deploy without runtime dependency on public networks.

1. Package flow: The prerequisite tooling downloads or stages files into specific location, optionally producing a transferable tarball for offline installations.
2. Verify flow: The orchestrator parses the spec, resolves expected artifacts (including platform filters and entitlement lists), and reports ready / missing before install.
3. Deploy flow: Spec plus vault (and optional pre-validation) drive Ansible playbooks against inventories derived from the engagement.

Specifications are YAML documents describing platforms (for example vCenter, OCP, VM, KVM ), hosts, applications with versions, topology (for example NSO CFS/RFS layouts), entitlements (NEDs and add-on packages), and file paths for OVAs, qcow2 images, and application-tier tarballs.

A specific application user_spec supplies defaults and path fallbacks for CNC/CDG. The orchestrator’s parser treats the user spec as source of truth and uses common spec entries when user keys are absent.

The intent generator supports guided collection of requirements via set of questionnaire, a rule engine (date driven logic), and schema-backed mapping to intent.yaml. 

The orchestrator is the single entry for scripted or interactive generate-intent, verify-bundle, and install coordination. Its design is explicitly hybrid:

• ARTIFACT_DEFS: Declares artifact types and naming patterns per application (NSO installer, NED signed packages, optional packages; CNC OVA/qcow2/tier tarballs; CDG images; BPA charts and air-gap image tarballs).
• APP_CONFIG: Maps CLI --app values (nso, crossworksuite, bpa) to specification folder names and default intent filenames.
• Parser / Handlers: Resolve CNC/CDG paths using user spec and common spec; custom handlers cover non-uniform naming (for example TSDN/DLM) and BPA version formatting for chart and tarball paths.

Readiness:AReportaggregates discovered artifacts; is_readyis true when no required files are missing after spec parsing. The module supports PyInstaller-frozen binaries via sys.frozen path resolution.

This component provides interactive menus and CLI modes for artifact packaging and host prerequisite installation: online, air-gap, or auto-detect; multi-application packaging including combinedCNC_NSO. It populates the artifact tree expected by Ansible and by verify-bundle logic.

• Composition:  This illustrates the multi-track nature of the stack: it imports different Kubernetes bootstrap paths —reflecting that different products target different Kubernetes bootstrap paths.
• Roles (representative families): preinstall (SELinux, firewall, SSH, registry helpers), k8s_install / rke2, deploy_nso, deploy_cnc, deploy_cdg, deploy_bpa, postinstall, uninstall and certificate renewal helpers. Ownership and testing are best managed at role boundaries; nested task folders implement sub-workflows (for example NSO L3 HA).

The framework provides hierarchical policy control (global → app → stage → individual check), auto-discovery of checks, enhanced reporting to structured logs, and optional JIRA integration. Operators run pre- or post-deployment phases against the same spec used for install, aligning automation with quality gates suitable for enterprise change discipline.

Indicative scale on a typical branch: on the order of thirty checks across BPA and NSO (counts to be confirmed withmake list-validation-checkson your checkout).

Derives required vault variables from specs, prompts or accepts passwords under policy, and emits encrypted group_vars/all_secrets.yaml plus a vault password file for Ansible—reducing ad-hoc secret embedding in playbooks.

• Secrets:Prefer Ansible Vault encrypted group variables; use vault manager strict modes where appropriate.
• Installer host:Treat as a high-trust control plane; restrict access and monitor.
• Artifacts:Protect acquisition channels; organizational processes can augment verify-bundle with cryptographic verification.
• Logging:Application and Ansible logs underdeploy/logs/ 

Example pre-deployment invocation:

cd /opt/cx-installer
python3 validation_checks/run_validation_checks.py -t pre -s specification/your_spec.yaml

 This is a model for inner sourcing where for more CISCO application installation same principle can be followed by forking the repository. 

Quantitative metrics (install duration, defect rates) areorganization-specific; teams must baseline against legacy runbooks on comparable topologies.

1. ExtendARTIFACT_DEFS(and labels if needed) incx_deploy_orchestrator.py.
2. Add acustom handlerwhen naming cannot be captured by patterns alone.
3. Update packaging logic insetup_cxinstaller_prereqswhen downloads are automated.

Prefer new tasks inside cohesive roles; introduce new roles when boundaries are clear. Wire playbooks viaimport_playbookor documented entry playbooks. Keep safe defaults in group_vars / vars.

Update YAML schemas underintent-generator/schema/ and chatbot inputs; ensure generated files match filenames expected byAPP_CONFIG.

• Deeper SBOM or image signature verification integration.
• Expanded validation coverage for CNC/CDG scenarios.
• CI references for spec linting and Ansible syntax checks.

The CX Programmable Installer combines declarative specifications, a Python control plane for packaging and verification, and an Ansible automation plane for scalable, repeatable deployments of Crosswork-related products across diverse infrastructure and connectivity models. Its architecture intentionally separates intent from execution, applies data-driven artifact expectations where practical, and embeds validation and vault workflows suitable for enterprise delivery. For full operational annexes—playbook tables, troubleshooting matrices, connectivity matrices, and extended command references—see the companion internal white paper.

cx-installer/
├── ansible_playbooks/     # ansible.cfg, files/, group_vars/, playbooks/, roles/, vars/
├── apps/                  # App-specific supporting content
├── deploy/                # Python deploy helpers, logging utilities
├── docs/                  # Technical documentation
├── intent-generator/      # Chatbot, rule engine, schemas, output/
├── scripts/               # Docker setup/start, vault_secrets_manager.py, ...
├── specification/         # User specs, samples, common fragments
├── validation_checks/     # Policies, runners, reports
├── cx_deploy_orchestrator.py
├── setup_cxinstaller_prereqs*
├── requirements.txt
└── README.md

Post-setup artifact focal points (typical):ansible_playbooks/files/artifacts/, files/bin/, files/charts/, files/images/.

Script:cx_deploy_orchestrator.py

Environment (typical session):

export PYTHONPATH=$(pwd)
export ANSIBLE_CONFIG=$(pwd)/ansible_playbooks/ansible.cfg