Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Puppet for Junos OS apply_group Defined Resource Type

Understanding the Puppet for Junos OS apply_group Defined Resource Type

Puppet for Junos OS enables you to use Puppet to manage certain devices running the Junos® operating system (Junos OS). The Puppet netdev_stdlib module is a vendor-neutral network abstraction framework that defines Puppet type specifications for certain resources used on network devices. The netdev_stdlib_junos module contains the provider implementations that enable you to configure these resources, which include physical interfaces, VLANs, link aggregation groups (LAGs), and Layer 2 switching services, on devices running Junos OS.

Puppet enables you to more easily manage resources on your network devices, but you are generally limited to configuring resource types that are already defined and implemented. Starting with netdev_stdlib_junos module version 2.0.2, the module provides the apply_group defined resource type, which enables you to manage resources that do not have separate type specifications. apply_group enables you to create generic resources as groups under the [edit groups] hierarchy level and apply those groups to your configuration.

The apply_group defined resource type references a custom Embedded Ruby (ERB) template that generates Junos OS configuration data. ERB is a templating engine for Ruby that enables you to create templates consisting of plain text documents with embedded Ruby code. ERB is part of the Ruby standard library, and ERB templates are supported in Puppet.

Because ERB templates are plain text documents, the template can include Junos OS configuration data in any of the supported formats including formatted ASCII text, Junos XML elements, or Junos OS set commands. The ability to add Ruby code to the template provides flexibility through the use of variable substitution and flow control. You can customize the input provided to the template for different Puppet client nodes by defining the relevant variables for that node in the manifest. When the ERB template is rendered, the plain text is copied directly to the output, and the embedded Ruby tags are processed. The client node applies the resulting configuration changes at the [edit groups] hierarchy level under the group name that matches the title for that apply_group resource.

An apply_group resource enables you to create and delete configuration groups as well as activate or deactivate a group. When you create or activate a configuration group, the client node also configures the group name in the apply-groups statement at the top of the configuration hierarchy so that the configuration inherits the statements in the corresponding group. When you delete or deactivate a configuration group, the client node removes the group name from the apply-groups statement if configured.

Creating Embedded Ruby Templates to Use with the Puppet for Junos OS apply_group Resource

Puppet for Junos OS enables you to use Puppet to manage certain devices running Junos OS. Starting with netdev_stdlib_junos module version 2.0.2, you can use the apply_group defined resource type to manage resources in the Junos OS configuration that do not have type specifications in the netdev_stdlib module. An apply_group resource references a custom Embedded Ruby (ERB) template that generates the Junos OS configuration data for a specific resource using the supplied inputs.

The ERB templating system for Ruby enables you to generate output from a template consisting of plain text with embedded Ruby code. You can create generic ERB templates that generate the desired Junos OS configuration data for any resource. Because ERB templates are plain text documents, the template can include Junos OS configuration data in any of the supported formats including formatted ASCII text, Junos XML elements, or Junos OS set commands. When the ERB template is rendered, the plain text is copied directly to the output, and the code in embedded Ruby tags is executed as Ruby code. ERB templates can also reference any node-specific Puppet variables that you define in the manifest.

ERB templates that are referenced by the apply_group resource must be placed in the netdev_stdlib_junos/templates directory on the Puppet master. The template filename must use the following format where the base filename can be any user-defined string, and the configuration format must reflect the format of the configuration data in the template, which can be "set", "text", or "xml". If the filename does not specify a format, the Puppet client uses XML as the default.

After you create and stage your ERB templates, you can use them to generate configuration data for resources on client nodes running Junos OS. To use a template, the Puppet manifest must include the apply_group resource, and the template_path attribute must reference the template. Any variables required by the template must be declared in the manifest.

