network engineering guide - gluware®support.gluenetworks.com/glulab/.../neteng_guide... · this...

Network Engineering Guide

Version 2.7-R1 (draft)

July 8, 2016

Copyright © 2016 Glue Networks, Inc. All rights reserved.

ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS (COLLECTIVELY, "INFORMATION") IN THIS DOCUMENT ARE PRESENTED "AS IS," WITH ALL FAULTS. GLUE NETWORKS AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL GLUE NETWORKS OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST OF PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THE INFORMATION, EVEN IF GLUE NETWORKS OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Gluware, the stylized "[g]uware" logo and the stylized "[g]" logo are registered trademarks of Glue Networks and/or its affiliates in the United States and certain other countries. Any other trademarks mentioned in this document are the property of their respective owners.

Reproduction in whole or in part in any form without prior written permission is prohibited. Glue Networks believes the information contained herein to be accurate as of the publication date; such information is subject to change without notice.

Glue Networks, Inc. 2020 L Street, Suite 130 Sacramento, CA 95811

Phone: 916.877.8224 Web: www.GlueNetworks.com/

Network Engineering Guide i

Contents

INTRODUCTION ............................................................................................................................................. 1

1. About This Document ........................................................................................................................... 1

2. Audience ............................................................................................................................................... 1

3. Document Conventions ........................................................................................................................ 2

4. Product Dependencies .......................................................................................................................... 2

4.1 Third-Party Software Dependencies ............................................................................................... 2

4.1.1 Control ..................................................................................................................................... 2

4.1.2 Lab ............................................................................................................................................ 2

5. Contacting Glue Networks .................................................................................................................... 3

5.1 Internet ........................................................................................................................................... 3

5.2 Technical Support ........................................................................................................................... 3

6. Professional Services ............................................................................................................................. 3

7. Documentation ..................................................................................................................................... 3

Capability Development & Export ................................................................................................................ 4

8. What is a Networking Capability? ......................................................................................................... 4

9. Capability Design Workflow .................................................................................................................. 4

10. Formulas.............................................................................................................................................. 5

10.1 Structure ....................................................................................................................................... 5

10.2 Formula Examples ......................................................................................................................... 9

10.2.1 Basic Connection .................................................................................................................. 10

10.2.2 Modular connection ............................................................................................................. 10

10.2.3 Modular JNIB ........................................................................................................................ 12

10.2.4 Validation JNIB ..................................................................................................................... 14

11. Config Data ........................................................................................................................................ 15

11.1 Structure ..................................................................................................................................... 16

11.1.1 Primitive Types ..................................................................................................................... 16

11.1.2 Container Types ................................................................................................................... 16

12. FLOW ................................................................................................................................................. 16

12.1 Structure ..................................................................................................................................... 17

12.1.1 Scalar .................................................................................................................................... 17

12.1.1.1 @String: ........................................................................................................................ 18

Network Engineering Guide ii

12.1.1.2 @Required!: .................................................................................................................. 18

12.1.1.3 @Enum:......................................................................................................................... 19

12.1.1.4 @Number:..................................................................................................................... 19

12.1.2 Array ..................................................................................................................................... 20

12.1.3 Object Structure ................................................................................................................... 20

12.1.3.1 @Complete.options ...................................................................................................... 20

12.1.3.2 @Select.options ............................................................................................................ 20

12.1.3.3 @Choice.options ........................................................................................................... 20

12.1.3.4 @Complete.allType ....................................................................................................... 21

12.1.4 Ref ........................................................................................................................................ 21

12.1.4.1 <reference>@TypeRef: ................................................................................................. 21

12.1.4.2 <property>@Ref : "<reference>":................................................................................. 21

12.1.5 Display .................................................................................................................................. 22

12.1.5.1 @Display.label .............................................................................................................. 22

12.1.5.2 @Display.tab ................................................................................................................. 22

12.2 FLOW Examples ........................................................................................................................... 22

12.2.1 Classes in a QoS Policy map ................................................................................................. 23

12.2.1.1 FLOW type Structure ..................................................................................................... 24

12.2.1.2 FLOW UI panel .............................................................................................................. 25

12.2.1.3 Config Data .................................................................................................................... 26

12.2.2 Choosing a QoS Policy .......................................................................................................... 26


12.2.2.2 FLOW UI panel .............................................................................................................. 27

12.2.2.3 Config Data .................................................................................................................... 27

12.2.3 Policy specific properties ..................................................................................................... 28


12.2.3.2 FLOW UI panel .............................................................................................................. 30

12.2.3.3 Config Data .................................................................................................................... 30

13. Lab Run Configuration for capabilities .............................................................................................. 32

14. Exporting capabilities from Lab......................................................................................................... 33

Feature Development & Publishing ............................................................................................................ 34

15. Creating a Network Feature .............................................................................................................. 34

15.1 Anatomy of a Feature ................................................................................................................. 34

15.2 File Location ................................................................................................................................ 36

15.3 Using the Start Object ................................................................................................................. 36

Network Engineering Guide iii

15.4 Understanding the NDK .............................................................................................................. 37

15.4.1 Object-oriented Approach ................................................................................................... 37

15.4.2 NDK Class Location ............................................................................................................... 37

15.4.3 NDK Class Examples and How They Function ...................................................................... 38

15.4.4 Dealing with CLI structure with entries................................................................................ 39

15.4.5 Object Naming Convention .................................................................................................. 40

15.4.6 Object Store ......................................................................................................................... 41

15.4.7 Feature Runtime Engine (FRE) ............................................................................................. 42

15.4.8 Coding a Declarative Feature Example ................................................................................ 42

15.4.8.1 Modeling A10 Networks ACOS Server Load-Balancing slb Network feature................ 42

15.5 Feature Semantic Engine ............................................................................................................ 45

15.6 Adding a Vendor Network Concept ............................................................................................ 45

15.6.1 Create an NDK Class ............................................................................................................. 45

15.6.2 Using the NDK Class ............................................................................................................. 47

15.6.3 Create a CLI Model ............................................................................................................... 47

16. Lab Run Configuration for Features .................................................................................................. 51

17. Packages and Publishing in Control .................................................................................................. 52

17.1 Packages ...................................................................................................................................... 52

17.1.1 Creating Packages ................................................................................................................ 52

Network Engineering Guide 1

INTRODUCTION

1. About This Document

Glue Networks provides two interactive solutions for the automation of network lifecycle management actions, Gluware Lab and Gluware Control:

The Gluware Lab Integrated Development Environment (IDE) that focuses primarily on networking capability Initial and Optimized Design focused actions;

The Gluware Control Configuration Automation Engine that focuses primarily on network capability Deployment and Management focused activities.

This guide focuses on Gluware Lab network capability design and validation.

2. Audience

This purpose of this guide is to enable a Network Engineer that has some familiarity with scripting, or a Developer with some familiarity with networking, to develop a networking capability to be tested, validated, and inevitably imported into Gluware Control.

Figure I-1.

Some of these actions occur at the network level (IP Addressing schemes, Branch policies, inclusion of Voice, etc.), and the manifestations of these network choices as well as many other configuration details are manually configured on the network devices themselves (interfaces, routing choices, VLANs, etc.).

The solutions from Glue Networks are focused on automating the orchestration and implementation of a range of configuration actions in all of the described network lifecycle phases, with integrated scalability and testability in each phase.


3. Document Conventions

For the purposes of this and related documentation from Glue Networks, a networking feature refers to a configuration-oriented action applied to either a single or a group of networking devices.

Network devices go through a series of phases throughout their lifetime – between purchase and end of life. Similarly, networks built using these networking devices go through a lifecycle of their own, which is illustrated below; Initial and Optimization Design (and validation), and Deploy and Management oriented activities. There are a range of network configuration actions involved in each of these lifecycle phases – which can be categorized further as "green field" (i.e., the Initial Design and Deploy phases), and "brown field" (i.e., the Optimized Design and Manage phases).

4. Product Dependencies

This section provides information about product dependencies and compatibility. It includes the following sections:

