Skip to main content

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.

resource-definitions

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.