Skip to main content

Service Descriptor

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!).

Getting Started​

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.

The basics​

A barebones spec file has the OpenAPI version, along with an info section that contains some basic details.

openapi: 3.0.0
info:
  title: My Service
  x-cortex-tag: my-service
  description: This is my cool service.

The only required fields under info are the title and the x-cortex-tag.

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.

tip

Any time you see a mention of a Service Tag, we're referring the value of x-cortex-tag in 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 info section!

FAQ​

  1. Is this descriptor file only used for microservices?
    1. 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.