Every service in Cortex is described by a YAML file called the Cortex Service Descriptor, also referred
to as a service's
Cortex YAML (naturally stemming from
cortex.yaml, which is filename that
powers the GitOps approach!).
The Service Descriptor is a fully compliant OpenAPI 3 spec file, with our own Cortex-specific extentions that we've added.
You can still use Cortex if you don't use OpenAPI/Swagger!
We use the OpenAPI spec as a base for service metadata, since it's an open spec with official support for extensions. That lets us extend it to be a service descriptor spec with optional usage of actual OpenAPI fields.
A barebones spec file has the OpenAPI version, along with an
info section that contains some basic details.
title: My Service
description: This is my cool service.
The only required fields under
info are the
title and the
You'll see us refer to the "Service Tag" throughout the docs. The Service Tag is a unique identifier that's used through Cortex, for example to declare dependencies on other services or to look up information using the Slackbot.
Any time you see a mention of a Service Tag, we're referring the value of
the Service Descriptor.
Adding more information
Any additional metadata you want to add to your descriptor belongs in the
info section. Throughout the
docs, you'll see snippets that start with
x-cortex-* – make sure to add this to the
- Is this descriptor file only used for microservices?
- You can use Cortex to describe REST services, kafka consumers/producers, libraries, modules within a monolith, etc. Any entity that could be described as a logical module should live in Cortex.