Defining Cisco ACI Observer jobs

The Cisco Application Centric Infrastructure (ACI) Observer is installed as part of the core installation procedure. You use the Cisco ACI Observer when you have a Cisco ACI environment with Cisco Application Policy Infrastructure Controller (APIC) in your environment. The Observer interfaces with Cisco APIC and makes active REST calls to Cisco APIC in the Cisco ACI environment. Using the Cisco ACI Observer, you can define jobs that dynamically load Cisco ACI data for analysis by Netcool Agile Service Manager.

Before you begin

Important: The Cisco ACI Observer supports the on-premise Cisco ACI version 4.1.

Ensure you have the Cisco ACI service details to hand, such as the Cisco APIC username, Cisco APIC password, Cisco APIC SSL TrustStore and Cisco APIC URL.

Remember: Swagger documentation for the observer is available at the following default location: https://<your host>/1.0/ciscoaci-observer/swagger

About this task

A Cisco ACI Observer job extracts Cisco ACI resources from Cisco APIC via REST. The Observer loads and updates the resources and their relationships within the Netcool Agile Service Manager core topology service.

ciscoaci_observer_common.sh: The configuration file you use to customize Cisco ACI Observer settings.; The parameters defined here are then used by the ciscoaci_observer_query_start.sh script to trigger the Cisco ACI Observer jobs.; Tip: Alternatively, you can set the appropriate environment variables. If an environment variable is set, it takes precedence over the configuration file settings.

You define and start the following jobs. You must edit the parameters in the configuration file before running this job.

Full Topology Upload job: A transient (one-off) job that loads all requested topology data.; This job is started by the ciscoaci_observer_query_start.sh script.

Listener: A long-running job that monitors its source for updates and runs until it is explicitly stopped, or until the Observer is stopped.; This job is started by the ciscoaci_observer_listen_start.sh script.

The Cisco ACI Observer loads the following Cisco ACI objects and their relationships into the Netcool Agile Service Manager core topology service:

Tenant Logical construct
(1) fvTenant
(2) fvAp
    A policy owner in the virtual fabric
(3) fvAEPg
    A set of requirements for the application-level EPG instance
(4) fvAEpP
    Abstract representation of an endpoint profile
(5) fvEpP
    An endpoint profile
(6) fvBD
    A bridge domain is a unique layer 2 forwarding domain that contains one or more subnets
(7) fvCtx
    The private layer 3 network context that belongs to a specific tenant or is shared
(8) vzBrCP
    A contract is a logical container for the subjects which relate to the filters that govern the rules for communication between endpoint groups (EPGs)
(9) vzOOBBrCP
    An out-of-band binary contract profile can only be provided by an out-of-band endpoint group and can only be consumed by the external prefix set
(10) vzSubj
    A subject is a sub-application running behind an endpoint group (for example, an Exchange server). A subject is parented by the contract, which can encapsulate multiple subjects
(11) vzFilter
    A filter policy is a group of resolvable filter entries
(12) fvSubnet
    A subnet defines the IP address range that can be used within the bridge domain
(13) fvRsCons
    The Consumer contract profile information and on Cisco ACI gui the option to create this object is via Consumed Contract. Used to build relationship between fvAEPg and vzBrCP
(14) fvRsBd
    A source relation to the bridge domain associated to this endpoint group. Used to build relationship between fvBD and fvAEPg
(15) fvRsCtx
    A source relation to a private layer 3 network context that either belongs to a specific tenant or is shared. Used to build relationship between fvBD and fvCtx
(16) vzRsSubjFiltAtt
    The filter for the subject of a service contract. Used to build relationship between vzSubj and vzFilter

Fabric Topology
(1) fabricInst
    A container object for fabric policies
(2) fabricNode
    The root node for the APIC
(3) polUni
    Represents policy definition or resolution universe
(4) firmwareRunning
    Information about leaf or spine switch firmware running on a node
(5) firmwareCtrlrRunning
    Information about each controller firmware that is running
(6) eqptLCSlot
    The slot for the module card
(7) eqptLC
    A line card (IO card) contains IO ports
(8) eqptPsuSlot
    The power supply slot
(9) eqptPsu
    The power supply unit
(10) eqptFtSlot
    A fan tray slot
(11) eqptFan
    The fan in a fan tray