Third-Party Software Dependencies

4.1 Third-Party Software Dependencies

The following summarizes the third-party dependencies of Gluware 2.7.

4.1.1 Control

NGINX. NGINX (pronounced "Engine X") is a free, open-source, high-performance HTTP server and reverse proxy, as well as an IMAP/POP3 proxy server. It can act as a reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and an HTTP cache.

Node.js. Node.js is an open-source, cross-platform, JavaScript runtime environment, built on Chrome's V8 JavaScript engine, for developing server-side Web applications.

RabbitMQ. RabbitMQ is an open source message-queueing server software implementation of AMQP (Advanced Message Queueing Protocol), also known as message broker or queue manager software.

RADIUS. Remote Authentication Dial-In User Service (RADIUS) is a client/server networking protocol and software that enables centralized Authentication, Authorization, and Accounting (AAA or Triple A) management. Remote access servers communicate with a central server to authenticate dial-in users and authorize access for users who connect and use a requested system or network service.

VMware Workstation Player (formerly known as Player Pro), or VMware Workstation, or VMware Fusion Pro. VMware is a virtualization and cloud computing software for x86-compatible computers. VMware virtualization is based on the ESX/ESXi bare metal hypervisor, supporting virtual machines.

4.1.2 Lab

Java Platform, Standard Edition 8 (Java SE 8), 64-bit. Java SE lets you develop and deploy Java applications on desktops and servers. The JDK (Java SE Development Kit) includes the JRE (Java Runtime Environment), so you do not have to download both separately.


5. Contacting Glue Networks

This section describes how to contact departments within Glue Networks.

5.1 Internet

You can learn about Glue Networks products at http://www.GlueNetworks.com

5.2 Technical Support

We are here to deliver the support and service you need to get the most from your Glue product investment. If support from Glue Networks for Gluware is needed, please contact the Service Delivery team by sending an email to [email protected]

Alternatively, call Glue SD Toll Free +1 855 458 3822 in the United States and Canada, 0808 134 9906 in the United Kingdom, and 0800 0232194 in the Netherlands.

You can also go to http://www.GlueNetworks.com/Support

6. Professional Services

Glue Networks has a staff of professionals who can help you with installation, provisioning, project management, custom designs, project design, and custom solutions. To contact Glue Networks professional services, email [email protected] or go to http://www.GlueNetworks.com

7. Documentation

The Glue Networks Technical Publications team strives for continual refinement and improvement in the quality and usability of Glue Networks documentation. We update regularly this document and, if you have any comments, suggestions, or information that you believe we should include, please contact the Glue Networks Technical Publications team. We appreciate your positive comments and requests for improvements. You can always submit any comments and suggestions that you might have about our documentation or printed materials. Send documentation comments to [email protected].


CAPABILITY DEVELOPMENT & EXPORT

This section of the Guide focuses on the creation, use, testing, and export of basic capabilities between Gluware Lab and Control. When imported into Gluware Control, these capabilities become Custom Scripts and they operate as single use networking capabilities applied to individual Nodes. This is not the recommended level of development from Glue Networks, but it does allow a new Gluware developer to familiarize themselves with the core concepts and create and exercise capabilities quickly and easily.

The next section on creation, use, testing and publishing of Features will illustrate the recommended development approach for Gluware based networking Features, which build on the fundamental structures and concepts covered in the rest of this first section.

8. What is a Networking Capability?

A networking capability includes a single or a group of functions that address a business need in a network or networking device. Examples of networking capabilities include Cisco specific feature support (like PfR and other iWAN features), and broader networking functions (like QoS policies and classes).

9. Capability Design Workflow

Gluware Lab networking capabilities are constructed in the following four consecutive steps:

the business action/logic is described in the form of a Formula,

the configuration data structure that needs to be created/read/updated/deleted is captured in Gluware’s Flexible Language Object Workstream (FLOW),

the Configuration Data for this particular instance of the data structure is described, and

all of the above is configured and tested in a controlled Lab environment to confirm that the capability works.

The file extension that is used to identify Formulas is *.jnib (i.e., Java Network Intelligent Bit), and it will be further described in upcoming sections of this Guide. The file extension for the FLOW data structure is *.jtype. The instance status that will populate the data structure for the intended action uses the file extension *.json (Java Script Object Notation).

The final step in creating the networking capability involves populating the FLOW data structure with the Config Data as the Formula is implemented on a lab network device.

The following examples put these concepts into a familiar networking engineering context.

Figure 9-1.


10. Formulas

As mentioned previously, the Formula is the intended action of the networking capability.

Within the Formula, the business action is realized via the following structural elements. The Formula essentially describes the connection to a networking device, the details of the capability that need to be investigated or acted upon, any programmatic structure or logic, dependent functions and/or structures

10.1 Structure

The structure of Gluware Lab networking capabilities is based on common industry programming principles and standards – primarily JavaScript and JSON. That said, if the basics of JavaScript and JSON are not familiar to the user of this Guide, most of the fundamentals can be found in the examples, or in any Java Script reference material.

A brief description (along with an example of the syntax) of each of the core structural elements will be provided below, followed by examples using these elements in familiar networking engineering scenarios.

The following diagram summarizes the required and optional components of Formulas, which are then described in the sections that follow.

Figure 10-1.


The key characteristics of a Formula are that:

It is a JavaScript object, which is essentially a JSON object that includes one or multiple functions (i.e., actions) as well as JSON structured data. If the Formula provides the entry point of execution, it must include an initial function run (i.e., run()), which describes the intended action of the overall Formula. It is possible to link and refer to external JNIBs (i.e., loadNib()) that provide incremental capabilities and functionality in a modular and scalable manner. This Global Function will be described in later sections of this Guide.

Code Sample 10-1.

run : function() { <intended action of the Formula> },

If applicable, a Formula will have a StartObject (i.e. getStartObj() ) to collect any necessary details and/or data from related JSON files as the Formula begins execution. An example would be connection specific details for the network device, or group of devices, that are being accessed by the Formula.

As the Modular Connection example illustrates later in this section, the StartObject is specified as the Formula is executed. This can be in the form of multiple JSON files merged together to create the single StartObject. Once it has been specified, the most common means of accessing the StartObject data is by using the global function getStartObj() followed by the desired properties of the StartObject that the Formula will need.

Code Sample 10-2.

run : function {

var new data = getStartObj().desired_data;

}


Similarly, if there is output expected from the Formula action, it will be stored in the FinishObject (i.e., getFinishObj() ) which is returned to the system executing the Formula. An example of this would be the results of a CLI "show" command, which would then be stored to use later. For example, the output of one Formula can be used as part of a StartObject of another Formula executing later in time. FinishObject is a JavaScript object that can be amended to by Formula developers, but cannot be replaced or deleted.

Code Sample 10-3.

run : function {

var result = getFinishObj().result _data;

}

It will automatically generate a completion state once execution has finished for the Formula. This completion state is one component of the FinishObject. There are four potential completion states for a Formula:

Success (Green)

Success with Warnings (Yellow)

Abort with Errors (Red)

User Intervention – Kill State

Success states are automatically generated by the Gluware Lab system. Abort codes are defined and integrated into the Formula by the Formula developers, with their own custom conditions and codes that are available in the FinishObject.

Code Sample 10-4.

