Device Templates

Device templates allow sharing protocol configurations between devices and configuring protocols via YAML syntax. This enables advanced features like templating or using external sources for device authentication.

Templates can be found on the sidebar under Device Templates, which presents a table with all created device templates. This view can be used to search, sort, create, update, or delete device templates seamlessly, just like in other tables in the RADKit Service UI.

../_images/list.png

Device Template configuration consists of:

  • Template Name: A unique identifier for the template.

  • Description: An optional description.

The Device Templates feature allows users to define and manage protocol configurations for devices using the YAML language. This feature enables dynamic configuration of various communication protocols, such as:

  • http

  • swagger

  • snmp

  • terminal

  • netconf

Templates are created through the webUI and require the following inputs:

  • name: The name of the template (required, string).

  • description: A description of the template (optional, string).

  • variableDefinitions: User-defined variables that can be referenced in the YAML configuration (optional).

  • protocolsDefinitionTemplate: The main configuration in YAML format that describes the protocols.

The system dynamically parses the YAML configuration before establishing a connection to the device.

—

Adding a New Device Template

To add a new Device Template, navigate to Device Templates in the sidebar and then click Add Device Template.

../_images/add.png

—

Default Variables

Three built-in variables are always available in every template and do not need to be declared:

  • device_name (string): The name of the device being connected to.

  • username (string): The name of the user attempting to connect to the device.

  • request_source (string): The source of the connection request to the RADKit Service. Possible values include: - cloud/{client_id} - asgi/username - direct/address:port - in_memory

These variables are automatically available within the YAML configuration and do not require explicit definition.

—

Complete YAML Example with Defaults

http:
  authentication_extra: null
  password: null
  port: 443
  protocol: HTTPS
  use_insecure_algorithms: false
  username: null
  verify: true
netconf:
  password: null
  port: 830
  use_insecure_algorithms: false
  username: null
snmp:
  community_string: null
  port: 161
  version: 2
swagger:
  password: null
  port: 443
  schema_path: ''
  use_insecure_algorithms: false
  username: null
  verify: true
terminal:
  capabilities:
  - UPLOAD
  - EXEC
  - INTERACTIVE
  - DOWNLOAD
  connection_method: SSH
  enable_password: null
  jumphost: false
  password: null
  port: 22
  private_key: null
  provisioning_variant: DEFAULT
  use_insecure_algorithms: false
  use_tunneling_if_jumphost: true
  username: null

—

Supported YAML Tags

The following custom YAML tags have been introduced to enable advanced dynamic behavior within templates:

### Tag !var

The !var tag allows the use of variable values defined in the variableDefinitions field or the built-in default variables within the YAML configuration.

#### Syntax:

!var <variable_name>

#### Example:

terminal:
  username: !var username
  password: !var password

—

### Tag !concat

The !concat tag combines a list of values into a single string. This is useful for dynamically building strings from multiple components.

#### Syntax:

!concat
  - <value1>
  - <value2>
  - ...

#### Example:

Below is an example of combining two strings, admin and _user, into a single value for the username field:

terminal:
  username: !concat
    - admin
    - _user

The above YAML will result in the following configuration:

terminal:
  username: "admin_user"

—

### Tag !combine

The !combine tag takes a list of mappings and combines them into a single mapping. This is particularly helpful for merging multiple key-value pairs into a single structure.

#### Syntax:

!combine
  - key1: value1
  - key2: value2
  - ...

#### Example:

Below is an example of using !combine to merge username and password fields into a single mapping:

terminal: !combine
  - username: admin
  - password: secret

The above YAML will result in the following configuration:

terminal:
  username: admin
  password: secret

—

### Tag !external and !external-key

The !external tag enables integration with the External Sources feature. This tag allows users to reference external sources as dynamic data providers for specific protocol fields, such as device credentials, external secret storage, or third-party authentication methods. External Sources

The External Sources feature enables integration with third-party applications and services. It allows for the delegation of device authentication and/or administrative authentication, such as external secret storage or third-party admin authentication methods.

#### Syntax:

!external <external_source_name>

Or, with additional parameters:

!external
  name: <external_source_name>
  use: <field_name>        # Optional
  values: <input_mapping>  # Optional

#### Parameters

  • name: The name of the external source to be used (required if the shorthand syntax is not used).

  • use: Specifies a specific field to extract from the returned mapping. This is used when the external source returns a mapping, and you need to select a particular value. Returns a scalar.

  • values: Allows passing additional variables to the external source, which may influence the data returned. Accepts a mapping.

#### !external-key

The !external-key tag is identical to !external, but will automatically fill in the “use” parameter using the key of the parent mapping in which it’s being used. Because of this, it can only be used in a mapping context.

#### Examples:

##### Example 1: Simple Reference to an External Source

terminal:
  username: !external-key static_credentials
  password: !external-key static_credentials

Here: - static_credentials is used as the external source for the username. - static_credentials is used as the external source for the password.

##### Example 2: Using the use Parameter

terminal:
  password: !external
    name: cyberark
    use: device/pass

Here: - The cyberark external source returns a mapping. - The use parameter specifies the device/pass field to extract, which results in a scalar value (e.g., the password string).

##### Example 3: Passing Additional Variables with values

terminal: !combine
  - !external
    name: keyboard-interactive
    values:
      var1: value1
      var2: value2

Here: - The keyboard-interactive external source is used. - The values parameter provides additional input (var1: value1, var2: value2) to the external source, which may influence the returned data.

##### Example 4: Shorthand syntax

terminal: !external demo

This is equivalent to:

terminal: !external
  name: demo

—

Example of Adding a New Template

This example demonstrates the required inputs and the use of YAML tags (!var, !concat, !combine, !external and !external-key).

#### Template Inputs:

  • name: MyDeviceTemplate

  • variableDefinitions: - custom_port (default: 22)

#### YAML Configuration (protocolsDefinitionTemplate):

http:
  username: !var username
  password: !external-key static_credentials
  port: 443
  verify: true

terminal: !combine
  - username: !concat
      - admin
      - _ssh
  - password: !external
      name: cyberark
      use: pass/terminal
  - connection_method: SSH
  - port: !var custom_port

swagger: !combine
  - username: !var username
  - password: !var another_external_source
  - verify: false

—

Explanation of the Configuration:

  1. HTTP Configuration: - The username is dynamically resolved using the !var tag. - The password is retrieved from the external source static_credentials using the !external-key tag. - The port is explicitly set to 443.

  2. Terminal Configuration: - Combines fields using the !combine tag:

    • The username is dynamically built using the !concat tag to combine admin and _ssh into a single string (admin_ssh).

    • The password is retrieved from the external source cyberark using the !external tag with the use parameter, specifically extracting the value from the pass/terminal field.

    • The connection_method is explicitly set to SSH.

    • The port dynamically uses the custom_port variable with a default value of 22.

  3. Swagger Configuration: - Combines fields using the !combine tag:

    • The username is dynamically resolved using the !var tag.

    • The password is retrieved from an external source (another_external_source) using the !var tag.

  4. Verify Template: - A reusable block of configuration (verify_template) defines verify: true for SSL certificate verification.

Using Device Templates in Devices

To use a device template in a device, open the device edit modal, select the desired template in the Template Selector, and provide all the mandatory and/or optional variable values.

../_images/device-use-single.png

Or use Bulk Edit if you want to modify more than a single device.

../_images/device-use-bulk.png

Selecting a template in the Template Selector changes this value for all the devices added to the cart. If no template is selected, the device template selection will be removed from all the devices. If a template is selected, it will add or override the template selection in every device in the cart.

Note

When a Device Template is selected, it takes precedence over other protocol configurations.