(12) topSystem
    Used to retrieve fabric node Operational State
(13) cnwPhysIf
    The physical interface assigned to the node cluster
(14) l1PhysIf
    The object that represents the Layer 1 physical Ethernet interface information object
(15) mgmtMgmtIf
    The management interface
(16) lldpAdjEp
    The LLDP neighbors, which contains the information regarding the neighbors
(17) eqptRsIoPhysConf
    A source relation to an L1 Ethernet interface. Used to build relationship between l1PhysIf and eqptLC
(18) mgmtRsOoBStNode
    An object which contains management ip address of fabric spine switches and fabric leaf switches

Procedure

To edit the parameters in the configuration file

Open the ciscoaci_observer_common.sh configuration file and edit (at least) the following parameters:
ciscoapic_api_url

Cisco APIC REST API endpoint

ciscoapic_username

Cisco APIC user name for REST API

ciscoapic_password

Cisco APIC user password for REST API.

Supply the Cisco APIC user password in encrypted text.

ciscoapic_tenant_name

Cisco APIC tenant

Set to 'admin' if there is no specific tenant

Set to '' to load Fabric Topology resources

ssl_truststore_file

Cisco APIC SSL trust store file for HTTPS authentication

JKS is the supported format and the file is relative to $ASM_HOME/security

password_ssl_truststore_file

Password to decrypt and encrypt Cisco APIC SSL trust store file.

Supply Cisco APIC SSL trust store password in encrypted text.
Encryption requirement:
The Load and Listener jobs require passwords in encrypted form. To encrypt the ciscoapic_password and password_ssl_truststore_file, run the encrypt_password.sh script in the $ASM_HOME/bin directory:
./bin/encrypt_password.sh
Enter and then confirm the value. The encryption utility will return an encrypted version.

To acquire a Cisco APIC SSL certificate and build the SSL truststore

Use the following command to use OpenSSL to connect to Cisco APIC over port 443, and extract an SSL Certificate from Cisco APIC to a <certificate_file_name>.crt file.
```
echo -n | openssl s_client -connect {Cisco APIC IpAddress}:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ./{certificate_file_name}.crt
```

Use the following Java keytool command to import the Cisco APIC certificate file into a keystore and encrypt the keystore with a given password.

Draft comment: Seema.Deshpande@ibm.com
Keystore will still need encryption according to Dev. In the command below, it says that the password (for step 3 to encrypt the keystore) is a plain text password. Hence I haven't added that info again to the step.

keytool -import -v -trustcacerts -alias {Cisco APIC Hostname} -file {certificate_file_name}.crt -keystore {keystore file name} -storepass {your plain text password to encrypt keystore}

Tip: You will need the following encryption information when editing ciscoaci_observer_common.sh

Table 1. Encryption parameters required for `ciscoaci_observer_common.sh`
keystore parameter	`ciscoaci_observer_common.sh` parameter
keystore password	password_ssl_truststore_file
keystore file name	ssl_truststore_file

Copy the keystore file ({keystore file name}) to the $ASM_HOME/security directory to complete the SSL setup.

To start the Load and Listener jobs

To start the Cisco ACI Observer Full Topology Upload job, use the following command:
```
$ASM_HOME/bin/ciscoaci_observer_query_start.sh
```
This job loads all requested topology data. Run this job whenever you need Cisco ACI topology data refreshed.
To start the Cisco ACI Observer Listener job, use the following command:
```
$ASM_HOME/bin/ciscoaci_observer_listen_start.sh
```
This job monitors its source for updates and runs until it is explicitly stopped, or until the Observer is stopped.

What to do next

You can also use the following scripts:

ciscoaci_observer_query_stop.sh: Stops the Full Topology Upload job
ciscoaci_observer_listen_stop.sh: Stops the Listener job
ciscoaci_observer_job_list.sh: Lists the status of current jobs
ciscoaci_observer_log_level.sh: Sets the log level

Remember: As an alternative to being configured using the Observer Configuration UI, observer jobs have scripts to start and stop all available jobs, to list the status of a current job, and to set its logging levels. These scripts can be run with -h or --help to display help information, and with -v or --verbose to print out the details of the actions performed by the script, including the full cURL command. For the on-prem version of Agile Service Manager, observer scripts are configured for specific jobs by editing the script configuration files.