# CloudZero Identifiers

The **cloudzero-identifiers** project contains definitions and APIs for managing normalized [resource](docs/czrn.md), [relationship](docs/czrel.md), and [statistic](docs/statistic-id.md) identifiers. These identifiers represent strong domain concepts and are encountered across nearly every CloudZero system and feature including Reactor, Billing, and the System Map.  These identifiers also have well-defined and strict specifications.

For best results, please read the [Domain Glossary](https://cloudzero.atlassian.net/wiki/spaces/ENG/pages/354189365/Domain+Glossary) for an introduction into some of the core concepts in the CloudZero Domain.


#### Initialize Dependencies

Create a `virtualenv` using the tool of your choice, e.g. `uv`:

```
uv venv -p 3.12.7
source .venv/bin/activate
```

Alternatively, save this in your `.zshrc` or `.bashrc` and run `venvall` to start a virtual environment:

```shell
alias venvactivate="source .venv/bin/activate &> /dev/null || source venv/bin/activate &> /dev/null || true"
venvactivate
alias venvcreate="uv venv ./.venv"
alias venvall="venvcreate && venvactivate"
```

## When to Use this Library
If you are building new features, odds are you will need to use some part of this library.  The Reactor's job in the CloudZero ecosystem is to translate and normalize the domains of cloud providers like AWS so that we can make magic happen downstream in Core.  Hence, the Reactor features are often responsible for creating identifiers using this library.  Features in Core like Billing and Graph7 most often use this library to validate, store, and analyze the identified entities.

## When to Change this Library
So you think you need to modify this library?  Here are some valid reasons to do so:
* AWS launches a new service that we've not seen before and we need to give identifiers to its resources
* You've noticed an ARN in the logs that we're not properly parsing
* A new resource type is discovered in the wild that we're not processing
* Fixing a bug in an identifier.  Identifiers are supposed to be immutable under ideal circumstances, but an immutable ID that's wrong is just as bad.  Consider it an act of swapping two immutable values; phasing out the old broken one and using the new correct one.  This is something that should be done carefully.
* We need to create a new CloudZero-specific resource to better model the cloud.
* Something needs to be updated in the documentation
* Something performs poorly in production and we have a better idea (be prepared to prove this with benchmarks!)
* A new function on an identifier is necessary (emphasis on the *necessary*).  General use across multiple projects should be demonstrated first.
* A new type of global identifier is introduced.  This should not happen often.

Breaking changes to the API are generally frowned upon.  Instead, version the internal API and give consumers the option to use the new one - but maintain the old one.

# API Reference Documentation

The following identifiers are covered in detail in the following main sections.  You'll get information on basic concepts, API usage, and advanced deep-dives.
* [CloudZero Resource Names (CZRN)](docs/czrn.md)
* [CloudZero Relationships (CZREL)](docs/czrel.md)
* [CloudZero Statistic IDs](docs/statistic-id.md)
