External Documentation
Cortex is your source of truth to external documentation - instead of digging through your wikis, you can aggregate links and API documentation into one easily accessible place.
Documentation is easily accessible through the Catalog, on the homepage for each service.
Links​
You can easily add links to docs, runbooks, tech specs, dashboards, and more.
The Service Descriptors a list of Link
objects:
x-cortex-link:
- name: Human Readable Name
type: runbook
url: https://cortex.io
description: Optional Description
The value of type
can be anything you want – examples include:
runbook
documentation
logs
dashboard
metrics
healthcheck
tip
You can look up links easily using our Slackbot!
Swagger/OpenAPI Documentation​
API documentation is a special case. Cortex supports displaying Swagger/OpenAPI specs for each service, in the "API Explorer" tab. There are a few ways of adding API specs to Cortex
Service Descriptor​
You can use your Service Descriptor file as an OpenAPI spec file. Since the Service Descriptor file extends the OpenAPI spec, you can simply implement the spec directly in this file.
Existing Specs​
If you have existing or external specs you want to display in the API explorer (e.g. from Swagger
Hub, GitHub Raw URL, etc), simply add a URL to the spec file (JSON or YAML) as an x-cortex-link
, with type openapi
.
The spec will then automatically show up in the API Explorer.
Relative links​
If you have specs checked into your service's Git repository, you can embed it by adding it as a
relative URL with type openapi
, like:
x-cortex-link:
- name: My Spec
type: OPENAPI
url: ./docs/my-openapi-spec.yaml
Git-Driven Markdown Docs​
Cortex automatically embeds markdown files from the docs
folder of your repo in the Catalog. These docs show up under the "Docs" tab.
Embed Dashboards​
Cortex supports embedding charts directly into the Catalog for quick access, making the Catalog a single pane of glass for your architecture.
x-cortex-dashboards:
embeds:
- type: datadog | grafana | newrelic
url: https://blahblah.com
The type
field is an enum of three types. This field is used when generating screenshots for certain Slack integration points.
If you do not plan to use this feature, feel free to choose any type as it's ignored entirely when embedding in the catalog.
The url
field is the src
value for the iframe
embed generated by your dashboard tool.
tip
If using Grafana, note that you can only embed charts, not dashboards. If you're seeing errors in your Grafana embeds, make sure your Grafana instance has embeds enabled.