Networking Shell Standard - Customizing a Shell in CloudShell 6.4

[Quali-Community]

Contents

1. Overview
2. Python packages structure
3. Customization guidelines – quick summary
4. Customization of an existing shell

Overview
Starting Feb 15th 2016, all networking Shells that are released from Quali’s engineering are according to the Networking Shell Standard. These Shells will be posted in Quali’s Download Center, in QualiSystems Git-hub and the Python packages the Shells are based on will be posted in PyPi.
The Networking Shell Standard definition can be found here - ?discussions_q=Networking-Shell-Standard
A Shell can be customized and expanded according to the Networking Shell Standard guidelines. It is also possible to create new networking Shells following the standard using a networking Shell template that will be provided in QualiSystems Git-hub. A great article which describes a GIT development model can be found here.
This document describes the procedures for customizing a networking Shell. There are separate guides for creating a new shell, certifying a model in an existing shell and debugging.

Python packages structure
See below a schema of the Quali’s Python package and their dependencies.

The actual implementation of the commands in the networking Shells is located in the “cloudshell-networking”, “cloudshell-networking-” and “cloudshell-networking--” python package. The logic in the “cloudshell-networking” includes the code that is generic to all networking devices, along with the structure and interfaces of a generic networking Shell. Any logic which is vendor specific is located in “cloudshell-networking-” and any logic which is OS specific is located in “cloudshell-networking--”.
The packages marked in purple are separate package that can be used by any python script, and the “cloudshell-virt-vcenter” is the vCenter App deployment option which will be released with 7.0.
Each of those packages has a version that follows Standard Versioning Guidelines (see details in http://semver.org), excluding cloudshell-automation-api has a version in the format of “CloudShell_version.X”, for example 7.0.X.

Customization guidelines – quick summary
When customizing an existing networking Shell or creating a new networking shell all the Networking Shell Standard definitions still apply.
Few points that should be considered:
• Don’t change the data model structure, names and rules. Use the generic families and models that come with the standard.
• Avoid adding attributes to sub-resources, add custom attributes only to the root model
• Don’t delete attributes. It is possible to adjust attributes rules if needed.
• Each shell should be per Vendor per OS and can be certified on specific models
• The “set attribute” functionality in which you change attributes values from CloudShell and apply them to the device isn’t supported. Such administrative activities should be done using a custom command.

Customization of an existing shell
Customization of an existing Shell can include addition of new commands, changes in existing commands or addition of attributes on the root level model (that will usually come with some changes in existing commands such as Autoload).

See below the customization flow:
1 – Create your copy of the repository
a. Find the Shell’s repository in QualiSystems Git-hub, for example the Cisco IOS Shell repository.
Note that all 6.4 content resides in 6.4 branch in each one of the repositories.
b. Fork the repository to QualiSystems Lab Git-hub or to your own profile page.

c. Optional – rename the new repository to make it clear that’s a customized/expanded version

d. Optional – update the “README.md” file with details about your repository. The content of this file will appear in the repository main page.

2 – Implement a new command
a. Navigate to the resource_drivers folder and open the file called _generic__resource_driver.py file. For example the “cisco_generic_ios_resource_driver.py”.

1. Add a new command in this format, after the definition of the Init function, for example:
   

MyCommand – replace with the function name
some-input – you can add multiple inputs to your function, just replace “some-input” with the input and if needed ad more inputs (comma separated)
‘ios’ – that’s the handler name, the text here should be according to the OS of the shell you’re expanding (). Read more about those handler in the device certification section.
b. Navigate to the folder (for example “ios”) and create a new file named __new.py file. For example “cisco_ios_new.py”. In this file fill in the following:

Replace CiscoIOSNew with the name you want to give to the new class, and CiscoIOS with the class that is defined in the “_.py” file that is located under the folder in the shell you’re expanding.
c. Under the folder (for example “ios”) open the file called init.py:

1. At the top of the script add the following:
   

Replace the “CiscoIOSNew” with the new class name you created in the previous step.
Replace the cloudshell.networking.cisco.ios.cisco_ios_new according to the new file you created in the previous step. It should be in the following format “cloudshell.networking...”.
2. Change the handler to point at the new class you created in step b:
replace this line:

with this line:

3 – Customize an existing command
a. Find the name of the function you want to override or extend – go to the “networking_generic_resource_driver.py” file in the cloudshell-networking repository, find the command name and copy its function name, for example for Save command the name of the function name is backup_configuration:

b. Open the _.py file under the folder (for example the “cisco_ios.py” file) and find the definition of the function with the name found in the previous step, for example in Cisco IOS’s Save command copy this line:

c. Follow step ‘b’ under “create a new command” and create a new __new.py file with the new class. Instead (or in addition) of adding the new command add the definition you copied in the previous step followed by the logic your own implementation of this command:

If you want to extend the new command and not override it do the following (call the implementation in the original class and then add your own logic).

If you want to alter the actual implementation of an existing command follow the “override” example and under “your logic here” just copy the implementation from the original class (for example from cisco_ios.py) and alter it as needed.

5 – Create the driver, update the data model and package the Shell
a. Download the Authoring project (under the root folder of the Shell’s repository there is a folder with the Authoring project, called__Shell_Authoring_Project).
b. Open the Authoring project in CloudShell Authoring.
c. In case you added a new command:

1. Copy the RunCustomCommand driver function to create a new function
2. Rename the copy according to your new command name
3. Open the PowerShell Call Function mini-canvas
4. Open Command4
5. Alter the command as follows:
   

Note that the MatrixJSON parameter actually holds all the information from the “reservation” and “resource” variables.
Replace SendCommand with the method name of your new command (the one you defined in step 2-a in the “customization of an existing shell” flow.
6. If there are additional inputs for your new command add them as follows – replace the command string with another variable (you should create a new variable in the Authoring project). If there are multiple inputs just add another one in the same format with a comma separator between them.

d. In case you overridden an existing command and changed the inputs

1. Open the command you altered.
2. Open the PowerShell Call Function mini-canvas
3. Open Command4
4. Add inputs following the same procedure described in 5-c-6.
   e. Save the project and re-load it to your GIT repository.
   f. Compile the driver. Rename the .dll file so it will have a different driver name than the original name of the driver.
   g. Navigate to the package folder (named __Shell_Package).
5. Take the .dll file you created in the previous step and load it to the Resource Drivers folder.
6. Open the datamodel.xml file under the DataModel folder
7. Go to the Switch family and rename the model from Switch to some unique name, for example Cisco IOS Switch Expanded
   
8. Associate the new driver you created with the model, under the Drivers section:
   
9. Repeat steps 3 and 4 for the Router family.
10. Optional - add attributes and associate them with the root models (the Switch model and the Router model).
    h. Download the whole package folder and zip it create the Quali package that can be loaded into CloudShell.
    i. Create a release with the zipped package attached to it. The version of the new release should be based on the original Shell version, with a new digit to refer to a customized version (for example Cisco IOS Shell 1.0.2.X):
11. 
12. 
13. 

6 – Share your customization
There are two levels for customization sharing. The first level is already completed once your repository:
• is public
• has a clear description in the README.md file
• has a versioned release with the zipped package attached
The second level is merging the customization with the original repository that is located in QualiSystems Git-hub. Not all customizations should be merged with the original repository. An example for a customization that should be merged is certification of new model that required some addition/adjustment to the Shell’s code.
Merging of code is done as a “pull request”. The merge is always between two branches, one in the originating repository (“base fork”) and the other in the new repository (“head fork”). To initiate a new pull request go to your repository and press the “Pull Request” button. Select the “base fork” and branch and the “head fork” and branch that you want to merge. There is an approval procedure you’ll need to go through to get the pull request approved – it will include adding tests to your code so the code coverage will be kept or improved, you’ll need to fix any bugs raised by our automatic tests and a code review by one of Quali’s engineers will be made.

 Attachments:

1.png [41KB]	2.png [34KB]	3.png [43KB]	4.png [11KB]	5.png [8KB]	6.png [2KB]	7.png [2KB]	8.png [2KB]	9.png [24KB]	10.png [11KB]	11.png [19KB]	12.png [20KB]	13.png [120KB]	14.png [144KB]	15.png [19KB]	16.png [6KB]	17.png [43KB]	18.png [27KB]	19.png [81KB]

---

 Alona Getzler (Alona.G) - 06/05/2016 11:55 AM

·  179  ·