# Catalog overview

EvoHub Catalog keeps your services, their owners and their promises in one place, and checks them against what is actually running. Your teams declare each service once: who owns it, how critical it is, where its runbook lives. An [EvoHub agent](https://docs.evohub.io/agent-overview.md) in each cluster or VM, or a read-only [cloud account](https://docs.evohub.io/catalog-cloud-accounts.md), reports what runs there. Catalog matches the two, and the gaps show up on their own: workloads nobody owns, services declared but not running, and environments that have drifted apart.

Catalog lives under **Catalog** in the EvoHub console.

## Declared and observed

Everything in Catalog is one of two kinds, and neither side can write the other's:

- **Declared**: what people say. Services, their owner team, tier, lifecycle and links, tiers and their SLA targets, and environments. Only people change these.
- **Observed**: what agents and cloud accounts report. Resources, applications, images, their history and the map. These are read-only: they change when your infrastructure does.

The one place a person decides something about an observation is which service it belongs to. That is what the [match queue](https://docs.evohub.io/catalog-matching-and-drift.md) is for.

## Concepts

### Environment

An environment is one place you run software, such as a production cluster, a staging cluster or a group of VMs. You create environments yourself under **Catalog → Environments and agents**, each with a **Name** (for example `eu-prod`), a **Kind** (`prod`, `staging`, `dev` or `other`) and an optional description.

Every agent and every cloud account reports into exactly one environment, chosen when you install or connect it. Several agents can report into the same environment, for example one per VM. An environment cannot be deleted while something still reports into it.

### Service

A service (called a *component* in the API) is something your teams build and run, declared by a person. It has:

| Field | What it is |
| --- | --- |
| **Name** | How it is shown, for example "Payments API". |
| **Slug** | Its identifier, for example `payments-api`: lowercase letters, digits and hyphens. It is used in links and annotations and **cannot change later**. |
| **Kind** | Service, library, database, website, job or other. |
| **Lifecycle** | Experimental, production, deprecated or retired. |
| **Owner team** | The team that answers for it. |
| **Tier** | How critical it is, from your organization's [tiers](https://docs.evohub.io/catalog-tiers-and-sla.md). |
| **Repository**, **Docs**, **Runbook** | Links, shown on the service's page. They must be `http` or `https` addresses. |

A service can also have an optional RACI (responsible, accountable, consulted, informed). See [Tiers and SLA reports](https://docs.evohub.io/catalog-tiers-and-sla.md#responsibilities).

Deleting a service removes the declaration only. Its resources stay and show up as unowned.

### Resource

A resource is one thing an agent or a cloud account saw: a Deployment, a Service, an Ingress, a Node, a systemd service on a VM, an EC2 instance, a bucket. Each resource has a status:

| Status | Meaning |
| --- | --- |
| **live** | The last sweep saw it. |
| **missing** | The last complete sweep did not see it. |
| **gone** | It has been missing for a day. |
| **stale** | The agent that reports it has stopped reporting, so nobody knows. |

A resource that was missing or gone and is seen again is live again, with its history intact. Absence is never taken as deletion straight away: a sweep that could not list everything marks nothing missing.

Each resource keeps its history. Open one under **Inventory → Resources** to see its current state, every change the sweeps observed with a before-and-after diff, what it connects to, and, for a workload, how it is running right now.

### Application

An application is what runs together. Catalog groups resources the way your cluster already groups them: an Argo CD application, a Helm release or an `app.kubernetes.io/instance` label names one; otherwise each workload is one, together with its Services, the Ingresses routing to them, its autoscaler and its volume claims. On a VM, an application is a Compose project, a container, or a systemd service that is not part of the operating system.

Ownership is decided per application: putting an application in a service puts every resource in it there too, now and as resources come and go. Applications are listed under **Inventory → Applications**, by namespace.

### Health

From the agent's live reports, each workload, application and VM service has a health: **healthy**, **degraded** (fewer pods ready than wanted, or containers failing), **down** (wants pods, none ready), **idle** (scaled to zero) or **unknown** (no report in the last ten minutes).

### Match queue

The match queue holds proposals that an application belongs to a service. A resource carrying the `evohub.io/component` annotation is bound to that service without asking; everything else is only ever proposed, strongest first, for a person to accept or reject. A rejected pair is never proposed again. See [Matching and drift](https://docs.evohub.io/catalog-matching-and-drift.md).

### Drift

Drift is where what was declared and what runs disagree: resources nobody owns, services with nothing running, a service running in staging but missing from production, staging and production on different images, resources that disappeared, workloads that are not ready, and cloud machines that open an admin port to the internet. See [Matching and drift](https://docs.evohub.io/catalog-matching-and-drift.md#drift).

### Tier and SLA report

Tiers are your organization's own levels of criticality, each with SLA targets: availability, and response and resolution times per On-Call severity. Each service takes its tier's targets and can change any of them for itself. Every month, Catalog measures each service against its targets, from the Uptime monitors and On-Call integrations tied to it. See [Tiers and SLA reports](https://docs.evohub.io/catalog-tiers-and-sla.md).

## The console

The Catalog navigation has three sections. Each entry shows only to people whose role can read it.

| Section | Page | What it shows |
| --- | --- | --- |
| Catalog | **Overview** | How everything the agents report is running, what needs attention, how much has an owner, and recent changes. Each number opens the list behind it. |
| | **Services** | The declared services, with filters by owner, tier, lifecycle and kind. Waiting match proposals are counted on this entry. |
| | **Map** | Applications by namespace, coloured by health, owner or tier. Open one for its tree, down to each pod. Cloud accounts are drawn region by region. |
| Inventory | **Applications** | Applications by environment and namespace. |
| | **Resources** | Everything observed, with filters for kind, status, namespace, image and unowned resources. |
| | **Images** | Every container image in use, most used first. |
| Settings | **Environments and agents** | Your environments and which agents report into each. |
| | **Tiers and SLAs** | Your tiers and their targets. |

**Drift** (**All drift**) and the **Match queue** (the suggestions waiting) open from the Overview. From the Overview you can also export the whole inventory, every asset with its service, owner, tier, SLA and RACI, as CSV or JSON for an audit.

Agents and cloud accounts belong to the organization rather than to Catalog, so they are managed under **Organization → Agents** and **Organization → Cloud accounts**.

## Billing

Catalog is priced per watched environment: each environment an agent or a cloud account reports from is metered at **11 EvoHub tokens a day, about $5 a month**, however many clusters or machines are in it. Services, agents, cloud accounts, the resources they discover, the map, drift and SLA reports are free. Your organization's free monthly allowance applies. See [How billing works](https://docs.evohub.io/how-billing-works.md).

## Related

- [Get started with Catalog](https://docs.evohub.io/catalog-getting-started.md)
- [Matching and drift](https://docs.evohub.io/catalog-matching-and-drift.md)
- [Tiers and SLA reports](https://docs.evohub.io/catalog-tiers-and-sla.md)
- [Cloud accounts](https://docs.evohub.io/catalog-cloud-accounts.md)
- [Catalog permissions](https://docs.evohub.io/catalog-permissions.md)
- [EvoHub Agent](https://docs.evohub.io/agent-overview.md)
- [Catalog API](https://docs.evohub.io/catalog-api.md)