Model and Syntax¶
Landscape¶
A landscape is defined as a collection of items which somehow belong together, be it for technical or business reasons. For example, a company department might model ALL its applications in production as one landscape and use grouping or tagging to further separate the applications. A second landscape could be used to model a future layout with a different infrastructure. Both landscapes could have items in common (like a database, load balancer, etc.), so their configuration can be reused.
LandscapeDescription¶
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
assignTemplates | Map<array> | optional, defaults to null | null | |
color | String | optional, defaults to null | null | |
config | LandscapeConfig<LandscapeConfig> | optional, defaults to null | null | |
contact | String | Primary contact method, preferably an email address. | optional, defaults to null | null |
description | String | A brief description of the landscape. | optional, defaults to null | null |
groups | Map<GroupDescription> | Description of item groups (optional, can also be given in sources). | optional, defaults to null | null |
icon | String | An icon or logo url | optional, defaults to null | null |
identifier | String | Immutable unique identifier. Maybe use an URN. | required, defaults to null | null |
isPartial | Boolean | optional, defaults to null | null | |
items | List<ItemDescription> | List of configuration sources. Handled in the given order, latter extend/overwrite earlier values like items etc. | optional, defaults to null | null |
labels | Map | optional, defaults to null | null | |
links | Map<Link> | Key-value pairs of related links. Some keys like 'github' cause that the endpoint data is parsed and added to to corresponding landscape component. | optional, defaults to null | github: https://github.com/dedica-team/nivio |
name | String | Human readable name. | required, defaults to null | null |
owner | String | The business owner (person or team), preferably an email address. | optional, defaults to null | null |
partial | Boolean | marks that the landscape is not complete, but an update | optional, defaults to null | null |
templates | Map<ItemDescription> | Item descriptions to be used as templates. All values except identifier and name will be applied to the assigned items. | optional, defaults to null | null |
SourceReference¶
This is a reference to a configuration file.
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
assignTemplates | Map<array> | A map with template identifier as key and item identifier matchers as value | optional, defaults to null | endOfLife: [web, “java6*”] |
basicAuthPassword | String | optional, defaults to null | null | |
basicAuthUsername | String | optional, defaults to null | null | |
deprecation | String | deprecation info (typically used in OpenAPI specs) | optional, defaults to null | null |
format | String | The input format. | optional, defaults to null | null |
headerTokenName | String | optional, defaults to null | null | |
headerTokenValue | String | optional, defaults to null | null | |
href | String | The link target. | required, defaults to null | null |
hreflang | String | hateoas language | optional, defaults to null | null |
media | String | hateoas media type | optional, defaults to null | null |
name | String | HateOAS / OpenAPI name | optional, defaults to null | null |
rel | String | hateoas relation type | optional, defaults to null | null |
title | String | hateoas title | optional, defaults to null | null |
type | String | optional, defaults to null | null | |
url | String | A URL, but can also be a relative path. | optional, defaults to null | ./a/items.yaml |
LandscapeConfig¶
Configuration of key performance indicators (i.e. status indicators) and layouting tweaks.
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
branding | Branding<Branding> | optional, defaults to null | null | |
greedy | Boolean | Flag that enables instant creation items based relation targets that cannot be found in the sources. | optional, defaults to null | null |
groupBlacklist | List | Names or patterns of groups that should be excluded from the landscape. Used to improve automatic scanning results. | optional, defaults to null | .*infra.* |
kpis | Map<KPIConfig> | Key performance indicator configs. Each KPI must have a unique identifier. | optional, defaults to null | null |
labelBlacklist | List | Names or patterns of labels that should be ignored. Used to improve automatic scanning results. | optional, defaults to null | .*COMPOSITION.* |
layoutConfig | LayoutConfig<LayoutConfig> | required, defaults to null | null |
KPIConfig¶
The configuration of landscape specific key performance indicators that derive status information from landscape components. Usually the KPIs work on labels
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
description | String | Description of the purpose of the KPI | optional, defaults to null | null |
enabled | Boolean | A flag indicating that the KPI is active. Can be used to disable default KPIs. | optional, defaults to null | null |
label | String | Key of the label to evaluate | required, defaults to null | costs |
matches | Map | A map of string based matchers that determine the resulting status (GREEN|YELLOW|ORANGE|RED|BROWN). Use a semicolon to separate matchers. | optional, defaults to null | RED: BAD;err.* |
messageTemplate | String | Template for the displayed message, containing a placeholder for the assessed value '%s | optional, defaults to null | The current value is: %s |
ranges | Map | A map of number based ranges that determine the resulting status (GREEN|YELLOW|ORANGE|RED|BROWN). Use a semicolon to separate upper and lower bounds. Tries to evaluate label values as numbers. | optional, defaults to null | GREEN: 0;99.999999 |
LayoutConfig¶
Layout configuration for landscapes with unusual number or ratios of items, groups and relations.
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
groupLayoutInitialTemp | Integer | The initial temperature for layouts of groups. | required, defaults to 900 | 900 |
groupMaxDistanceLimit | Integer | A maximum distance between groups up to where forces are applied. | required, defaults to 1000 | 1000 |
groupMinDistanceLimit | Integer | The minimum distance between groups. | required, defaults to 50 | 50 |
itemLayoutInitialTemp | Integer | The initial temperature for layouts of items within groups. | required, defaults to 300 | 300 |
itemMaxDistanceLimit | Integer | A maximum distance between items up to where forces are applied. | required, defaults to 350 | 350 |
itemMinDistanceLimit | Integer | The minimum distance between items. | required, defaults to 100 | 100 |
Branding¶
Map branding (tweaks visuals)
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
mapStylesheet | String | A resolvable URL pointing to a CSS stylesheet. This stylesheet is included in the generated SVG map. Use is to style the appearance of the map. | optional, defaults to null | https://acme.com/css/acme.css |
GroupDescription¶
A group of items. Could be used as bounded context, for instance.
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
color | String | The HTML (hexcode only!) color used to draw the group and its items. If no color is given, one is computed. | optional, defaults to null | 05ffaa |
contact | String | A contact method, preferably email. | optional, defaults to null | null |
contains | List | A list of item identifiers or SQL-like queries to easily assign items to this group. | optional, defaults to null | identifier LIKE ‘DB1’ |
description | String | A brief description. | optional, defaults to null | null |
environment | String | optional, defaults to null | null | |
identifier | String | A unique identifier for the group (also used as name). Descriptions are merged based on the identifier. | required, defaults to null | shipping |
labels | Map | optional, defaults to null | null | |
links | Map<Link> | Key-value pairs of related links. Some keys like 'github' cause that the endpoint data is parsed and added to to corresponding landscape component. | optional, defaults to null | github: https://github.com/dedica-team/nivio |
name | String | optional, defaults to null | null | |
owner | String | The business owner of the group. | optional, defaults to null | null |
ItemDescription¶
List of configuration sources. Handled in the given order, latter extend/overwrite earlier values like items etc.
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
address | String | The technical address of the item (should be an URI). Taken into account when matching relation endpoints. | optional, defaults to null | null |
color | String | Overrides the group color. Use an HTML hex color code without the leading hash. | optional, defaults to null | 4400FF |
contact | String | The primary way to contact a responsible person or team. Preferably use an email address. | optional, defaults to null | johnson@acme.com |
description | String | A brief description. | optional, defaults to null | null |
frameworks | Map | The parts used to create the item. Usually refers to technical frameworks. | optional, defaults to null | java: 8 |
group | String | The identifier of the group this item belongs in. Every item requires to be member of a group internally, so if nothing is given, the value is set to its layer. | optional, defaults to null | shipping |
icon | String | An icon name or URL to set the displayed map icon. The default icon set is https://materialdesignicons.com/ and all names can be used (aliases do not work). | optional, defaults to null | null |
identifier | String | Immutable unique identifier (maybe use an URN). Primary means to identify items in searches. | required, defaults to null | null |
interfaces | Set<InterfaceDescription> | A collection of low level interfaces. Can be used to describe HTTP API endpoints for instance. | optional, defaults to null | null |
labels | Map | optional, defaults to null | null | |
layer | String | The technical layer | optional, defaults to null | infrastructure |
lifecycle | String | The lifecycle state of an item. | optional, defaults to null | null |
links | Map<Link> | Key-value pairs of related links. Some keys like 'github' cause that the endpoint data is parsed and added to to corresponding landscape component. | optional, defaults to null | github: https://github.com/dedica-team/nivio |
name | String | A human readable name/title. The name is considered when items are searched. | optional, defaults to null | my beautiful service |
owner | String | The business owner of the item. Preferably use an email address. | optional, defaults to null | johnson@acme.com |
providedBy | List | A collection of identifiers which are providers for this item (i.e. hard dependencies that are required). This is a convenience field to build relations. | optional, defaults to null | shipping-mysqldb |
status | List<map> | A list of statuses that works like hardcoded KPIs. | optional, defaults to null | null |
statuses | List<map> | A list of statuses that works like hardcoded KPIs. | optional, defaults to null | null |
tags | List | optional, defaults to null | null | |
type | String | The type of the item. A string describing its nature. If no icon is set, the type determines the displayed icon. | optional, defaults to null | service|database|volume |
InterfaceDescription¶
Describes a low-level interface of an item.
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
deprecated | Boolean | optional, defaults to null | null | |
description | String | A brief description. | optional, defaults to null | null |
format | String | The payload format. | optional, defaults to null | null |
name | String | optional, defaults to null | null | |
parameters | String | optional, defaults to null | null | |
path | String | optional, defaults to null | null | |
payload | String | optional, defaults to null | null | |
protection | String | A description of the interface protection method. | optional, defaults to null | null |
summary | String | optional, defaults to null | null | |
url | String | A URL describing the endpoint. | optional, defaults to null | null |
Link¶
A link to an external resource. Contains a href (URL) plus various attributes for authentication and/or hateoas.
Name | Type | Description | Remarks | Example |
---|---|---|---|---|
basicAuthPassword | String | optional, defaults to null | null | |
basicAuthUsername | String | optional, defaults to null | null | |
deprecation | String | deprecation info (typically used in OpenAPI specs) | optional, defaults to null | null |
headerTokenName | String | optional, defaults to null | null | |
headerTokenValue | String | optional, defaults to null | null | |
href | String | The link target. | required, defaults to null | null |
hreflang | String | hateoas language | optional, defaults to null | null |
media | String | hateoas media type | optional, defaults to null | null |
name | String | HateOAS / OpenAPI name | optional, defaults to null | null |
rel | String | hateoas relation type | optional, defaults to null | null |
title | String | hateoas title | optional, defaults to null | null |
type | String | optional, defaults to null | null |
Plus, there are labels having a special meaning:
capability
The capability the service provides for the business or, in case of infrastructure, the technical capability like enabling service discovery, configuration, secrets, or persistence.color
A hex color code (items inherit group colors as default)costs
Running costs of the item.fill
Background image (for displaying purposes).frameworks
A comma-separated list of frameworks as key-value pairs (key is name, value is version).health
Description of the item’s health status.icon
Icon/image (for displaying purposes).label
A custom label (like a note, but very short).lifecycle
A lifecycle phase (PLANNED|plan
,INTEGRATION|int
,PRODUCTION|prod
,END_OF_LIFE|eol|end
).note
A custom note.scale
Number of instances.security
Description of the item’s security status.shortname
Abbreviated name.software
Software/OS name.stability
Description of the item’s stability.team
Name of the responsible team (e.g. technical owner).version
The version (e.g. software version or protocol version).visibility
Visibility to other items.weight
Importance or relations. Used as factor for drawn width if numbers between 0 and 5 are given.
You can also store custom properties as labels, but keep in mind that
- label keys are converted to lowercase and
- label values are stored as string.
Item configuration
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | items: - identifier: blog-server shortName: blog1 group: content mycustomlabel1: foo mycustomlabel_2: bar any: entry is stored as label frameworks: php: 7.1 - identifier: auth-gateway shortName: blog1 layer: ingress group: content - identifier: DB1 software: MariaDB version: 10.3.11 type: database layer: infrastructure |
Item Groups¶
Groups can have the following attributes:
identifier
: A unique identifier in the landscape. Provided automatically via the dictionary key, so do not set it.contains
Array of references to other items (identifiers and CQN queries).owner
Owning party (e.g. marketing).description
A short description.team
Technical owner.contact
Support/notification contact (email). May be addressed in case of errors.color
A hex color code for rendering.links
A map/dictionary of URLs to more information.
Group configuration
1 2 3 4 5 6 7 8 9 10 11 12 | groups: content: description: All services responsible to provide information on the web. owner: Joe Armstrong team: Team Content contact: joe@acme.org color: "#345345" links: wiki: http://wiki.acme.org/teamContent infrastructure: team: Admins |
Item Identification and Referencing¶
An item can be uniquely identified by its landscape, its group, and its identifier. A fully qualified
identifier is composed of these three: mylandscape
, agroup
, and theitem
. Since the group is optional, items with unique
identifier can also be addressed using mylandscape
and theitem
, or just theitem
. Nivio tries to resolve the correct item and raises
an error if it cannot be found or the result is ambiguous.
Service references are required to describe a provider
relation or dataflow
.
1 2 3 4 5 6 7 8 | items: - identifier: theservice group: agroup relations: - target: anothergroup/anotherservice format: json type: dataflow label: Data Sync |