Transcription
Cisco Elastic Service Controller 5.5 Netconf API GuideUpdated: June, 2021
ContentsCISCO ELASTIC SERVICE CONTROLLER 5.5 NETCONF API GUIDE . 11INTRODUCTION . 51.1Using NETCONF API . 51.1.1 Get configuration . 51.1.2 Get non-configurable data . 51.1.3 Subscribe ESC notifications . 51.1.4 Make RPC calls . 51.1.5 Push in configurations . 51.2ESC esc nc cli script . 51.2.1 Show all available commands . 61.2.2 Get configuration . 61.2.3 Get non-configurable data . 61.2.4 Push in configurations . 61.3SSH RSA Key-based authentication for the esc nc cli script . 61.4ConfD CLI . 71.5Change ConfD Admin Password . 71.6NETCONF Protocol Operations . 71.7NETCONF Capabilities . 82ESC DATAMODEL . 113CONFIGURATION DATA . 113.1Reading Configuration Data . 113.1.1 Fetching all config data . 113.1.2 Example: Fetching deployed services by network name . 143.2Writing Configuration Data (CRUD operations) . 153.2.1 Stage 1: Acceptance or Rejection of a Configuration Request . 153.2.2 Stage 2: Activation of a new Configuration . 163.2.3 Configuration Workflows . 163.2.4 Combining Workflows . 16
4OPERATIONAL DATA . 184.1Reading Operational Data . 184.1.1 Fetching all operational data . 185CUSTOM RPC METHODS . 205.1serviceAction method . 205.2vmAction method . 206ESC WORKFLOWS USING NETCONF . 216.1Configuration Workflows . 216.1.1 Create Vim Connector . 216.1.2 Delete Vim Connector . 246.1.3 Update Vim Connector . 266.1.4 Create Vim User . 286.1.5 Delete Vim User . 316.1.6 Update Vim User . 336.1.7 Create Default Vim Connector . 356.1.8 Delete Default Vim Connector . 366.1.9 Create Tenant . 376.1.10 Delete Tenant . 416.1.11 Update Tenant . 426.1.12 Create Network . 446.1.13 Delete Network . 476.1.14 Create Subnet . 496.1.15 Delete Subnet . 516.1.16 Create Image . 536.1.17 Delete Image . 566.1.18 Create Flavor . 586.1.19 Delete Flavor . 616.1.20 Create Volume. 636.1.21 Delete Volume. 656.1.22 Create File Server . 676.1.23 Delete File Server . 686.1.24 Deploy Service . 696.1.25 Un-deploy Service. 766.1.26 Update Service . 796.1.27 Deploy Multi-vim Service . 866.1.28 Deploy Service with configuration files retrieved from remote server with authentication. . 916.2Operational Workflows . 946.2.1 Service Operations . 94
6.2.2VM operations . 1076.3ESC System API . 1196.3.1 Log API . 11977.1ESC TRIGGERED WORKFLOWS .120Auto Recovery (Auto Healing) Workflow . 1207.2Scale Out/Scale in Work Flows . 1227.2.1 Scale Out Work Flow . 1227.2.2 Scale In Work Flow . 1248IMPORT WORKFLOWS USING NETCONF .1258.1Import VM Configuration . 1258.1.1 Netconf Request . 1258.1.2 Netconf Response . 1268.2Finalize VM Import Configuration . 1278.2.1 Netconf Request . 1278.2.2 Netconf Response . 1278.3Delete VM Import Configuration. 1278.3.1 Netconf Request . 1278.3.2 Netconf Response . 1288.4Get VM Import Configuration . 1288.4.1 NetConf Request . 1288.4.2 Netconf Response . 128
1 IntroductionThe NETCONF API of ESC is to let the northbound clients communicate with ESC using the NETCONFprotocol.1.1 Using NETCONF APIESC’s NETCONF API can be accessed using any client that can communicate using the Netconf/YangProtocol. The easiest way to interact with the NETCONF Interface is using the Confd. ConfD provides apython based program called netconf-console that ships with ConfD. On any ESC VM, the netconfconsole is located in:/opt/cisco/esc/confd/bin/netconf-consoleThe Netconf API is hosted on port 830.The following operations below are supported by netconf-console, the examples presume/opt/cisco/esc/confd/bin is in the execution path:1.1.1Get configuration# netconf-console --user admin --password confd-password --port 830 --get-config -x "/esc datamodel"1.1.2Get non-configurable data# netconf-console --user admin --password confd-password --port 830 --get -x "/esc datamodel/opdata"1.1.3Subscribe ESC notifications# netconf-console --user admin --password confd-password --port 830 --create-subscription escEvent1.1.4Make RPC calls# netconf-console --user admin --password confd-password --rpc rpc.xml1.1.5Push in configurations# netconf-console --user admin --password confd-password --edit-config cfg.xml1.2 ESC esc nc cli scriptESC’s also provides a script which wraps the native netconf-console in an ESC functional specificmanner, providing a simple method to perform common tasks. This should be the preferred method tointeract with the NETCONF Interface, and is fully supported.
On any ESC VM, the esc nc cli script is locaed in /usr/bin, therefore will be in the executionpath of every operating system user.The esc nc cli script can be run by the admin operating system user without the sudorequirement.The following operations show a small subset of the common tasks which can be performed.NOTE: ConfD RPC calls cannot be directly made using this script: the netconf-console scriptshould be used for that purpose, as shown above.1.2.1Show all available commands# esc nc cli help1.2.2Get configuration# esc nc cli --user admin --password confd-password getconfig1.2.3Get non-configurable data# esc nc cli --user admin --password confd-password get1.2.4Push in configurations# esc nc cli --user admin --password confd-password editconfig cfg.xml1.3 SSH RSA Key-based authentication for the esc nc cli scriptThe examples above show esc nc cli script using user/password based authentication.Up to and including ESC 5.3, the operating system admin user has an SSH RSA key automaticallygenerated under it’s home directory: /home/admin/.ssh. It’s public key is stored in the ConfDdatabase authentication data against the ConfD admin user, and can be used in conjunction with amatching private key when validating access to the NETCONF API.By default, if a user and password are not presented to the esc nc cli script as parameters, thenauthentication would be RSA key based, using the admin user’s private RSA key (remember, the publickey was automatically stored within the ConfD database during ESC VM creation) and the ConfD adminuser.Therefore, the following is valid:# esc nc cli get-configGet Configured data
/opt/cisco/esc/confd/bin/netconf-console --port 830 --host 127.0.0.1 -user esc-nc-admin --privKeyFile /home/admin/.ssh/confd id rsa -privKeyType rsa --get-config -x "esc datamodel"the output following the command shows the private RSA key authentication.From ESC 5.4 onwards, the operating system admin user does not have an SSH key automaticallygenerated during ESC, therefore RSA key validation is not possible “out-of-the-box”.This can be enabled via the following post ESC VM creation command run as root:# escadm confd keygen --user adminThis will a) generate an RSA SSH key under /home/admin/.ssh and b) populate the ConfD databaseauthentication data with the public key.NOTE: No passphrase is required.1.4 ConfD CLIConfD has a CLI to enable user to read, write configurations and check operational data.The path of ConfD CLI in ESC is in:/opt/cisco/esc/confd/bin/confd cliNOTE: From ESC 5.4 and beyond, the confd cli command can only be executed by the root user, or auser with Linux sudo privileges, due to security hardening measures.1.5 Change ConfD Admin PasswordConfD admin Password can be changed using ConfD CLI.# sudo /opt/cisco/esc/confd/bin/confd cli-u adminadmin@host configureadmin@host% set aaa authentication users user adminpassword ESCt3st!234 (ESCt3st!234 is the new password)admin@host% commit1.6 NETCONF Protocol OperationsThis table captures what are the NETCONF Protocol Operations supported by n:baseTerminate this sessionYes
commit:base AND:candidateCommit the contents of the candidate/ configuration database Yesto the running/ configuration databasecopy-config:baseCopy a configuration databaseNocreatesubscription:notificationCreate a NETCONF notification subscriptionYesdelete-config:baseDelete a configuration databaseYesdiscardchanges:base AND:candidateClear all changes from the candidate/ configuration databaseand make it match the running/ configuration databaseNoedit-config:baseModify a configuration databaseYesget:baseRetrieve data from the running configuration database and/ordevice statisticsYesget-config:baseRetrieve data from the running configuration databaseYeskill-session:baseTerminate another sessionNolock:baseLock a configuration database so only my session can writeYesunlock:baseUnlock a configuration database so any session can writeYesvalidate:base AND:validateValidate the entire contents of a configuration databaseNo1.7 NETCONF CapabilitiesThis table captures what are the NETCONF capabilities supported by ESC.NameDescriptionSupported:candidateThe server supports the candidate/ database. It will allow this special database tobe locked, edited, saved, and unlocked. The server will also support the discardchanges and basic commit operations.No:confirmedcommitFor servers that support the :candidate capability, this additional capability will alsobe advertised if the server supports the 'confirmed commit' feature. This specialmode requires a server to send two commit RPC method requests instead ofone, to save any changes to the running/ database. If the second request doesNo
not arrive within a specified time interval, the server will automatically revert therunning configuration to the previous version.:interleaveThe server will accept rpc requests (besides close-session while notificationdelivery is active. The :notification capability must also be present if this capabilityis advertised.:notificationThe server supports the basic notification delivery mechanisms defined in RFC 5277, Yese.g., the create-subscription operation will be accepted by the server. Unless the:interleave capa
schemes (e.g., file, https, sftp) that the server supports within a particular URL value. The 'file' scheme allows for editable local configuration databases. The other schemes allow for remote storage of configuration databases. No :validate The server supports the validate operation. When this operation is requested on a
