Manage entities
Entities are the tree that holds your resources: companies, clients, environments, teams. What you set on an entity, everything below it inherits. This guide shows how to build and change the tree under Settings › Entities, where to set what each entity passes down, and how to tag resources so you can group them across the tree.
Before you begin
- You need the Entity admin role on the entity you change. To create an entity, you need it on the parent; to move one, on the entity and on its new parent.
- Plan the levels you need. The kinds of entity (tenant, client, environment, group) are labels and change no behaviour. For how inheritance works, see Entities, tags and inheritance.
In the examples, Areito Corporation is the root, Ciguapa Inc. is a client below it, and Production and UAT are its environments.
Create an entity
- Open Settings › Entities. The tree shows the entity chosen in the picker and everything below it, with the number of resources in each branch.
- On the parent, for example Ciguapa Inc., open its actions menu and select Add an entity below.
- Enter the Name, for example
Production. - Choose the Kind, for example environment.
- Optionally enter a Short name, used in paths: lower-case letters, digits and hyphens, unique across the installation. When you leave it empty, it is derived from the name. It cannot be changed later.
- Select Create.
There is only one root entity; every other entity has a parent.
Rename an entity
- Open the entity's actions menu and select Rename.
- Change the Name, and the Kind if needed. The root's kind cannot change.
- Select Save.
The short name stays as it was, so links and paths keep working.
Move an entity
Moving an entity moves everything below it, and from then on it all inherits from its new place: thresholds, Slack channels, maintenance windows, registration and roles.
- Open the entity's actions menu and select Move.
- Choose the New parent. Only entities you administer are offered, and never the entity itself or one below it.
- Select Move.
The root cannot move. The audit log records every move.
Delete an entity
You can delete an entity once nothing is left below it.
- Remove or move what it holds: child entities, resources and sources. Deleting a resource also deletes its alerts.
- Open the entity's actions menu and select Delete. The option is available only when the entity is empty.
- Select Delete to confirm. The entity's own credentials, Slack channels and role assignments are deleted with it.
Excubius refuses the deletion when the entity still has child entities, resources, sources or alerts, or when resources elsewhere use one of its credentials. The root cannot be deleted.
Set what an entity passes down
Each inherited setting has its own screen. Choose the entity in the picker, or open it from Settings › Entities.
| Setting | Where | Guide |
|---|---|---|
| Threshold defaults of every check | Settings › Entities, actions menu, Threshold defaults | Change thresholds and turn checks off |
| Roles and who gets an account | Settings › Users and roles | Manage users and roles |
| Credentials for the collector | Settings › Credentials | Store a credential for the collector |
| Slack channels | Settings › Notifications | Configure Slack notifications |
| Maintenance windows | Settings › Maintenance windows | Plan a maintenance window |
| Default theme and logo | Settings › Branch appearance | Set up the public status page |
| Public status page | Settings › Status page | Set up the public status page |
Tag resources
Tags are key:value labels on resources, such as env:prod, role:sql or client:ciguapa. A resource lives in one place of the tree, but tags let you group it with others from anywhere in the tree.
To tag a resource:
- Open the resource and select Edit. When you add a resource, the wizard has a Tags step that works the same way.
- In Tags, enter
key:valuepairs separated by spaces, for exampleenv:prod role:sql client:ciguapa. Keys use letters, digits, dot, dash and underscore, and each key appears once. - Set the Criticality, from 1 (low) to 5 (critical). It is its own field, not a tag, and it is used for routing, risk and the security score.
- Select Save.
Use at least env, role and client on every resource, and set the criticality.
To use the tags:
- In Resources, enter a Tag rule.
role:sql env:prodshows resources that have both; a key alone, such asclient, shows every resource that has that key. - On the Overview, choose the Hex view and Group by a tag key to see one group of hexagons per value.
Do it with the API
| Task | Request |
|---|---|
| Create | POST /api/v1/entities with parent_id, name, optional kind and slug |
| Rename or change the kind | PATCH /api/v1/entities/{id} with name or kind |
| Move | PATCH /api/v1/entities/{id} with parent_id |
| Delete | DELETE /api/v1/entities/{id}; answers 409 with the reason while the entity is not empty |
| Tag a resource | PATCH /api/v1/resources/{id} with tags, an object such as {"env": "prod", "role": "sql"}, and criticality |