Basic Usage

K2HR3 Template Engine

Dynamic RESOURCE can be defined for RESOURCE of K2HR3 system.
The K2HR3 system provides a TEMPLATE notation for defining dynamic RESOURCE.
The contents described in this TEMPLATE pass through the K2HR3 Template Engine and are expanded as RESOURCE data. The K2HR3 Template Engine and TEMPLATE notation are described below.

Apply

In the K2HR3 system, USER can set a character string as RESOURCE data.
For character strings set as RESOURCE, USER and ROLE member HOST can be read.
The K2HR3 Template Engine can expand template strings that satisfy the TEMPLATE notation.

Overview

Explain the description method and specification of the basic TEMPLATE to be understood by the K2HR3 Template Engine.

Analysis range of TEMPLATE

The K2HR3 Template Engine analyzes and expands the character string of the range(statement) separated by the following keywords in the character string read as a TEMPLATE.

{{ .... }}

Specifying the template engine

This feature is reserved and currently only fixed value “k2hr3template”(for K2HR3 Template Engine) is supported.

This is a statement specified by the template engine.
It must start from the beginning of all TEMPLATE strings.
You can omit it when using the K2HR3 Template Engine.

Comment

Statements as described below will not be output(displayed) when expanded by the template engine.
It is a statement to use as a general comment.

