Skip to main content

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

You can easily add links to docs, runbooks, tech specs, dashboards, and more.

The Catalog 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!

API Documentation​

API documentation is a special case. Cortex supports displaying Swagger/OpenAPI/AsyncAPI specs for each entity, in the "API Explorer" tab. There are a few ways of adding API specs to Cortex

Swagger/OpenAPI Documentation​

Catalog Descriptor​

You can use your Catalog Descriptor file as an OpenAPI spec file. Since the Catalog 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.

If you have specs checked into your 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

In addition to providing the ability to link to specs within the service repo, we also allow for links that reference other Git repositories that aren't necessarily associated with your entity but still within your organization.

info

Power users can also specify a branch parameter between the second and the third colon separated group, i.e. in the form github:org/repo:branch:path/to/file. If this parameter is omitted we will use the repository's default branch.

x-cortex-link:
  - name: My GitHub Spec
    type: OPENAPI
    url: github:org/repo:path/to/file
x-cortex-link:
  - name: My GitLab Spec
    type: OPENAPI
    url: gitlab:namespace/project:path/to/file
x-cortex-link:
  - name: My Azure DevOps Spec
    type: OPENAPI
    url: azuredevops:project/repository:path/to/file
x-cortex-link:
  - name: My Bitbucket Spec
    type: OPENAPI
    url: bitbucket:workspace/repo:path/to/file

Upload via API​

If you know your entity tag, you can also send your OpenAPI JSON or YAML file to our public endpoint for managing OpenAPI documentation /api/v1/catalog/{tag}/documentation/openapi for each of your entities. One API doc per entity can be uploaded and it will automatically show up as an API Doc entry in the dropdown in the API explorer.

The request body is the following, in JSON format. See API Docs for authentication details.

FieldTypeDescription
specstringThe json or yaml as a string
Converting YAML or JSON to string

You can use a lightweight utility like jq to take your yaml/json and generate a string that can be used for your request:

e.g. $(cat my_file.yaml | jq -Rsa)

AsyncAPI Documentation​

Existing Specs​

If you have existing or external specs you want to display in the API explorer (e.g. from GitHub Raw URL, etc), simply add a URL to the spec file (JSON or YAML) as an x-cortex-link, with type async_api. The spec will then automatically show up in the API Explorer.

If you have specs checked into your Git repository, you can embed it by adding it as a relative URL with type async_api, like:

x-cortex-link:
  - name: My Spec
    type: ASYNC_API
    url: ./docs/my-spec.yml

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 (optional)
      url: https://blahblah.com

The type field is an optional enum of three types. The type field is used when generating screenshots for certain Slack integration points. If you do not plan to use this feature feel, leave the type field blank and only add the url, 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

Note that you can only embed charts, not dashboards. Your tool of choice likely has an option for generating embed URLs for individual charts, which is what you'd want to use here.

If you're using Grafana and seeing errors in your Grafana embeds, make sure your Grafana instance has embeds enabled.