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​
- 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.