iApp Lab 2 - Getting to Know the Include Files

Getting Comfortable with iApp template code reuse

People new to iApp templates are often frustrated by trying to understand the usage of APL defines and TCL procs defined in the apl_common and app_utils include files. The purpose of this lab is to get you comfortable finding code in these include files, and in making your own include files to share code between your templates. You will also be creating a simple template that creates a simple config.
Note: When it comes to editing your template, you have a choice as to how you want to do it.
1. You can edit the template on the BIG-IP in TMSH, using vi.
2. You can export the entire template as a file, load that file into your code editor for editing, and then import it back into the BIG-IP when you are finished.
3. You can cut-and-paste the contents of the section that you are working on into the code editor of your choice, work on it there, and cut-and-paste it back.
4. You can make your edits in the BIG-IP iApp Template UI, although this option is really not recommended.

Part 1: Create a new iApp template

You can do this through the UI
1. Navigate to the iApp -> Templates screen.
2. Click Create.
3. Name your new template lab_2 and save it.
Or from TMSH
1. Enter TMSH and navigate to ‘/ sys application template’
2. Suggestion: type “modify cli preference tcl-syntax-highlighting enabled”
3. Type ‘create lab_2’ and hit enter.

Part 2: Copy the include scripts

For our first task, we are going to copy the include scripts so that we have a version that we can work with.
1. Enter TMSH and navigate to ‘/ sys application apl-script’
2. Copy the apl_common script with this command ‘cp f5.apl_common my_apl_common’
3. Navigate to ‘/ cli script’
4. Copy the app_utils script with this command ‘cp f5.app_utils my_app_utils’

Part 3: Attach the include files and export

We want to get a look at what is inside these include files, so the first thing we are going to do is attach them to our new template and export the template so that we can get them.
1. Edit your new template in TMSH or in the GUI.
2. At the top of the presentation section, add this line,
include "/Common/my_apl_common"

3. At the top of the implementation section, add this line,
tmsh::include "my_app_utils"

4. Save the template
5. In the GUI, export your new template.
6. Open the resulting file and have a look at the contents of these include files

Part 4: Edit my_apl_common

We are going to define two new types in the APL script that can be used in the template. The first one is a row containing the IP address and port. The second is a simple pool members table.
1. Open the exported template file and find the place where my_apl_common is defined.
2. Add the definition for the row.
define row ip_and_port {
    string ip validator "IpAddress"
    editchoice port default "80" { "http" => "80", "https" => "443" }
}

3. Add the definition for the simple pool member table
define table simple_pool_members {
    string addr required validator "IpAddress"
    string port default "80" required validator "PortNumber" display "small"
}

4. Save the file.

Part 5: Edit the Presentation Section

Now it is time to create the template UI. We are going to use the two defined types that we just added to my_apl_common, along with the yesno and lb_method defined types that were already defined there. We will also use two section elements and an optional element. This simple UI is just going to ask for an IP and port number for a virtual server and optionally ask for a set of IP/port combinations to populate a pool with.
1. Open the exported template file and find the place where the presentation section is defined.
2. Add a section element named virtual
3. Inside the virtual section, add
  1. An ip_and_port element named vs_info.

ip_and_port vsinfo

  1. A yesno element named attach_pool
4. Add an optional that displays when attach_pool is equal to Yes.
5. Inside the optional, add a section named pool.
6. Inside the pool section add
  1. a simple_pool_members element named servers
  1. and an lb_method element named lb
7. Add the text strings
 {
    virtual “Virtual Server Questions”
    virtual.vs_info “Enter the IP address and port for the virtual server.”
    virtual.attach_pool “Do you want to add a pool to this virtual server?”
    pool “Server Pool”
    pool.lb “What load balancing method do you want to use?”
    pool.servers “Enter the IP address and port combinations for the servers that you want in this pool.”
}

8. Save the file.

Part 6: Testing the Presentation:

It is a really good idea to always make sure that the presentation part of the template is working the way that you want before you dive into the implementation section.
1. First import the template back into the BIG-IP.
a. In the GUI, navigate to iApps -> Templates screen and click the import button.
  1. Select the file that you have been working in.
  1. Check the Overwrite Existing Templates check-box.
  1. Click Upload.
2. Enter the template and verify that all of the visual elements, questions, and labels all look as they should.
3. If anything isn’t right, go back and fix it. If you need help figuring out what has gone wrong, ask your instructor.

Part 7: Edit the Implementation Section

OK, now it’s time to create an actual config with your template. We are going to consume the inputs from the presentation section and use them to create a virtual server, and also a pool if the user selected one. We are going to keep things simple by using some predefined procs from my_app_utils.
1. Open the exported template file and find the place where the implementation section is defined.
2. First we need to add some global constants. One of the drawbacks of using cli script includes is that you cannot define global constants inside the include file. Any global constants that are needed by a proc inside that included script that is used in your template, have to be included in your template. In our case, we need to supply the following, which you could also have cut-and-pasted out of almost any of the templates in the system.
set NO_ANSWER "No"
set YES_ANSWER "Yes"
set WAN_OPTION "WAN"
set EMPTY_STRING "EMPTY_STRING_NO_VALUE_PRESENT"
set ADDR_FIELD "addr"
set PORT_FIELD "port"
set RATIO_FIELD "ratio"
set CONNECTION_LIMIT_FIELD "connection_limit"
set HOST_FIELD "host"
set ONE_SPACE " "
set HTTP_11_VERSION_STRING "\"Version 1.1\""

3. Now we are going to create the pool, is the user desired one. We are going to accomplish this by reusing the create_pool proc that is included in my_app_utils.
a. check the following link to see procedure input and output details https://devcentral.f5.com/wiki/iApp.app-utils-CLI-script-include.ashx#create_pool:_45
b. Add an if statement that checks if the attach_pool input was set to Yes.
i. If attach_pool is set to No, set a variable named pool_name to none.
ii. If attach_pool is set to Yes, set the variable named pool_name to the result of running tmsh::run_proc my_app_utils:create_pool with the inputs set as follows
  1. Use tmsh::app_name for the app_name parameter
  1. Use none for the monitor_name parameter
  1. Use “{$pool__servers}” for the servers parameter
  1. Use $::pool__lb for thelb_method parameter
4. Now it is time to create the virtual server. We are going to accomplish this by reusing the create_http_vs proc that is included in my_app_utils.
  1. Scroll up and have a look at what inputs that proc requires.
b. Run tmsh::run_proc my_app_utils:create_http_vs with the inputs set as follows
  1. Use tmsh::app_name for the app_name parameter
ii. Use $::virtual__vs_info__ip:$::virtual__vs_info__port for the destination parameter
  1. Use automap for the snat parameter
iv. Use the pool_name variable defined above for the pool_name parameter
  1. Use http for the profile_names parameter
  1. Use none for the persist_profile parameter
  1. Use tcp for the tcp_server_profile_name parameter
  1. Use tcp for the tcp_client_profile_name parameter

Part 8: Testing the Template as a whole:

1. First import the template back into the BIG-IP.
2. Enter the template, fill in all of the fields, and click Finished.
3. If any errors are reported, correct them, return, and continue.
4. Make sure to test it both ways, with a pool attached and without.

Optional/Bonus Step: Edit the Help Section

Optionally, you can go into the Help section and add some guidance for your new template.

The BIG-IP API Reference documentation contains community-contributed content. F5 does not monitor or control community code contributions. We make no guarantees or warranties regarding the available code, and it may contain errors, defects, bugs, inaccuracies, or security vulnerabilities. Your access to and use of any code available in the BIG-IP API reference guides is solely at your own risk.