Template resource files

Config Template, Schema, and README Files

F5 NGINX Instance Manager uses Go templating and JSON schemas to create flexible and robust NGINX configuration templates. This allows users to efficiently customize and validate configurations without needing expert knowledge of NGINX syntax.

Enhanced templating with Sprig
Go templating in Instance Manager includes support for the Sprig function library, offering a wide range of additional functions that can be used in templates for advanced operations like string manipulation, data conversion, mathematics, and more.

This guide covers the following resource files for creating templates:

• Config files (*.tmpl), which are Go templates that define the NGINX configuration’s structure and parameters.
• Schema files (*.json), which are JSON schemas specifing the rules for input validation and providing the structure for dynamic web forms.
• README.md files, which document the template’s purpose, usage, and capabilities.

If you’re creating templates from scratch, the following table lists the acceptable template and schama filenames to use:

Example: Enable OIDC with main.tmpl

This example shows how to enable OIDC authentication in NGINX using a config template and user input. This templated approach with JSON schema validation simplifies updating the NGINX configuration and reduces the risk of errors.

• main.tmpl

  A template file, main.tmpl, checks if OIDC (OpenID Connect) authentication should be enabled in the NGINX configuration based on user input. If the input enables OIDC, the template instructs NGINX to load the ngx_http_js_module.so module necessary for OIDC functionality.

  {{$input := .}}
  {{$baseData := .Data.V1}}
  {{$oidcEnabled := false}}
  
  {{if $baseData.main}}
      {{if $baseData.main.templateInput}}
          {{$oidc := index $baseData.main.templateInput "oidc"}}
          {{if $oidc}}
              {{$oidcEnabled = index $oidc "enabled"}}
          {{end}}
      {{end}}
  
      {{if eq $oidcEnabled true}}
          load_module modules/ngx_http_js_module.so;
      {{end}}
  {{end}}
  

• main.json

  A JSON schema file, main.json, validates user inputs for main.tmpl, ensuring that the oidc object’s enabled property is correctly defined and used. The templateInput root property is required and will be validated when analyzing the template.

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "Main inputs",
    "properties": {
  	"templateInput": {
  	  "type": [
  		"object",
  		"null"
  	  ],
  	  "properties": {
  		"oidc": {
  		  "type": "object",
  		  "title": "OIDC Setting",
  		  "description": "Adds OIDC settings to main, http, http-server and location blocks. Use OIDC to enable single sign-on (SSO) to authenticate to your app.",
  		  "__docs": [
  			{
  			  "title": "OIDC specification",
  			  "link": "https://openid.net/specs/openid-connect-core-1_0.html"
  			}
  		  ],
  		  "properties": {
  			"enabled": {
  			  "title": "OIDC authentication enabled",
  			  "type": "boolean",
  			  "description": "Set this value to be true, if location(s) can be accessed only after authentication by the OIDC provider configured at the gateway. If no authentication is needed set this value to be false.",
  			  "examples": [
  				true
  			  ]
  			}
  		  },
  		  "required": [
  			"enabled"
  		  ]
  		}
  	  }
      }
    },
    "required": []
  }
  

  
  

  An explanation of the JSON schema settings:

  • Root property for templateInput: The JSON schema defines a root property named templateInput. This property is necessary because it contains all the customizable parameters the user can provide for the template. The schema specifies that templateInput can be either an object (which holds configuration parameters) or null (indicating the absence of such parameters).

  • OIDC object validation: Within templateInput, there’s a specific object named oidc meant to configure OIDC-related settings. The schema for the oidc object includes a boolean property named enabled. This property controls whether OIDC authentication is turned on (true) or off (false) for the NGINX configuration being generated.

  • Input-validation for oidc object: The main.json provides rules for validating the oidc object’s inputs. For example, the enabled property within the oidc object must be a boolean. This ensures that the template receives correctly typed and structured data to generate the configuration correctly.

  • Required properties: The schema declares that within the oidc object, the enabled property is mandatory ("required": ["enabled"]). This means that any input provided for the oidc object must include a clear true/false value for enabled.

Additional Templating Resources

Concepts

• Understand Config Templates: Learn about config template types, publication targets, and the template submission process.

• F5 Global Default Base Template: Learn about the F5 Global Default Base Template, including its key components and usage. Discover how augment templates can be used to segment portions of the base template.

• Augment Templates: Learn how augment templates can be combined with base templates to add specific features like OIDC authentication, or segment (compartmentalize) configuration elements like location and server blocks.

• Template Resource Files: Learn about template resource files, including config template files, JSON schemas, and auxiliary files.

• Dynamic Form JSON Schema: Learn how to use JSON schemas for template input and validation in the dynamic web form builder.

How-Tos

• Manage NGINX Configs with Config Templates: Create, import, and deploy NGINX configurations using config templates.

• Access Control for Templates and Template Submissions: Apply role-based access control (RBAC) settings to templates and template submissions.