{{# This is comment strings.... }}

Display variables

By describing as follows, you can display values such as variables (described later) used in the template.
You can also specify constants for variables to be displayed.

{{= 'print static string' }}
{{= true }}
{{= 1000 }}
{{= %variable% }}

Escape keyword

You may not want to recognize the keywords used to specify the analysis range of the template as a template.
Also, you may not want to recognize the keywords used to specify the character string (described later) as a template.
These escaping methods are shown below.

Constant

The constants supported by the K2HR3 Template Engine are shown below.

Number

There are the following methods for expressing numerical values supported by the K2HR3 Template Engine.

String

To describe a character string in a statement, specify the range with single quote or double quote.

'This is string in single quote'
"This is string in double quote"

Variable

When analyzing the template, the K2HR3 Template Engine permanently uses the variables of each template to be expanded.
A variable has one of the following forms.

%variable%
%var_array%[0] or %var_array%['0'] 
%var_object%{'key'} or %var_object%['key']

You can freely define variables in templates.
Alternatively, you can specify the YRN path of RESOURCE, ROLE registered in the K2HR3 system, and use the data set for these as variables.

%yrn:yahoo:yjcore:::resource:k2hr3api_res%

Array and object elements

Specify ‘[…]’ or ‘{…}’ to access array and object elements.
In the case of an array, the position number can be specified as a numerical value or character string in ‘[…]’.

%var_array%[0]
%var_array%['0']

In the case of an object, you can access it by specifying the key name as a character string in ‘{…}’ or ‘[…]’.

%var_object%{'key'}
%var_object%['key']

Number of array and object elements

The number of elements in arrays and objects can be obtained using ‘.length’ or ‘.size’, ‘.count’.
The following example displays the number of elements in the %var_array% array variable.

{{= %var_array%.length }}

Limit

Multi-level arrays and objects are not supported.
But accessing multiple arrays and objects can be achieved by preparing and accessing temporary variables as shown below.

{{ %tmparray% = %multiarray%[2] }}
{{= %tmparray%[0] }}

Syntax

The control syntax available for the K2HR3 Template Engine is shown below.

Operator

Enumerate available operators. Conditional operators are mainly used as conditional statements of control syntax.

Attention 1

Variables and constants basically have types (numbers, strings, logical values).
When binary operators specify variables and constants of different types, they are aligned to the type on the left side as much as possible.

Attention 2

Operator priorities follow general priorities.
The result of expanding the following template is “20”.

{{ %tmp_priority_data00% = 1 + 3 * 2 * 3 + 1 }}
{{= %tmp_priority_data00% }}

Samples

Samples(Basics)

The sample template character string (multiple lines) is shown below.

{{#!k2hr3template }}
{{# COMMENT LINE : The above line can be omitted. }}
Example of template expansion.

1) Examples of loops using variables
  {{ for %val% = 0 ; %val% < 2 ; ++%val% }}
    - Expansion within a loop: The value of the current variable {{= %val% }}.
  {{ done }}

3) Calculation
  {{ %val% = 10 + 10 * 9 / 3 }}
  %val% should be 40.
 Calculation result = {{= %val% }}

That 's all.

The following shows the result of expansion of the above template character string by the K2HR3 Template Engine.
Line feeds are adjusted

Example of template expansion.

1) Examples of loops using variables
    - Expansion within a loop: The value of the current variable 0.
    - Expansion within a loop: The value of the current variable 1.

3) Calculation
  %val% should be 40.
 Calculation result = 40

That 's all.

Samples(expanding ROLE member HOST)

ROLE has the HOST information as its member.
The HOST information can be used as a variable in the template which is using K2HR3 Template Engine.
The following is an example of a template that expands HOST information included in a ROLE.

{{#!k2hr3template }}
{{ foreach %host_key% in %yrn:yahoo:::mytenant:role:myrole/hosts/ip% }}
    {{ %one_host% = %yrn:yahoo:::mytenant:role:myrole/hosts/ip%{{ %one_host% = %yrn:yahoo:::mytenant:role:myrole/hosts/ip%{%host_key%} }}
    {{= %one_host%{'host'} }}
    {{= %one_host%{'port'} }}
{{ done }}

In the above example, the IP addresses in ROLE which are register by the K2HR3 application etc are displayed as the information of those HOST.
The HOST information always includes ‘host’ and ‘port’(0 for any).
If VirtualMachine and Pod(container) are automatically registered to ROLE from Openstack and kubernetes, there are some keys in addition to the above.
The following sample shows the individual HOST information for ROLE in like a JSON format.

'yrn:yahoo:::mytenant:role:myrole/hosts/ip': {
    '127.0.0.1,0,': {                                  <--- case of normal registration
        'host':   '127.0.0.1'
        'port':   0,
        'extra':  null,
        'cuk':    null
    },
    '127.0.0.2,0,': {                                  <--- case of automatically from openstack
        'host':   '127.0.0.2'
        'port':   0,
        'extra':  'openstack-auto-v1',
        'cuk':    null
    },
    '127.0.0.3,0,cuk-xxxxxxxxxxxxxxx': {               <--- case of automatically from kubernetes
        'host':                '127.0.0.3'
        'port':                0,
        'extra':               'k8s-auto-v1',
        'cuk':                 'cuk-xxxxxxxxxxxxxxx',
        'k8s_namespace':       'namespace'
        'k8s_service_account': 'sa'
        'k8s_node_name':       'nodename'
        'k8s_node_ip':         '127.0.0.3'
        'k8s_pod_name':        'podname'
        'k8s_pod_id':          'pod-id-yyyyyyyyyyyy'
        'k8s_pod_ip':          '192.0.0.3'
        'k8s_container_id':    'container-id-zzzzzz'
    },
    ...
}

Please refer to the sample above.
That way, you can distinguish regular registration, Openstack registration, and kubernetes registration from the elements of the HOST information.
Any of the following variable names can be used to indicate HOST information of ROLE.

1) Only IP address
   %yrn:<provider(domain)>:<service>:<region>:<tenant>:role:<role name>/hosts/ip%

2) Only hostname(FQDN)
   %yrn:<provider(domain)>:<service>:<region>:<tenant>:role:<role name>/hosts/name%

3) IP address and hostname(FQDN)
   %yrn:<provider(domain)>:<service>:<region>:<tenant>:role:<role name>/hosts/all%

These variables are defined every ROLE.
So you can use them from the template when you need them to unpack that information.

About expansion of HOST information

Here, it is assumed that a list of HOST registered in a specific ROLE is obtained and used in your application.
For example, the application needs to access an IP address registered in ROLE and expects to be able to dynamically generate a list of that IP address from the K2HR3 system.
To achieve this, do the following:

The sample template is shown below.

{{ %host_no% = 0 }}
{{ foreach %host_key% in %yrn:yahoo:::mytenant:role:myrole/hosts/all% }}
    {{ %one_host% = %yrn:yahoo:::mytenant:role:myrole/hosts/all%{{ %one_host% = %yrn:yahoo:::mytenant:role:myrole/hosts/all%{%host_key%} }}
    Host[{{= %host_no% }}] = {{= %one_host%{'host'} }}:{{= %one_host%{'port'} }}
    {{ ++%host_no% }}
{{ done }}

The following is a sample of the above template expanded.

    Host[0] = abc.example.com:0
    Host[1] = 127.0.0.1:0

As mentioned above, ROLE dynamic HOST information can be expanded as a part of RESOURCE using a template.

Basic Usage