ERB templates can contain Ruby tags, which are delimited by <% and %>. Table 1 summarizes the different ERB tag types, their syntax, and their impact on the rendered output. ERB code tags are generally used for flow control. The ERB processor executes code in a code tag but does not insert any values into the output. ERB tags that contain an equals sign (=) are expressions. The ERB processor evaluates the expression and places the resulting value in the output. ERB tags that contain the hash (#) symbol are comments that do not affect the rendered output.

Table 1: Embedded Ruby Tag Types

Tag Type

Syntax

Behavior

Code

<% code %>

Executes the code, but does not insert a value into the output.

Comment

<%# comment %>

Ignores any code following # and does not insert any text into the output.

Expression

<%= expression %>

Generates a value from the expression and inserts the value into the output.

Literal

<%% %%>

Inserts a literal <% %> into the output.

You can use Ruby tags in your templates to manipulate data, perform variable substitutions, iterate over indexed collections like arrays and hashes, and create conditional constructs. Some of the more common constructs are presented here. For detailed information about using ERB templates in Puppet, see https://puppet.com/docs/puppet/latest/lang_template_erb.html.

An ERB template can iterate over collections, such as arrays or hashes, by using the <% @variable.each … %> syntax. The following template iterates over each service in an array and generates Junos OS configuration data that configures each service at the [edit system services] hierarchy level under the specified configuration group.

Consider the following array declaration in the manifest, which defines several services:

When the template is evaluated with the given array, the template generates the following configuration data as set commands:

You can also iterate over items in a hash, which is indexed using a key rather than a number. The following ERB template iterates over log files in a hash and generates configuration data that configures the files along with their facility and severity details at the [edit system syslog] hierarchy level under the specified configuration group. Each log file is mapped to an array of hashes that store the facility and severity details.

Consider the following hash declaration in the manifest, which defines two log files and specifies the facility and severity of the messages to include in each log:

When the template is evaluated with the given hash, the template generates the following configuration data in text format:

You can also create conditional constructs like the following to modify the configuration data based on the presence or absence of variables in the supplied inputs:

For example, suppose that you are configuring a number of physical interfaces, and you only want to configure a logical interface when the relevant information is included in the supplied inputs. Consider the following hash declaration in the manifest:

A template can test whether the hash for each interface contains a unit key and then modify the configuration output based on the result. The following ERB template generates configuration data that configures a description for each physical interface but only configures the logical interface when the unit key is present in the hash for that interface:

The template generates the following Junos XML configuration data, which does not configure a logical unit for the ge-0/0/3 interface:

To avoid creating ERB templates from scratch, you can copy a portion of an existing device configuration into a new ERB template file, replace the variables in the configuration data with appropriate ERB variables, and add Ruby tags as required for flow control. For an example outlining how to copy and convert a configuration into an ERB template, see Puppet + ERB Templates + Junos = Increased automation agility and flexibility.

For more information about using Puppet templates, see the official Puppet documentation at https://puppet.com/docs/puppet/latest/lang_template.html.

Declaring the Puppet for Junos OS apply_group Resource in a Manifest

Puppet for Junos OS enables you to use Puppet to manage certain devices running Junos OS. You can use the apply_group defined resource type to manage generic resources in the Junos OS configuration that do not have type specifications in the netdev_stdlib module. An apply_group resource references a custom Embedded Ruby (ERB) template that generates the configuration data for the specific resource using the supplied inputs.

You declare resources of type apply_group in your manifest. When you declare the resource, you must define a title, which determines the group name under which the Puppet client applies the configuration changes. You must also define the template_path attribute to reference the desired ERB template located in the netdev_stdlib_junos/templates directory on the Puppet master. The template_path attribute follows Puppet’s normal convention of using module/template-filename for referencing template files. By default, Puppet looks for the template in the given module’s templates directory. For example:

The apply_group resource type includes two optional attributes, ensure and active. The ensure attribute determines whether to create or delete a configuration group, and the active attribute determines whether the group should be active or inactive on the device. Table 2 outlines the effects on the configuration for different attribute settings.

Setting ensure to present causes the client to create the configuration group in the Junos OS configuration at the [edit groups group-name] hierarchy level, whereas setting ensure to absent causes the client to delete the corresponding configuration group from the device configuration. Setting active to true activates the configuration group and adds the group name to the apply-groups statement at the top of the configuration hierarchy. Setting active to false, on the other hand, deactivates the configuration and removes the group name from the apply-groups statement, if configured. When you deactivate the configuration group, the device marks it with the inactive: tag and ignores that portion of the configuration when you commit it.

If the group name is configured under the apply-groups statement, the configuration inherits the statements in that configuration group. The order of the groups in the apply-groups statement determines the inheritance priority. The configuration data in the first group takes priority over the data in subsequent groups.

Table 2: ensure and active Attributes for apply_group Resources

Attribute Settings

Configuration Group

apply-groups Statement

ensure => present
active => true
(Default)

Create or modify the configuration group and ensure it is active

Add the group name to the apply-groups statement, if not already present.

ensure => present
active => false

Create or modify the configuration group and deactivate it

Remove the group name from the apply-groups statement, if present.

ensure => absent

Delete the configuration group

Remove the group name from the apply-groups statement, if present.

Note:

If active is set to true but ensure is set to absent, the client still deletes the group name from the apply-group statement, because the configuration group does not exist.

If the apply_group resource uses an ERB template that references Puppet variables, you must declare the necessary variables for that node in the manifest. Puppet variables are prefixed with a dollar sign ($).

When the Puppet client node downloads the catalog, it applies the configuration changes generated by the template at the [edit groups group-name] hierarchy level in the configuration and updates the group name in the apply-groups statement as instructed. The client also stores a copy of the configuration group in a /var/tmp/group-name file on the device, which can be useful for troubleshooting any issues.

The following steps outline how to add an apply_group resource to your manifest. In this example, the apply_group resource references the following ERB template named services.set.erb in the netdev_stdlib_junos/templates directory:

  1. Declare any Puppet variables that are used by the ERB template to generate the configuration data for that node.
  2. Declare an apply_group resource, and define the group name under which the configuration changes are applied.
  3. Define the template_path attribute, and reference the desired ERB template located in the netdev_stdlib_junos/templates directory.
  4. (Optional) Define the ensure attribute as present or absent to specify whether to create or delete the configuration group.

    If you omit the attribute, it defaults to present.

  5. (Optional) Define the active attribute as true or false to specify whether to activate or deactivate the configuration group.

    If you omit the attribute, it defaults to true.

An apply_group resource in a sample manifest file is presented here:

Example: Using the Puppet for Junos OS apply_group Resource to Configure Devices Running Junos OS

Puppet for Junos OS enables you to use Puppet to manage certain devices running Junos OS. This example shows how to use the apply_group defined resource type with an Embedded Ruby (ERB) template to configure a BGP resource, which does not have a type specification in the netdev_stdlib module.

Requirements

This example uses the following hardware and software components:

  • MX80 router running Junos OS Release 14.2R2 with the jpuppet software package installed and a Junos OS user account for Puppet.

  • Puppet master with the Juniper Networks NETCONF Ruby gem and netdev_stdlib_junos module version 2.0.3 installed.

Overview

This example creates a Puppet manifest that uses the apply_group resource to configure statements for internal and external BGP peering for the puppet-client.example.com node. The apply_group resource references the bgp.set.erb ERB template, which generates the configuration data for the resource. The template is located in the modules/netdev_stdlib_junos/templates directory.

The Puppet manifest declares the $bgp variable, which contains the node-specific configuration values that the template uses to generate the configuration data for that node. The data is provided in a hash that uses the BGP group names as keys. Each key maps to another hash that contains the details for that group including the group type, and the IP addresses and AS number of the peers. When the template is referenced, it iterates over the hash and generates the configuration data as Junos OS set commands.

The title for the apply_group resource defines the bgp_group group name under which the configuration changes are applied at the [edit groups] hierarchy level. The template_path attribute is set to netdev_stdlib_junos/bgp.set.erb, which references the bgp.set.erb template. The ensure attribute is set to present to instruct the client to create the configuration on the device, and the active attribute is set to true to make sure that the configuration is active and that the group name is configured under the apply-groups statement. Both attributes are optional in this case, because they are set to the default values.

When the client downloads the catalog, it adds the configuration data generated by the template under the [edit groups bgp_group] hierarchy level and configures the apply-groups statement to include the bgp_group group name. If the commit succeeds, the configuration inherits the statements in the configuration group.

Note:

This example assumes that the local autonomous system number is already defined on the device.

Configuration

Creating the ERB Template

To create and stage the ERB template:

  1. Create a new template file named bgp.set.erb, and add the text and Ruby tags required to generate the desired configuration data for the BGP resource.

  2. Place the template file in the modules/netdev_stdlib_junos/templates directory on the Puppet master.

Creating the Manifest

To declare the apply_group resource in a Puppet manifest and reference the ERB template:

  1. Create the manifest file and define the client node.

  2. Declare any Puppet variables that are used by the template to configure that node.

  3. Declare the apply_group resource and its title, which defines the group name under which the configuration data will be added at the [edit groups group-name] hierarchy level.

  4. Set the apply_group template_path attribute to reference the bgp.set.erb template.

  5. (Optional) Set the apply_group ensure attribute to present to create the configuration group.

  6. (Optional) Set the apply_group active attribute to true to activate the configuration.

Results

On the Puppet master, review the manifest. If the manifest does not display the intended code, repeat the instructions in this example to correct the manifest.

Verification

To verify that the commit was successful and the configuration reflects the new BGP resource, perform these tasks:

Verifying the Commit

Purpose

Verify the commit by reviewing the commit history for the Puppet node.

Action

From operational mode, you can enter the show system commit command to verify that the catalog changes were successfully committed.

Meaning

The commit log indicates that the Puppet client successfully applied the configuration changes generated by the template.

Verifying the Configuration

Purpose

Verify that the BGP configuration group is in the active configuration on the device and that the configuration group name is configured for the apply-groups statement.

Action

From operational mode, enter the show configuration groups bgp_group and the show configuration apply-groups commands.

apply_group

Syntax

Description

Defined resource type in the Juniper Networks netdev_stdlib_junos Puppet module that enables you to manage network resources that do not have type specifications in the netdev_stdlib module. apply_group enables you to create generic resources as groups under the [edit groups group-name] hierarchy level and apply those groups to the configuration of devices running Junos OS.

apply_group references an Embedded Ruby (ERB) template, which takes inputs defined in the manifest and generates the Junos OS configuration data that is configured on the client node. ERB templates referenced by an apply_group resource must be placed in the netdev_stdlib_junos/templates directory.

Attributes

group-name

Name of the group at the [edit groups] hierarchy level in the Junos OS configuration under which the configuration changes are applied.

active

(Optional) Specify whether to activate or deactivate the corresponding configuration group. A value of true activates the configuration group and adds the group name to the apply-groups statement in the configuration. A value of false deactivates the configuration group and removes the group name from the apply-groups statement if configured.

  • Default: true

ensure

(Optional) Specify whether to create or delete the configuration group. A value of present creates the configuration group. A value of absent deletes the configuration group and removes the group name from the apply-groups statement if configured.

  • Default: present

template_path

Reference to an ERB template. The value uses the Puppet convention for referencing template files, which is module/template-filename. The module name is netdev_stdlib_junos, and the template filename is an ERB template file residing in the netdev_stdlib_junos/templates directory.

Usage Examples

Consider the following ERB template, interface.set.erb, which iterates over a collection of interfaces. When rendered, the template generates configuration data that configures each interface with a description and a logical unit that has a protocol family and an address.

The following Puppet manifest uses an apply_group resource to configure the specified interfaces under the [edit group interface_group] hierarchy level. apply_group references the interface.set.erb ERB template in the netdev_stdlib_junos/templates directory.

Puppet renders the configuration data in the template using the inputs defined in the manifest.

The Puppet client configures the data under the [edit groups interface_group] hierarchy level and adds the group name to the apply-groups statement.

Release Information

Defined resource type introduced in netdev_stdlib_junos module version 2.0.2.