ki
name: "Tutorial test KI"
version: "1@Author"
description: "Tutorial test KI to describe KI Syntax 6.0"
tier: "default"
Introduction
Knowledge Items use a YAML-like syntax and are constructed using five major sections. The following document will introduce you to each section and how it is used.
Sections
Mandatory elements for all KI are: Valid combinations are:
|
Every Knowledge Item is build with these sections:
Section | Description |
---|---|
|
Meta information about the KI, like |
|
Specifies on which node the knowledge will be applied and which conditions should exist on the node |
|
Commands to execute when KI is bound to a node before the specified conditions are matched |
|
Specifies which conditions should exist on the issue to execute the KI |
|
Commands to execute in the case of issue binding |
Depending on the type of function your Knowledge Item should perform, you
will need different combinations of elements. You can, for example,
create a KI that only has the prepare
element. It will react to the
specified environment and perform certain functionality without relying
on a special data situation (when) or actually running external tools or
actions (do).
ki
-
name
- KI Name (if KIs are saved to the filesystem, this name should be the same as the filename) -
description
- KI description -
version
- (Mandatory Attribute), defines the version of the KI. Proposed form is:1@author
(this should allow to modify the KI in a distributed environment by different people, but still allows easier update later. For example, if the author doesn’t change, then1@Foo
should be updated to2@Foo
, but2@Foo
and3@Bar
would be in conflict, needing manual resolving) -
tier
- Optional attribute to indicate execution tier the KI belongs to ("default", "policy" or "fallback")
KI Tiers
KIs can be assigned to one of three priority tiers which will affect KI selection priority.
default |
the normal KI priority which should be used for almost all normal KIs |
policy |
the policy level will guarantee execution before KIs of the other tiers |
fallback |
KIs in this tier will only ever be executed when not default or policy KIs are matching |
KI tiers are only applied on a vertex local scope, so a matching "fallback" KI on the current processing vertex will be executed before the issue is routed to a "policy" KI on a connected remote vertex.
Only use "policy" and "fallback" tiers for rare cases where guaranteed prioritized or "last resort" execution is absolutely essential. |
on
This section defines where the KI is "bound" meaning a definition of filter elements that specify environment conditions according to the MARS-Model Node data. It could look something like:
on
NodeType # exists
not NodeFoo # not exists
(NodeType == "Machine")
OSName =~ "(SLES|Centos)"
(OSVersion > "7") and (OSVersion < "10") # or OSVersion in 7..10 ?
with Type@in as ParentScope
(NodeType == "Resource") or (NodeType == "Software")
MonitoringEnabled
end
on.with
This subsection provides an additional restriction to the vertices on which ki
will be applied. Namely, the vertex which is matched by the regular conditions in on
section must additionally be connected to another vertex of type <vertexType>
by an connection of type <edgeType> in direction edgeDirection
. The <edgeType> can be omitted which would accept any edge type:
with <vertexType>@<edgeDirection>[:<edgeType>]
where <edgeDirection>
can have the following values: in
, out
, or connected
.
It specifies direction of the edge between vertices, can be incoming (in:←), outgoing (out:→) or connected (-). The last one means that condition with
is true for any edge direction (in or out), it just checks if edge exists.
on
ogit/_type == "ogit/Person"
with ogit/Software/Application@out:ogit/uses
ogit/name == "LunchApp"
ogit/url
end
That way KI
will execute on every vertex of type "ogit/Person" having an outgoing edge of type ogit/uses
to a
vertex of type ogit/Software/Application
which must satisfy the following conditions:
-
ogit/name
attribute has value "LunchApp" -
attribute
ogit/url
exists
prepare
This section is not mandatory. It is used to perform actions when the Knowledge Item is activated regardless of the specified data situation. This can typically be used to initialize temporary variables, contexts or to log additional messages to help debugging or interpreting the processing history. An example can look like this:
prepare
log("adding default aws profile for match")
AWSProfile = "Company"
EC2AMI = "ami-12345abcd"
EC2SecurityGroup = "sg-abc123"
#EC2SubNet = "subnet-abc123"
EC2SubNet = "subnet-abc123"
EC2InstanceType = "m4.2xlarge"
Note however, that pure prepare
KIs will only be executed when an
issue does KI evaluation on that node. You must not expect the prepare
block to be executed on every possible node when deploying the KI. You
can however assume that it will be executed before other KIs on the same
node are triggered by an actual issue.
<<<
when
The instructions defined in do
will only be executed when all conditions
of when
section are matched.
when
VarA
VarB["key"] # match on key
VarC[VarA] == NodeType
list VarD
VarF as Test
MonitoringStatus@any == "true"
do
Once all conditions are matched the Knowledge Item will be applied. The
do
section defines which actions are performed. It might look like this:
log.info("bind ki and execute do")
VarB["new_key"] = 1
add(NewVar["key"] = "1")
delete(VarA)
stdout: ExecuteOutput, exit: LOCAL::Error = execute("path/to/script", timeout: 60)
if Error then
log.error("command returned with non-zero exit code")
else
log("execute returned ${ExecuteOutput}")
end
Logical Branching
Designing Knowledge Items with As a rule of thumb: Deciding between variants of a log message is acceptable. Making decisions about the data condition should be handled in a separate and re-usable Knowledge Item. |
You can use the If function to add logical branching to your Knowledge Item.
do
stdout: ExecuteOutput, exit: LOCAL::Error = execute("path/to/script", timeout: 60)
if Error then
log.error("command returned with non-zero exit code")
else
log("execute returned ${ExecuteOutput}")
end
Comments
Single line KI will not work with inline comments. If you wish to use comments in your KI definition you MUST use the long form notation. |
You can add comments to you Knowledge Items that explain what certain elements are supposed to do. They simply start with a #
. Comments can be added virtually anywhere in the definition.
# Just a comment
VarA #This is also a comment
If you wish to see how these sections are used you can refer to a full example. |