if (test === expectedvalue) {

return; //value.

} else {

abort(007, "The value : "+test+", doesn't match the expected value:

"+expectedvalue);

}

User intervention is a state that is entered when a user terminates the Formula before it has completed execution. This completion state is also automatically included in the FinishObject and involves no additional Formula development logic to be created.

It supports logging capabilities that convey progress and status of the intended action. While executing, Formulas automatically provide two levels of logging – detailed and summary. The detail log includes all five levels of log details described below, as well as the StartObject and FinishObject. The summary log includes only level 2-5 log details. Both levels of reports are captured for every Formula action, and the


following options can be specified within a Formula to customize the level of logging displayed and/or captured at any point in the Formula’s execution:

Log.debug : development level details

Log.info : operations/user level details

Log.checkpoint : similar to info, milestone details

Log.task : nested levels of summary details

Log.warning : status indicators

Note

Use of log.warning automatically changes the completion state of the Formula from Success to Success with Warnings...

Code Sample 10-5.

run : function {

log.debug("Starting Formula");

},

It supports a CommandObject (i.e., cmd), which enables the remote execution of a set of CLI commands on the network device (or group of devices) that the Formula is acting on. These network devices can be Cisco, Juniper, Riverbed, etc. network devices.

An initial list of supported commands is listed below:

inactivity()

connect()

send()

getSendResponseStr()

getSendResponseMatch()

disconnect()

Code Sample 10-6.

run : function {

var cmd = new cmd(…);

cmd.connect();

cmd.send("show version");

},


It supports the ability to reference other Formulas to allow modular and scalable Formula design of networking capabilities using the Loadnib() global method.

Code Sample 10-7.

aclMgr : loadNIB("examples/acl_operations.jnib"),

run : function {

thisNib.aclMgr.function(…);

},

10.2 Formula Examples

The following examples illustrate the structures outlined above in typical network engineering scenarios. The initial examples will be self-contained (including the batch file to be used with the runJNIB command line utility, and any necessary Formula and/or JSON files), and only focus on inspecting and acting on a remote network device with static data found in either the Formula or the associated JSON files.

Examples including interactive use of user-inputted data will follow once the JTYPE structure has been illustrated. The runJNIB utility is integrated in future versions of Gluware Lab as the Run/Console execution utility. Further details of how to execute Formulas in Gluware lab are available on the support site and in Gluware Lab embedded support; however, the general capabilities are the same as runJNIB depicted below.


10.2.1 Basic Connection

This example illustrates how to make a connection to a network device and run a show command on that remote device (in this case the "show version" command). The key concepts are highlighted in blue.

Figure 10-2.

10.2.2 Modular connection

This example illustrates JSON setup file support (StartObject). In this example it is being used to abstract the connection details for the network device (or devices) being accessed within the Formula. Once again, the key concepts are illustrated in blue.

The StartObject needs to be referenced as the Formula is being initialized, the StartObject itself needs to be a JS structured Object format (i.e., starting and ending in { }), and then the global function StartObject can be used to access the connection initialization details in this example.


Figure 10-3.


10.2.3 Modular JNIB

This example will illustrate the use of multiple JSON files that are merged into a single StartObject to provide the setup details for the Formula as it begins execution. It also includes a FinishObject that collects execution details from the Formula during execution, and uses loadNIB() (another Global Function) to access modular external functions used by the Formula.

Figure 10-4.


Figure 10-5.


10.2.4 Validation JNIB

This example will illustrate logging for progress indications, multiple remote commands to execute on a network device, next hop networking details, and a built in timeout exception if the connection with the device is lost. This example also introduces the exit() Global Method.

If the connection to the network device is lost, then the logging reflects a warning and the exit() global method is invoked to interrupt the Formula execution. If not, the logging mechanism reports the progress, the remote commands are executed on the network device, and the Formula completes successfully.

Figure 10-6.


Figure 10-7.

11. Config Data

Network configuration management data includes a wide variety of details, which often change across different network configurations and different network devices and models. Java Script Object Notation (JSON) provides an extremely flexible and adaptable means of capturing and representing these different configuration details and associated dependencies.

JSON is not network specific, not even configuration specific, but its flexibility accommodates the creation of network and configuration specific constructs that enable efficient and timely Formula development. The basic JSON structures are described in the following section, followed by details of the configuration Flexible Language Object Workstream (FLOW) structures that are based on JSON and used extensively with Formulas.


11.1 Structure

The structure of Gluware Lab networking capabilities is based on common industry programming principles and standards – primarily JavaScript and JSON. That said, if the basics of JavaScript and JSON are not familiar to the user of this Guide, most of the fundamentals can be found in any JavaScript Reference materials.

The following is a review of the relevant core JSON Types: Primitives and Containers.

11.1.1 Primitive Types

String – " "

Number – 0

Boolean – false

Null

11.1.2 Container Types

Object – { }

Array – [ ]

These types are the basic data constructs of the range of networking configuration objects, which are then combined with the FLOW structures defined below to add testability and a more structured approach to capturing and storing configuration details.

12. FLOW

Formulas enable automation of network configurations, and FLOW enables integrated validation and testability for the configuration data, and provides a unique means of representing structure and data entry for the end user that is using or inputting the configuration data. To reiterate, there are two primary functions served by FLOW structural elements -

Validating data that is referenced by Formulas, and

Specifying the format that data is used by or entered by end users.


Figure 12-1.

FLOW (JTYPEs) can be thought of as falling into one of two primary categories based on their focus.

Programmatic focused:

Basic – that are used to structure JSON primitive types, and

Array – that are used to structure JSON arrays (i.e., one kind of Containers)

Ref – that are used to reference existing JTYPE/JSON structures.

UI panel based:

Object Structure – that organize multiple object properties for input and viewing by Gluware Control users, and

Display – that helps organize the display of JSON data.

There is currently one other type of FLOW that can be both programmatic and UI Panel focused , called Compound, which combines multiple other FLOW types.

Each of the supported FLOW types are described in the Structure section and then illustrated in the Examples section that follows.

12.1 Structure

12.1.1 Scalar

The Basic set of FLOW types serve the purpose of validation and testability of configuration data that is closely coupled to Formula development and execution. The set covers:

bounds applied to a subset of JSON Primitives (@String and @Number),

a fixed set of values that are based on JSON Primitives (@Enum), and

a designation for any required properties of any kind in a JSON Object (@Required).


12.1.1.1 @String:

This property can only be the primitive type String and includes the following potential constraints.

Min – the minimum number of characters allowed in this object property;

Max – the maximum number of characters allowed for this object property;

Pattern – a character pattern that this object property must adhere to;

Validator –

Note

The Pattern constraint is a Regular Expression, and adheres to the properties and purposes of Java Script Regular Expressions. This Guide does not include further details of Regular Expressions, as there are many resources and publications that cover this topic.

12.1.1.2 @Required!:

This property can be specified as any JSON type, and when invoked, this property must be populated in this Object and must conform to the described JSON type.

Code Sample 12-1.

{ "name@Required!" : "",

}

This example defines a required property of the object designated "name", which is a string with no initial value included.


12.1.1.3 @Enum:

This property can be specified as any JSON Primitive type (String, Number, Boolean, Null), and includes the list of valid values that can be assigned to the property.

Code Sample 12-2.

{

"state" : {

"active@Enum" : [true, false],

}

}

This example defines a property of the JSON Object "state", designated as "active", that is a primitive type Boolean which can have the value of either true or false.

12.1.1.4 @Number:

This property can only be the primitive type Number and includes the following potential constraints.

A range that bounds the input value for the property with min and max entries.

An OnlyInteger Boolean attribute that allows any numeric value if it is false, and only Integer values if it is true.

An excludeList attribute that includes a list of numeric property values that are not allowed as valid inputs for this object property.

Code Sample 12-3.

{

"testScale@Number" : {min: 0, max: 10,

onlyInteger: true, excludeList: [3]}, "testScale" : 4

}

This example defines a primitive JSON type Number designated as "testScale" that:

is in the range of 0-10,

can only accept an input that is an Integer,

cannot have the value 3, and

has a default initial value of 4.

Any property input value that does not meet the described constraints is not allowed and generates a warning flag in the UI Panel of the FLOW.


12.1.2 Array

There are two FLOW types associated with Arrays –

One that supports the Java Script Array container type, and

One that supports the container type and an identified object property that will be used to organize the contents of the Array.

12.1.3 Object Structure

In particular, the Object Structure FLOW types are best understood by seeing them used in context – including the structures, the forms they create, and the JSON data that is rendered. A brief description of each is included below, followed by examples that use them in a networking context.

There are four Object Structure FLOW types:

@Complete.options

@Select.options

@Choice.options

@Complete.allType

12.1.3.1 @Complete.options

If the need is to add one to a limited number of properties to an existing Object – and they can be any of a list of completely different property types, then Complete_options is the FLOW type to use. The additional property can be a JSON primitive, a JSON Container, or a Container of any mix of Containers or Primitives.

This object structure provides a list of properties in a selection menu, and as each property is populated with data, that field is removed from the selection menu. Any remaining properties can then be selected and populated until all the object properties have been populated and the selection menu is empty. The maximum number of properties in this object is the number of initial options defined.

12.1.3.2 @Select.options

If the need is to add a single property to an existing Object – and it can be any of a list of completely different property types, then Select_options is the FLOW type to use. The additional property can be a JSON primitive, a JSON Container, or a Container of any mix of Containers or Primitives.

This object structure allows a single set of properties be populated based on a single prior menu selection from the initial menu options.

12.1.3.3 @Choice.options

If the need is to add any number of properties to an existing Object – and each of them can be of a completely different property type, then Choice_options is the FLOW type to use. The additional properties can be a JSON primitive, a JSON Container, or a Container of any mix of Containers or Primitives.

This object structure allows multiple sets of properties to be populated based on one to multiple menu selections from the initial menu options.


12.1.3.4 @Complete.allType

If the need is to add any number of properties to an existing Object – and they are all of the same property type, then Complete_allType is the FLOW type to use.

The additional properties can be a JSON primitive, a JSON Container, or a Container of any mix of Containers or Primitives.

All additional object structures added after this JSON object is defined must conform to this JSON structure.

12.1.4 Ref

There are two FLOW types associated with Refs –

One that is used to reference other type information (either in the same file location using the @TypeDef syntax, or found in other FLOW files – using file locations), and

One that is used to declare other JSON instance references.

12.1.4.1 <reference>@TypeRef:

This FLOW type avoids unnecessary copying or retyping of repetitive/reused data structures. The property structure that will be reused can either be declared before its first reference (using the @TypeDef reference), or its alternative location can be declared (similar to how the LoadJnib() structure identifies external Formulas that can be used with/in a Formula).

Code Sample 12-4.

WIP -

example@TypeDef : { }

example@TypeRef : { }

12.1.4.2 <property>@Ref : "<reference>":

This FLOW type identifies JSON files to be used with the identified property. Again, like the LoadNib, and @TypeRef structures allow access to and use of external Formulas and FLOW types respectively, @Ref allows access to and use of external JSON files with local FLOW types(s).

Code Sample 12-5.

property1@Ref : "location1"

property2@Ref : ["location1", "location2", "location-n"]


Note

When there are multiple locations in the @Ref reference (like the array example above), the @ref structure is used to indicate the selected location within the @Ref array.

12.1.5 Display

12.1.5.1 @Display.label

This FLOW type allows a form based description for the associated object properties that is placed in a separate line in the current form.

12.1.5.2 @Display.tab

This FLOW type allows a form based grouping of multiple object properties of a networking configuration. The tab provides a new form page in the current configuration on which a group of properties is located.

12.2 FLOW Examples

The following examples will utilize the different FLOW types to capture/organize network device configuration settings for familiar networking features.

Each example will:

describe the actual FLOW JavaScript definitions, followed by

the input/edit UI panels that are generated by them in Gluware Lab, followed by

the Config Data object that is created by the structure and the populated form.

As there is often more than one FLOW type included in examples, the different types are called out as being either Forms or Programmatic focused.


12.2.1 Classes in a QoS Policy map

In a QoS policy, there can be a range of defined classes – a classic 5, 8, or 11 Class model as examples.

Figure 12-1.

Each class in the selected policy model contains roughly the same set of details/properties. If the number of classes is optional, identifying the # of classes in a policy and populating this type of configuration data is aligned to the use of the Complete.allType FLOW type structure.

UI panels

As illustrated below, the Complete.allType object structure is best suited for capturing and/or reviewing these configuration details. This example also illustrates the use of the @Display.label Display FLOW type or allowing a form based description for the associated object properties.

Programmatic

The @Enum and @Number Basic FLOW types are also included in this example to further structure the QoS configuration data.


12.2.1.1 FLOW type Structure

There are three different object properties defined for each class (illustrated below), and three unique labels defined for use in the accompanying input form. This allows for efficient data structure naming conventions at the same time as providing user-friendly descriptions in the forms.

Figure 12-2.


12.2.1.2 FLOW UI panel

For this example, the policy map name of Qos_pmap_Acme was used and two classes were created for this policy. As mentioned previously, the object property structure for each class is the same – i.e., includes classname, bandwidthtype, and bandwidth properties. The selections for each class are represented by pull down menus in the associated form(s) and form elements. Adding an additional class to the policy is done by selecting the (+) button at the bottom of the form and deleting an existing class or the policy map itself is achieved by selecting the appropriate (X) button. There are currently no means of confirming deletion or addition provided in Gluware Lab.

Figure 12-3.


12.2.1.3 Config Data

The following JSON data was generated from the forms input reflected above – a policy map with two class instances populated based on the entries or settings selected in the FLOW UI panel.

Figure 12-4.

12.2.2 Choosing a QoS Policy

If there are a finite number of known options to choose from, for instance choosing from one of three standard 5, 8, or 11 class QoS policies, then this is aligned to the use of the Complete.options FLOW type structure. After one of the menu options has been selected (and in some cases the Config Data populated), any additional options are made from the remaining selections in the original list. For this example, after the 5 class policy model was selected, a further selection (using the (+) button) would only have the 8 class and 11 class options from which to choose.


Forms

This example uses the Complete.options and Display.label FLOW types


Figure 12-5. FLOW type Structure


Figure 12-6. FLOW UI Panel



Figure 12-7. Config Data

12.2.3 Policy specific properties

In some situations’ a single option needs to be chosen, but depending on which choice is made, different additional information needs to be collected as well. Building on the previous example, if a choice needs to be made between a 5 class and 8 class policy, but once one of the two is chosen, the names of each class need to be customized or use a default class name, then this usage is aligned with the Select.options FLOW type.


As illustrated in the example below, there are two options for the classnames object (5 of 8 class QoS policy), and depending on the option chosen, a different set of additional properties to collect in the FLOW UI panel.


Figure 12-8.



The form for the Select.options FLOW type reflects the set of options (5 or 8 class QoS policy), and once one of them is selected, the options to customize the individual class names are provided, with a default naming of the classic class names for each policy.

Figure 12-9.


The Select.options FLOW type has captured the classnames property selection of a 5 class policy, and captured all of the class name selections, which in this example include two custom entries for class 3 and class 4.

Figure 12-10.

Note

The last Object Structure FLOW type (Choice.options) is very similar to the Select.options in structure and usage – with one specific difference in how the object property name is handled. If the Choice.options FLOW type had been


used in the current example, the classnames property would have taken on the property value of the option selected (5 class) as illustrated below.

Figure 12-11.


13. Lab Run Configuration for capabilities

Once the Formula/FLOW/Config Data for a capability under development has been completed, the next step in its development using the Gluware Lab environment is to Run it in the integrated Console execution environment.

Figure 13-1.

Whether accessed in the Gluware Lab menu bar "Run" option or by right clicking on the JNIB file in the project Explorer and selecting "Run As", the first step in execution is to select Run Configurations … This will bring up the Configuration form depicted below. Once the Formula file and any appropriate Start Object files have been specified, and the Run Type of default is selected, the selections are applied and the Formula is run. If the Console View is not already open, this will open the Console View, where the details and results of the Formula being executed are reflected.


14. Exporting capabilities from Lab

Gluware Lab includes the Export button depicted with the blue background and arrow below: Figure 14-1.

Once selected, the following configuration panel is opened and the user chooses source and destination details for the export operation Figure 14-2.

These include the Project and Org within the Project the user will export Formulas and Flow from, and which Gluware Control system and Org they are exporting the Formulas and Flows to. Once these selections have been made, pressing the OK button initiates the export operation. The user will then need to log into the specified Control system to complete the importing process and use the Formulas and Flows they have created in the Custom Scripts portion of the Action Panel. Further details of these activities can be found on the Gluware Control support site found at the following link: http://support.gluenetworks.com/glucontrol/.

http://support.gluenetworks.com/glucontrol/


FEATURE DEVELOPMENT & PUBLISHING

15. Creating a Network Feature

15.1 Anatomy of a Feature

A network feature is a networking functionality that runs on a device such as firewalling, QoS, routing... Where a configuration has always seen as a monolithic block of CLI text before, the feature approach in Gluware allows network engineers or developers to see the target device as a container of several network features. The feature concept applies to both any devices whether they are CLI-based or REST-based. In Gluware, the concept of node assembly is how service chaining of network features is applied against the target device. Network features can have dependencies on required data or other features to have run before them. For instance, the routing feature requires the interfaces to be numbered first, or the QoS feature needs the associated policy details in order to be processed. There are two ways to write a feature. First, like the examples shown in the first section of this Guide, is writing it so that Gluware sends the raw CLI to the target device. This would be keeping the same traditional imperative method used for sending configurations to remote endpoints. That CLI can be hardcoded into the code. This requires the network engineer to perform several tasks: conceiving the desired CLI code, and making sure the CLI code is compatible with the target device (vendor, platform, operating system version, existing configuration...). If the target platforms for the feature are different, then the CLI code will have to be modified for each platform type accordingly. Once this type of feature capability has been created, the details of exporting it to Control are described at the end of the previous section of the Guide. The second way to write a feature is leveraging the object-oriented network scripting language available in Gluware Lab, which is covered in this section. The scripting language allows network engineers and developers to teach the engine on how the feature runs. For instance, you create a RouteMap or an IpAcl object; that teaches the engine how these objects have to be written with regard to CLI. In order to do that, Gluware needs to understand what a RouteMap or an IpAcl are. This is where the Dynamic NDK comes into play. Each network concept like an ACL, a route map, an interface can be modeled in details using the Gluware FLOW language. Each modeled network concept is called an NDK class. Gluware Lab integrates extensive examples on how to write an NDK class. An NDK class includes the properties describing the object and the methods applicable to that object. As a result, a feature is a script manipulating all these objects modeled in the NDK class library. The chapter adding a vendor network concept explains these concepts further and includes examples on how to onboard a network concept that needs to be automated. Once the NDK classes exist, a feature is a collection of objects created and manipulated with these NDK classes. If an NDK class is a directly modeling of a network concept that can be rendered on the target device, it is generally associated with a CLI model. A CLI model teaches Gluware what is the resulting CLI syntax so rendering a given network concept. As a result, by handling NDK objects in a feature, Gluware understands the network concepts involved and will automatically render the CLI accordingly at runtime. Gluware ships with a semantic engine that


includes several vendors and manufacturers operating systems such as Cisco IOS/IOS XE, Riverbed RiOS, Palo Alto PANOS, Fortinet FortiOS, F5 BIG-IP (tmsh), and Juniper JunOS. Check for Glue Networks support website to add support for additional certified CLI-based vendors. The semantic engine also guides Gluware to understand what is already configured in the target device. As a result, and based on the model, Gluware might opt to add, amend, ignore or delete the existing configuration on the target device. This makes Gluware a powerful tool for mitigating unauthorized changes (like changes not in the model) or to rapidly redeploy a device in an RMA or disaster recovery situation. The other benefit of using the NDK objects is the declarative versus the imperative approach. This allows the network engineer/developer to focus on what he wants to see in the target configuration and not worry about the existing state of the target endpoint. Indeed, Gluware will automatically perform the garbage collection of all the items that are not in the reference model. Having said that, it is however possible to configure Gluware to leave items that are not in the model (so not performing the garbage collection). This is useful when dealing with transitions when not everything has been modeled yet! A declarative feature includes five files: the feature declaration file (FLOW) and four code files (feature, manager, renderer, and discovery). The feature declaration file contains all the settings of the feature in order for Gluware to understand how to run that feature: what type of node is it applicable to, if there are dependencies on other features that need to run first, dependencies on configuration domain or feature data. This will be explained in details in the Using the Start Object and Feature Runtime Engine (FRE) chapters. The feature code file includes the main entry points for Gluware to execute the feature. Entries points are functions that Gluware runs depending on the operation performed on the target device. For instance, run() is the entry point for a regular provisioning, deleteNode() is the entry point for a delete operation on a node or preview() is the entry point for previewing what’s going to happen without performing any changes on the target endpoint. The manager code file includes the network business logic. This is where the feature is modeled using the NDK objects. For instance, in order to model a policy-based routing feature on Cisco IOS, the manager will include objects for route-maps, access-lists, and interfaces. For instance, in order to model a server load-balancing feature on A10 Networks ACOS, the manager will include objects for servers, service-groups, and virtual-servers. The discovery code file includes the logic that Gluware needs to read an existing configuration on a target endpoint prior to altering it. This allows Gluware to push only the necessary changes to a target endpoint. The rendering code file includes the rendering logic. This is where the model is turned into CLI at runtime. Out of these four code files, only two needs to be understood in order to write a feature: the feature and the manager code files. The feature code file needs to include the list of the NDK classes that are used and relevant to the feature. The manager code included the network business logic using these NDK classes. The rendering and discovery codes files should remain untouched. When advanced rendering is required, having access to the rendering and discovery code files allow to extend the capabilities of the default rendering in Gluware.


Once a feature has been created, the feature “package” can then be published for later importing into Gluware Control as described at the end of this section of the Guide.

15.2 File Location

When designing a feature, it is important to understand the location of each section. Here is a quick reminder on how organizations are handled within Gluware. The top organization is sys. This is a system-wide organization. Every item in the sys organization can be seen in any other organization. The sys organization can be found in the /sys tree structure. Any other custom organizations are in the /org tree structure. When an object exists in both the /sys and /org tree structures, the object in /org is preferred over the /sys object. When a reference link to objects in a custom organization is missing, Gluware will fall back in looking up the object in the /sys tree structure. The feature files are located in the following directories: - /src/sys/jnib/features which contains a single directory per feature, each directory including all the

code files for a given feature - /src/sys/type/construct/feature which contains all the feature declaration files (one per feature).

15.3 Using the Start Object

A feature is a model of the networking concept that is applicable to a target endpoint (also called node). That model can be fed with multiple dynamic data. That dynamic data can be user inputs, data stored somewhere, etc. In a regular development environment, when developers require access to data, several complex techniques are required to retrieve the necessary data: accessing a relational or non-relational database, accessing a file system. This is time consuming and requires domain specific knowledge on how to perform these actions. Using Gluware, this operation is very simple. When building a feature, the required data to run that feature are declared in the feature declaration file (written in FLOW). This feeds the Feature Runtime Engine (FRE) to retrieve automatically the relevant dynamic data from Gluware backend system without any knowledge or understanding of a database/file system. At runtime, the FRE builds a JSON object called the feature start object (startObj) that includes all the dynamic data necessary to run the feature. For instance, if the feature has user input, that data will be automatically included in the start object. For instance, if the feature has some dependencies on domains, the data of the relevant domains will be included in the start object. The following example shows how the sample feature needs the site relevant domain data; the site being some user input data relevant to a site such as a datacenter or a branch. {

"@Info": {

...

"domainDependencies": {

...

"/sys/type/construct/domain/site.jtype": {}

...

}

When running a feature, the start object can be retrieved using the following method: var startObj = getStartObj();

The variable startObj contains the feature start object in a JSON format.


But because the feature start object can be big (because if includes all the data relevant to a node for a given feature at runtime), there are some methods that helps digging into the start object. For instance, when running a feature, the feature data can be retrieved using the following method:

var featureData = getFeatureInstanceData();

The variable featureData is now a JSON object including only the feature data typically captured with at the user input. For instance, if node belongs to various domains, the following function retrieves all the domain data relevant to the feature for that node:

node.importDomainConstructs(getStartObj());

The node variable now includes a property called domains that contains all the various domain data.

15.4 Understanding the NDK

15.4.1 Object-oriented Approach

The NDK is a collection of programming classes used to model a network concept. Like a traditional programming class, a NDK class has a constructor, properties, and methods.

The class represents the overall concept where the objects are the instances of a class. For instance, let us use a Person class that models a person:

var dan = new Person();

var john = new Person();

var jake = new Person();

Person is the class where Dan, John, and Jake are objects.

A constructor is the method that is called when creating/instantiating the object for the first time.

The properties are the fields that are specific to the object. For instance, firstName, lastName, DOB are possible fields for a Person class.

The methods are the functions that are applicable to the objects. For instance:

john.sleep();

jake.walk();

dan.run();

sleep(), walk() and run() are methods application to any object of Person class.

15.4.2 NDK Class Location

The NDK classes are usually located in the following directory:


/src/sys/jnib/lib/classes/<vendor_name>

or (for a class only accessible for a given organization)

/src/org/<orgnanization_name>/jnib/lib/classes/<vendor_name>

15.4.3 NDK Class Examples and How They Function

Let us look at the NDK class modeling the A10 Networks ACOS server network concept:

// A10 Server NDKClass

fields: {

"name@String": {},

"rip": {},

"[email protected]": ["Ipv4Subnet"],

"services": {},

"[email protected]": true,

"[email protected]": ["IpPort"]

},

initialize: function(name) {

this.setName(name);

}

The properties are in the fields section of the NDK class. The server class has three fields: name, rip, and services. The name field is a string. The rip field is an object of Ipv4Subnet class. The services field is an object of objects of IpPort class.

Let us create an object of "server" class named "myName":

var member = new Server("myName");

The variable member is now an object of "server" class type.

In order to instantiate the name property of member, the following methods can be used:

member.name = "myName";

or

member.setName("myName"); // preferred way

Gluware NDK engine will respond to both ways. Any property within a NDK class will have default associated methods called the synthetic methods. Gluware NDK engine will understand these methods when called. There is no need to code these methods unless they need to be overloaded (see Create an NDK Class in the Adding a Vendor Network Concept chapter).


In order to instantiate the rip property of member, the following methods can be used:

member.rip = myRealIpAddress;

or

member.linkRip(myRealIpAddress); // preferred way

where myRealIpAddress is an object of Ipv4Subnet class type.

In order to instantiate the services property of member, the following methods can be used:

member.services[myTcpPort]= myTcpPort;

or

member.addService(myTcpPort); // preferred way

where myTcpPort is an object of IpPort class type.

Gluware NDK engine will automatically perform a validation of the object against the NDK class and will

abort and error out if the validation fails. For instance, if the object myTcpPort is not of IpPort class type, Gluware will abort. If the object myTcpPort is of IpPort class type but has some properties that includes other objects that failed their respective validations (against their associated classes), Gluware will also abort. Gluware will traverse recursively all the objects (within objects) until a full validation is performed. That significantly reduces the amount of code required to perform data validation. For instance, in the previous example where trying to add myTcpPort object into the

services properties, if the myTcpPort object of IpPort class type has a port property defined as:

"port@Number": { "min": 0, "max": 65535, "onlyInteger": true }

... and equal to 70000, Gluware will abort as it tried to validate the myTcpPort object against the IpPort class and failed.

15.4.4 Dealing with CLI structure with entries

Some CLI structure includes entries such as Cisco access-lists or route-maps, Fortinet firewall policies or routing objects as shows below.

Cisco IOS route-map:

route-map rmap-ipv4-sites-outbound deny 10

match tag 9999

route-map rmap-ipv4-sites-outbound permit 20

match ip address prefix-list plist-ipv4-sites-local

set tag 240


In the Cisco structure, the route-map has two entries. Each entry has its own property.

Fortinet FortiOS firewall policy:

config firewall policy

edit 2

set uuid f87e1b26-3d45-51e6-52a8-50640825939c

set srcintf "port1"

set dstintf "any"

set srcaddr "address_1234"

set dstaddr "address_test_1111"

set action accept

set schedule "always"

set service "myFirewallServiceGroup"

next

edit 3

set uuid f8fb4b14-3d45-51e6-2fee-e9f37acc0d8a

set srcintf "port1"

set dstintf "port2"

set srcaddr "all"

set dstaddr "address_4568"

set schedule "always"

set service "httpService"

set logtraffic disable

next

end

In this Fortinet example, the firewall policy has two entries, each of them with their own properties.

The annotation @entryMap allows facilitating handling network concepts with entries and defining associated properties and methods applied to these entries.

15.4.5 Object Naming Convention

Each object that has a name property is very likely to be the name of the CLI-rendered object. For instance, in Cisco IOS, let create an access-list acl-test:

var myAcl = new IpAcl(IPV4, IpAcl.EXTENDED, "acl-test");

When rendering the myAcl object, the generated CLI will be:

ip access-list extended acl-test

When dealing with several network features on a single target endpoint, it is important to differentiate the objects for each feature.


For instance, in a typical Cisco IOS configuration, there can be access-list used in routing, security, policy-based routing, or quality of service (QoS). Using different naming conventions in each feature avoids mixing the access-list items.

A naming convention is expressed using regular expressions (regex). A regex expression is a succession of characters defining a search pattern. Using naming convention is not mandatory but highly recommended.

Using a specific naming convention per feature ensures that Gluware understands the objects that it can alter or delete from the target device. For instance, if all the access-list of the routing feature are named using the acl-routing-.+ regex, Gluware will intervene on the access-lists that is following that convention when processing the routing feature. As a result, there is no risk in touching the access-lists of other features that are using a different naming convention.

15.4.6 Object Store

Each NodeClass object (node) includes two stores: a system store and an object store. The system store includes all the settings for an associated object store. Each store needs to be initialized. This is done automatically at the creation of the node.

To submit an NDK object to the Gluware semantic and rendering engine (SRE), it has to be posted to the object store. The object store is expecting to receive any NDK object as far as the associated NDK class has been declared previously. As part of the declaration, each NDK class associates a naming convention and a feature tag.

For instance, in order to declare the IpAcl class for the firewall feature using the /acl-firewall-.+/ naming convention, use the following call:

node.declare(IpAcl, "firewall", /acl-firewall-.+/);

Then, any IpAcl object can be store in the object store for the firewall feature. If the IpAcl object name does not match the naming convention, the object is rejected.

The following example shows how an IpAcl object is added to the object store of node for the firewall feature:

var acl = new IpAcl(IPV4, IpAcl.EXTENDED, "acl-firewall-test");

node.store(acl, "firewall");

Note: each object that is submitted to the object store will be validated. In other words, Gluware will check the object against the associated NDK class prior to accepting it. It the validation fails, the object is rejected. This ensures that all the objects within the store are valid: expected values of the primitives, expected structure, and so on.

Note: when invoking the store function, the reference to the object is stored. As a result, even when the object is altered later in the code, the object in the store is automatically updated. As a result, it does no matter when an object is added to the store.


The object store also supports a fetching mechanism allowing the network engineer or developer to retrieve by its name a previously stored object, as shown in the following example:

node.fetch(IpAcl, "acl-firewall-test");

If the IpAcl object exists, the fetch function will return a reference to the object. So altering the object will impact the object in the store. If the IpAcl object does not exist, the fetch function returns undefined.

15.4.7 Feature Runtime Engine (FRE)

The Gluware feature runtime engine (FRE) is responsible to the execution of the network features. Each node is associated to an assembly in order to perform service chaining of network features. At runtime, the FRE will resolve all the references to achieve two important steps. First step is to determine in what order the network features need to be run. Features have dependencies: some features require to run before the execution of another feature, features have domain dependencies, and so on. Once the order determined, the FRE launches each feature one by one. Second step is to build the start object for the node, prior to running each feature. The start object is assembled at that time by resolving all the references. For more details, read the "Use the Start Object" section.

If the FRE cannot resolve all the references, either configuration data is missing or configuration data have missing references to their associated FLOW models, the FRE aborts.

Each feature has a feature declaration file (written in FLOW). That file declares the following references:

- The feature entry point: a reference to the JNIB file that includes the action methods: o run(): the method call when a node provisioning is triggered o preview(): the method called when a preview is triggered o deleteNode(): when a delete node action is triggered

- The list of features that are required to have run initially - The list of domains required - The node dependency

15.4.8 Coding a Declarative Feature Example

15.4.8.1 Modeling A10 Networks ACOS Server Load-Balancing slb Network feature

A feature includes five files: the feature declaration file (FLOW) and four code files (feature, manager, renderer, and discovery).

Let review the target CLI to generate:

slb server S1 20.20.20.51

port 21 tcp

!

slb server S3 20.20.20.53

port 21 tcp

!

slb service-group sg-tcp21-1 tcp

member S1 21


member S3 21

priority 15

!

slb virtual-server VIP1 10.10.10.101

port 21 tcp

service-group sg-tcp21-1

Three network concepts can be found in this CLI configuration: servers, service-groups, and virtual-servers. Each concept renders straight from the CLI root level and can been configured independently from one another. So let us create three NDK classes with a CLI model for each of the classes: Server, ServiceGroup, and VirtualServer.

// Server NDK Class

fields: {

"name@String": {},

"rip": {},


"services": {},



},


this.setName(name);

},

methods: {

setRip: function(rip) {

this.linkRip(new Ipv4Subnet(rip));

}

}

// ServiceGroup NDK Class

fields: {

"name@String": { "min": 1, "max": 127 },

"ipPort": {},

"[email protected]": ["IpPort"],

"@JS.entryMap": {

"start@Number" : { "min": 1, "max": 65534, "onlyInteger":

true },

"start": 1,

"increment@Number" : { "min": 1, "max": 65534,

"onlyInteger": true },

"increment": 1,

"classSuffix": "Member",

"classFields": {

"members": {},


"[email protected]": ["Server"],


"priority@Number": { "min": 1, "max": 16,


"enable": false

}

}

},

initialize: function(name, port) {

this.setName(name);

this.linkIpPort(port);

},

methods: {

setIpPort: function(protocol, port) {

switch (protocol) {

case IpProtocol.TCP:

case IpProtocol.UDP:

this.linkIpPort(new IpPort(protocol, port));

break;

default:

abort(-11, "FATAL: Invalid protocol for

setIpPort() for ServiceGroup NDK Class (expecting tcp or udp)");

break;

}

}

}

// VirtualServer NDK Class

fields: {

"name@String": { "min": 1, "max": 127 },

"vip": {},


"@JS.entryMap": {

"start@Number" : { "min": 1, "max": 65534, "onlyInteger":

true },

"start": 1,

"increment@Number" : { "min": 1, "max": 65534,


"increment": 1,

"classSuffix": "Port",

"classFields": {

"ipPort": {},

"[email protected]": ["IpPort"],

"serviceGroup": {},

"[email protected]": ["ServiceGroup"],

"enable": false

}

}

},


this.setName(name);


},

methods: {

setVip: function(vip) {

this.linkVip(new Ipv4Subnet(vip));

}

}

15.5 Feature Semantic Engine

The Feature Semantic Engine (FSE) is responsible for rendering each NDK object that has been posted in the node object store. The FSE will be executed after each feature manager. So if a node has an assembly performing a ten-feature service chain, the FSE will be run ten times.

When an NDK class is associated with a CLI model, the FSE will render each object of that class when found in a node object store. Using that CLI model, the FSE will generate the CLI commands to be sent to the node. The FSE will also understand which part of the CLI commands are keywords and values. As a result, the FSE will capture what is already sent in the target node and will only sent the CLI commands required to reach the goal. The FSE will also crawl the node to remove all the CLI commands that are not supposed to "be there."

In order for Gluware to understand the CLI structure of each vendor, Gluware ships with vendor specific knowledge packages called Vendor Specific Extensions (VSEs). Before rendering on a specific device, make sure the Gluware engine has the proper VSEs installed.

In order to understand which CLI model to use, the FSE relies on the osOption object associated with the node (in either node.shell.osOption or node.cmd.osOption properties whether previewing is enabled or not). Based on osOption properties, the FSE will choose the correct vendor (like Cisco, Arista, Fortinet...), the correct operating system (like IOS, EOS, FortiOS...), and optionally le version running.

15.6 Adding a Vendor Network Concept

15.6.1 Create an NDK Class

The NDK class comprises of four sections:

- fields (mandatory) The fields section is a FLOW model of the NDK class. It includes all the properties of the class from primitives to objects.

o If the property is a number or string primitive, the dynamic method calls available will be prefixed by set... unset... and get... that represents the actions applicable to the property. For instance, if the property name is test, the following methods are available:

setTest(), unsetTest() and getTest(). o If the property is a Boolean primitive, the dynamic method calls available will be prefixed by

enable... and disable... which represents the actions applicable to the property. For instance, if the property name is test, the following methods are available: enableTest() and disableTest().

o If the property is an object, the dynamic method calls available will be prefixed by link... unlink... and get... which represents the actions applicable to the property. For instance,


if the property name is test, the following methods are available: linkTest(),

unlinkTest() and getTest(). o If the property is an object of objects or an array of objects, the dynamic method calls

available will be prefixed by add... remove... get...Items that represents the actions applicable to the property. If the property name is a plural noun, the method will only use the singular noun. For instance, if the property name is tests, the following methods are available: addTest(), removeTest() and getTestItems().

- methods (optional) The methods section includes all the optional methods for the class. If a method has the exact name of a dynamic method (as highlighted in the fields section), the method will supersede the dynamic method.

o initialize (optional) The initialize section is the constructor of the class. Use that method to define the behavior of the constructor for the class.

o nibLoaded (optional) This section is used to define methods outside the namespace of the class. Advanced users only should use this section.

The Dynamic NDK engine understands the following annotations:

o @JS.classes This annotation specifies the accepted object that can be assigned to the property. Before handling the object against the property, the object will be validated against its associated FLOW model if any. The annotation accepts an array of strings. For instance, the following example defines the property test as an IpAcl object:

"[email protected]" : [ "IpAcl" ]

o @JS.method This annotation specifies the methods associated to the property to either rename a dynamic function or assign a different name to it.

o @JS.method.nameSuffix This annotation specifies the suffix of the dynamic methods. For instance, if the property

name is test and expecting primitives, the dynamic methods are setTest(), unsetTest(), and getTest(),. If the name suffix is set to "glass," the dynamic methods associated to that property are now setGlass(), unsetGlass(), and getGlass().

o @JS.method.<action>.name When the default synthetic method name needs to be overloaded -- in other words, renamed, or changed -- this annotation specifies the new name for the associated action. For instance, if the selected action is "link," the following statement will replace the default linking method by the new method name processThat(): "[email protected]": "processThat"

o @JS.objectMap


Use his annotation when a property contains more than one object. The property will be an object of objects.

Example with the Server NDK Class

// A10 Server NDK Class

fields: {

"name@String": {},

"rip": {},


"services": {},



},


this.setName(name);

},

methods: {

setRip: function(rip) {

this.linkRip(new Ipv4Subnet(rip));

}

}

In this example, the Server class has two properties: rip and services. The rip property is an object of Ipv4Subnet type. The services property is an object of IpPort objects. The following dynamic methods are available: linkRip(), unlinkRip(), getRip(), addService(),

removeService(), and getServiceItems(). The class has a constructor (initialize method) and has one additional method setRip().

15.6.2 Using the NDK Class

When designing a feature, methods can be applied to any object whether methods are user defined or dynamic. The following example shows how a Server object is created and methods are applied to it:

var server = new Server("myServer");

server.linkRip(new Ipv4Subnet("1.2.3.4");

var port = new IpPort("tcp", 8080);

server.addService(port);

server.setRip("1.2.3.4");

Any NDK method will automatically drop a debugging line in the execution log to facilitate the tracking of each step of the networking model.

15.6.3 Create a CLI Model


The CLI model helps the Gluware rendering engine to generate the correct syntax for the target CLI output. It is also used by the rendering engine to read the existing configuration from the target device. As a result, the Gluware compare engine that includes the semantic rules for the target device will only send the required changes to get the desired configuration onto the target device.

The "META-DATA" section includes all the signaling to feed the Gluware compare engine: flagging Boolean values, identifying the key value… The following section shows the FLOW model for the META-DATA:

"META-DATA" : {

"nameId@String" : { "pattern": "\\$[a-zA-Z0-9\.-_]+" },

"key@String" : { "pattern": "\\$[a-zA-Z0-9\.-_]+" },

"boolProperties" : [],

"multiWordProperties" : [],

"ignoreLines" : {

"from" : []

},

"exitLines" : [],

"rootEntryFlag" : false,

"ignoreFromConfigMatch" : false,

"indentDefinesLevel" : false,

"confirmCommands" : [{

"confirmCommand" : "",

"confirmResponse" : "",

"autoReturn" : false

}]

}

- The nameId property defines the name that is used as the key of the CLI command. - The key property defines the key value of the CLI command,

- The boolProperties property defines an array of all the properties of Boolean type, - The multiWordProperties property defines that includes a succession of multiple values

following a keyword. For instance, dns-server 1.1.1.1 2.2.2.2 3.3.3.3 where dns-

server is the keyword. - The ignoreLines property is an object of multiple subproperties such as "from" that is an array

of regular expressions of all the CLI lines that will be ignored by the Gluware compare engine when retrieving the CLI lines from the target device.

- The exitLines property defines an array of regular expressions that are used for exiting a CLI subsection. For instance "exit-af-topology" in a Cisco dynamic routing AF section.

- The rootEntryFlag property defines that the CLI command in the model will not have any sublevels and only commands are the root level.

- The identDefinesLevel Boolean property defines that the indentation of the command is exactly defining the sublevel of the CLI commands. For instance, two spaces in front of a command defines that this CLI command is at two sublevels from the root level.

- The confirmCommands is an array of multiple objects. Each object defines how the Gluware CLI engine will treat questions coming its way when dealing with the CLI flow. The optional autoReturn property allows the Gluware engine to follow automatically a response with a carriage return.


Note that the nameId or key properties cannot be used simultaneously. Both properties cannot contain any space character.

Any property in the CLI model is prefixed with $context. followed by the property name path. If the property is an array, the [*] indicates to crawl the property. Each CLI line is defined as a key in the CLI model. The value side is used to control the carriage return behavior. Depending on the syntax use in the value, the resulting CLI will land all the items of the array on the same line, or write as many lines as there are items in the array. In order to create as many lines as there are items in the array, "<cr>" is used

For instance:

port $context.nb $context.protocol : "<cr>"

… defines a port command line with two values. The "<cr>" defined as the value will add a carriage return once the port command is written. As a result, a possible CLI command would be:

port 21 tcp

For instance:

port $context.services[*].nb $context.services[*].protocol : "<cr>"

… defines a port command line with two values from the services array. The "<cr>" defined as the value will add a carriage return once the port command is written. As a result, a possible CLI command would be:

port 21 tcp

port 8080 tcp

port 53 udp

For instance:

dns-server $context.servers[*].ip : ""

… defines a dns-server command line with values from the servers array. The "" defined as the value will NOT add a carriage return in between the items of the servers array. The carriage return will be issued at the end. As a result, a possible CLI command would be:

dns-server 1.1.1.1 2.2.2.2 3.3.3.3

In the following example, the CLI model for the Service class:

"CliModel" : {

"acos" : {

"default" : {

"META-DATA" : {

"nameId" : "$context.name",


"boolProperties" : ["#context.enable"]

},

"slb server $context.name $context.rip.ipPrefix" : {

"<cr>" : {

"port $context.services[*].port

$context.services[*].protocol.name" : "<cr>"

}

}

}

}

}

In this example, the CLI model applies to a target device running the ACOS operating system (OS) with the "default" version of that operating system. If required, a specific version of the ACOS operating system can be added to deal with difference syntax introduced either by a new network function, a current network function being deprecated or amended.


16. Lab Run Configuration for Features

Once the Formula/FLOW/Config Data for a Feature under development has been completed, the next step in its development using the Gluware Lab environment is to Run it in the integrated Console execution environment.

Figure 13-1.

Whether accessed in the Gluware Lab menu bar "Run" option or by right clicking on the JNIB file in the project Explorer and selecting "Run As", the first step in execution is to select Run Configurations … This will bring up the Configuration form depicted above. Once the Formula file and any appropriate Start Object files have been specified, and the Run Type of FRE Launch is selected, the selections are applied and the Formula is run. If the Console View is not already open, this will open the Console View, where the details and results of the Formula being executed are reflected.


Note

Run Type for Features using the structures defined in this section must be FRE Launch (vs default for the capabilities in the last section).

17. Packages and Publishing in Control

Figure 15-1.

The Gluware orchestration and provisioning solution includes Lab, Control, and the Distribution Center that acts as a clearinghouse for all the different combinations of capabilities based on Formulas and FLOW created in Lab that are then imported and acted on in Control. The following content and illustrations include the relevant structures and concepts related to the creation and publishing of Gluware based features (or packages).

17.1 Packages

17.1.1 Creating Packages

As outlined at the end of the previous section of the Guide, the Lab Export option operates at an Org level within a Project, and allows Customs Scripts to be exported to Control. For the NDK/DNDK based features described in this section, the relevant Formulas and Flow in a Project are consolidated into a Control Package and then published to an area of the Distribution Center. From here, they are either


shared with other Gluware users (in Lab or Control) or imported to the desired Control system from the Distribution Center as described below.

Figure 15-2.

To begin the package creation process, the configuration panel illustrated above is opened as soon as the user right clicks on the desired Lab Project in the Folder tree of Lab. Creation and subsequent editing of an existing package follow the same process described below. In this example, the user selects Create Nib Package…

The user is then prompted to confirm their selection as illustrated below.


Figure 15-3.

The user then specifies the details of the package, and it bears noting at this point what the two primary consumption paths for packages will be. Once created and saved, the package will be used either to build other projects and packages within Lab, or the package will be imported as a Control package within Gluware Control. The following details are important documentation for other Lab and Control users in either case.


Figure 15-4.

Once the package creation option has been selected, the screen above is accessed. The ID is automatically generated by the Lab system and serves as a unique identifier for this Project/package within Gluware. The Name and Description fields are then defined for this package and serve to identify all versions of this package moving forward. Like the ID, the current version of the package is automatically generated by Lab and increments as each new version is saved. The Lab Feature and Control Package check boxes are used to designate the destination for this version of this package. If it is to be integrated into or used by other projects/packages within Lab, the user selects the Lab Feature option and the Lab Recommended Install check box becomes accessible. This option is used to suggest to other Lab users that this package be installed by default in all other projects. The Control Package option indicates that this Package is intended to be imported into Control. The Encrypt JNIBs check box allows the user some measure of protection for their Formulas by encrypting them within the package.


The NIB Package Dependencies window allows the user to specify other packages that this package will depend on, and pulls up a list of all visible packages for this user in the Distribution Center. Any critical resources for the current package should be selected. Once all the options have been specified, the user selects OK or Publish. Figure 15-5.

The Distribution Center is broken up into Distribution Areas. Users will only have access and visibility in the areas they have been assigned to by Gluware. Once the user has specified the Distribution Area they will publish to, the last step of package creation is to select the version number and provide a description for this version of the package. The user has the option to specify a different version number if desired, but the default option is recommended.

The Publish description is used to describe uniquely what is new in this version of the package. The user should only include the details specific to this version in this description and use the package description field in the previous field for describing the overall attributes of the package.

Once all of these options have been specified, the user can select OK and the package will be published.


Figure 15-6.

Once a package has been published for the first time, the project folder in the Folder tree will reflect the name and last saved version of the package associated with it as illustrated above.

network engineering guide - gluware®support.gluenetworks.com/glulab/.../neteng_guide... · this...

Documents