Managing Catalogs
Last updated
Last updated
A catalog is a defined selection of entities. You can use catalogs to track and store information about all of the components that make up your infrastructure. This includes everything from services and domains to AWS S3 buckets and RDS, Google Cloud resources, or Azure Resources.
While entities are defined by YAML files, catalogs themselves are not defined by a YAML file and must be created in the Cortex UI. Think of catalogs as a folder containing a collection of entities, with each entity defined by its own YAML file. An entity can belong to multiple catalogs, so you can also think of a catalog as a filter that defines which entity types to group together.
In the example screen shot below, the Services page contains a list of all entities that belong to the Service catalog:
By default, Cortex comes with four built-in catalogs:
Services contains all service entities.
Infrastructure contains all entities representing your infrastructure assets.
Cortex pulls in resources directly from AWS, Azure Resources, or Google Cloud, as their corresponding types out of the box. These resources are automatically added to the Infrastructure catalog.
Domains contains all domain entities and displays them in a hierarchical view.
Teams contains all team entities and displays them in a hierarchical view alongside a leaderboard based on Scorecards.
You can choose to rename these catalogs to fit your own taxonomy, but note that the custom names of these default catalogs will not override the references to their default names throughout the app. Instead, you could choose to create additional custom catalogs.
To customize your Cortex instance to your organization's needs, you can also define custom catalogs in Cortex to represent your infrastructure. See Create custom catalogs below.
Click Catalogs from the main nav to view your list of catalogs. You must have the View catalogs permission.
You can view and manage all entities in your Cortex account under Catalogs > All Entities. You can organize entities into catalogs to make it easier to find and manage them.
On that page you can also create entity types, which determine the types entities you’ll import into Cortex.
Cortex comes with built-in entity types to get you started quickly. These entity types do not have a definition schema, and instead fetch details on demand from the original source. You can also create your own entity types.
To view all entity types, go to Catalogs > All Entities then click the Entity types tab.
On the All catalogs page, you’ll find all pre-defined and custom catalogs in Cortex.
This page will reflect the same list of catalogs you find in the Catalogs dropdown menu in the main nav.
Just like "All entities", "All catalogs" includes a search bar and a sort function, as well as a toggle for displaying or hiding Drafts.
From this page, you can create new catalogs and edit existing ones.
You can create catalogs in the Cortex UI. For each catalog, you set the criteria that determines which entities belong to that catalog. In addition, you can define custom entity types to categorize the entities that live in your catalogs.
Because catalogs are not defined by a YAML file, it is not possible to create them via a GitOps workflow.
To create, edit, and delete catalogs, you must have the Edit catalogs permission.
To create a new catalog:
At the top of the "All catalogs" page, click Create catalog.
Configure the "Create catalog" form:
Name: Enter a name for the catalog.
Description: Optionally, enter a description of the catalog.
Display icon: an icon to appear alongside the catalog throughout the app.
URL: Enter a unique URL slug.
By default, the URL slug will be generated based on the catalog’s name, but you can use the URL field to create a custom slug.
Add entity types: In this section, you will define the entities that are included in your catalog. All entities that match the criteria defined in this section will be automatically included in the catalog. To create a catalog, you need to add at least one entity type. Catalogs can include a combination of any entity types, or can include just one type.
Selection type: Choose whether to include or exclude the entity types you select.
Entity types: Select from the entity types you've created.
Include or Exclude groups: Choose groups to include or exclude.
CQL expression: Optionally, enter a specific CQL expression to fine-tune your catalog based on specific criteria.
Draft: Choose whether to save the catalog as a draft or publish it. Only admins and managers have the ability to view drafts.
Click Save catalog.
Once the catalog is created, you’ll find it under Catalogs > All catalogs, automatically populated with all entities that apply based on the entity types you've created.
To edit a catalog:
In Cortex, go to Catalogs > All catalogs. Click into the catalog you want to edit, then click Edit catalog at the top of the page.
This will bring you back to the catalog creation page, with all the details from your last save.
Make any changes necessary to the catalog.
At the bottom of the page, click Save catalog.
You can use the audit log to track changes made to any of your catalogs. Catalog updates will be listed as CATALOG in the Type column, and the updated catalog will be listed under the Entity column.
The Action column will indicate whether a catalog was created, deleted, or updated.
After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you create a custom catalog, you can set the entity type criteria.
For the default catalogs, the entity type criteria is set by default:
The Services catalog contains service entity types
The Domains catalog contains domain entity types
The Teams catalog contains team entity types
The Infrastructure catalog contains any entities that are not the types service, domain, or team.
By default, any custom entity types you create will belong to the Infrastructure catalog. If you do not want the entity type to belong to this catalog, you can add the entity type to a different catalog.
You must have the Configure appearance settings permission to configure the catalog display.
By default, catalogs will appear in alphabetical order, but you can manually adjust the order that the catalogs appear in the main nav.
Navigate to Settings > Workspace > Main sidebar to drag and drop catalogs into your preferred order:
