Input format: cloud and datacentre inventories
Run the commands below from the installation directory. See Run operator commands for how ./lens reaches the running installation and copies files into it.
One command reads all five shapes:
From the installation directory:
./lens connectors ingest --org harbour --source aws --fixture estate.jsonOn success the command prints a summary of what it wrote and exits 0; the map shows the result after the projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default. service’s next pass (about 30 s by default). A refusal names what was wrong.
--source is one of aws, gcp, azure, terraform or cmdb. Each produces infrastructure cellsCellA box on the map that stands for a team, service, supplier or AI agent. It is a unit you can inspect, not necessarily a department or a person., their containment, and the dependencies the export declares, all at the shown rungRungOne of three levels of support for a recorded value: told, shown or measured. The level appears beside the value..
The parsers were written against the template shapes below. A genuine platform export usually differs. A file that does not parse on the first day is a findingFindingA difference in the records that needs a decision. It includes its sources and can describe a slow handoff, disputed fact or missing owner. to record; the mapping is part of the engagement, not an error in your export.
How a unit reaches a cell. Every shape carries a domain tag, label or field whose value must be the id of a cell that already exists. The tag is read from the resource itself or from its immediate containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host.: the AWSAWSAmazon Web Services: a cloud platform whose account and resource exports NovusLens can read. account, the GCPGCPGoogle Cloud Platform: a cloud platform whose project and resource exports NovusLens can read. project, the Azure resource group, the CMDBCMDBConfiguration management database: an inventory of systems and the relationships recorded between them. business service. A tag higher up, on an organizational unit, a folder or a subscription, names that container’s cell but does not reach the resources under it. A resource with no tag either way is kept as unmatched infrastructure and reported.
aws
Top level: organizational_units (each id, name, optional tags.domain), accounts (each id, name, optional ou naming a unit, optional tags with domain, region, iac), resources (each name, optional account, type, region, tags.domain, depends_on list of resource names).
{
"organizational_units": [{"id": "ou-1", "name": "Operations", "tags": {"domain": "operations"}}],
"accounts": [{"id": "111122223333", "name": "bookings-prod", "ou": "Operations", "tags": {"domain": "bookings", "region": "eu-west-2"}}],
"resources": [
{"name": "bookings-api", "account": "bookings-prod", "type": "ecs-service", "depends_on": ["bookings-db"]},
{"name": "bookings-db", "account": "bookings-prod", "type": "rds"}
]
}gcp
Top level: folders (each name, displayName, optional labels.domain), projects (each projectId, optional displayName, projectNumber, folder naming a folder’s display name, labels with domain and region), resources (each name, optional project, type, region, labels.domain, depends_on).
{
"folders": [{"name": "folders/100", "displayName": "Customs", "labels": {"domain": "customs"}}],
"projects": [{"projectId": "harbour-customs-prod", "folder": "Customs", "labels": {"domain": "customs", "region": "europe-west2"}}],
"resources": [{"name": "customs-filing-run", "project": "harbour-customs-prod", "type": "cloud-run", "depends_on": ["customs-declarations-db"]},
{"name": "customs-declarations-db", "project": "harbour-customs-prod", "type": "cloud-sql"}]
}azure
Top level: management_groups (each id, displayName, optional parent, tags.domain), subscriptions (each subscriptionId, displayName, optional managementGroup, tags.domain), resource_groups (each name, optional subscription, location, tags with domain and iac), resources (each name, optional resource_group, type, location, tags.domain, depends_on).
{
"management_groups": [{"id": "mg-harbour", "displayName": "Harbour", "parent": null}],
"subscriptions": [{"subscriptionId": "0000-wh", "displayName": "Warehousing Prod", "managementGroup": "Harbour", "tags": {"domain": "warehousing"}}],
"resource_groups": [{"name": "rg-wms", "subscription": "Warehousing Prod", "location": "uksouth", "tags": {"domain": "warehousing"}}],
"resources": [{"name": "wms-app", "resource_group": "rg-wms", "type": "Microsoft.Web/sites", "depends_on": ["wms-sql"]},
{"name": "wms-sql", "resource_group": "rg-wms", "type": "Microsoft.Sql/servers"}]
}terraform
The state file itself. Read per resource: type, name, optional module, provider, and the first instance’s attributes (tags or labels for domain, region or location) and dependencies.
{
"version": 4,
"resources": [
{"module": "bookings", "type": "aws_ecs_service", "name": "api",
"provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
"instances": [{"attributes": {"region": "eu-west-2", "tags": {"domain": "bookings"}},
"dependencies": ["module.bookings.aws_db_instance.main"]}]},
{"module": "bookings", "type": "aws_db_instance", "name": "main",
"provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
"instances": [{"attributes": {"region": "eu-west-2", "tags": {"domain": "bookings"}}}]}
]
}cmdb
Top level: configuration_items. Each needs ci_id and ci_name; optional ci_class, business_service (the cell), datacentre, and a dcim object of rack and power residue. A CMDB export declares no dependencies; those come from telemetryTelemetryMeasurements and activity records sent by a running system, such as ticket timings, network traffic or workflow results. later.
{
"configuration_items": [
{"ci_id": "CI0001", "ci_name": "wms-db-01", "ci_class": "server", "business_service": "warehousing", "datacentre": "felixstowe-dc1"},
{"ci_id": "CI0002", "ci_name": "wms-app-01", "ci_class": "server", "business_service": "warehousing", "datacentre": "felixstowe-dc1"}
]
}What a re-run does
| Situation | What happens |
|---|---|
| Stable identity | The resource’s name, slugged, not its cloud id. Group cells are named by provider and group. |
| The same export twice | The same artifact; cells and edges written again with the same values. |
| A resource whose domain tag changes | Re-parented under the new domain. |
| A renamed resource | A new cell; the old one stays. |
| Two resources with the same name in different accounts or projects | Both are held out of the map and a duplicate-unit-id finding names them. Qualify the names or split the export. |
| A resource or dependency omitted from the export | Untouched. Nothing is ever removed from the implementation layer; an export cannot say a resource is gone. |
| A resource the provider reports and the infrastructure codeInfrastructure codeFiles that describe the computing resources an organisation intends to create and how they should be configured. does not describe | An estate-drift finding names both accounts. Neither is corrected. See Estate drift. |
| A resource the code declares and the provider does not report | The same: a drift finding, both accounts kept. |
| A tag naming a domain the map lacks | The resource is not created; an undeclared-domain finding opens. Re-run once the cell exists. The finding does not close by itself. |
| Cross-provider edges | Only after the link command, which re-writes them on each run. |
| When visible | After the projection service’s next pass. |