Resource Catalog
The Resource Catalog is the home for anything that would benefit being tracked in a system of record but doesn't belong in the Service Catalog, such as infrastructure assets (databases, buckets, caches, AWS accounts).
Resource Definitions
Every resource in the catalog is associated with a Resource Definition, i.e. a "type" of resource (think s3
or rds
).
Each definition requires a type
and a JSON schema that outlines the spec any resource of that type
should conform to.
A resource must be of a type
that has a corresponding Resource Definition. Each resource of that type will
have its x-cortex-definition
validated against this schema.
JSON schema for custom resource definition
You can create custom resource definitions for the custom type
. These custom resource definitions are powered by the open source
JSON Schema project. While the JSON Schema provides many different capabilities, it is typical to keep things
simple.
{
"required": [
"version",
"distribution"
],
"properties": {
"version": {
"type": "string"
},
"distribution": {
"type": "string"
}
}
}
Acceptable type
are array
, boolean
, integer
, null
, number
, object
, and string
.
Resource Catalog
There are a few different ways of getting Resources into your catalog. Using our Resource Import flow, you can import resources from cloud providers such as AWS or GCP. However, this won't work for custom resource types – you'll have to use one of the following two methods.
YAML definition
Every resource is defined as YAML. This YAML is fully compatible with
the cortex.yaml
, meaning you can specify anything for a resource that you
would for a service – including ownership, git, on-call, SLOs, etc.
There main differences between a service YAML and a resource YAML are two additional keys must be specified
in addition to what a service requires: x-cortex-type
and x-cortex-definition
.
openapi: 3.0.0
info:
title: My Database
description: This is my cool MySQL database.
x-cortex-tag: my-database
x-cortex-type: mysql
x-cortex-definition:
version: 8.0.29
distribution: percona
The x-cortex-definition
block will be validated using the resource definition associated
with the x-cortex-type
field.
If your custom Resource Definition does not have specific requirements, resource entities still need a non-null
definition specified, like x-cortex-definition: {}
.
API
You can use our standard Descriptor Upload API to upload Resource Descriptor YAML files.
GitOps
When using GitOps you can define any number of resources that are associated with
your service, e.g. a database, s3 buckets, etc in the same repository. In general, the best place to put these
resources is at your repository's root directory within .cortex/catalog
. For example a simple service might
have the structure:
.
├── .cortex
│ └── catalog
│ ├── database.yml
│ └── s3-bucket.yml
├── cortex.yaml
└── src
└── index.js
└── ...
Any file found within the .cortex/catalog
directory will be automatically picked up and parsed as a Catalog Entity.
You can define services within .cortex/catalog
if you'd like, instead of leaving it at the root. The only
requirement is that any file named cortex.yaml
or cortex.yml
is x-cortex-type: service
(which is the default
and can be left out of the file), and contains no x-cortex-definition
block.