External documentation

Cortex is your source of truth to external documentation. Instead of digging through wikis and other resources, you can aggregate documentation on the relevant entities in Cortex in the following ways:

• Adding links to an entity
• Displaying Swagger, OpenAPI, or AsyncAPI specs on an entity
• Embedding git-driven markdown
• Embedding dashboards

Add links to an entity

On entities, you can add links to docs, runbooks, tech specs, dashboards, and more. Links appear on an entity details page under the Links section.

Entity descriptor

In the entity descriptor, add a list of link objects:

x-cortex-link:
  - name: Human Readable Name
    type: runbook
    url: https://cortex.io
    description: Optional Description

name, type, and url are required. The value of type can be defined based on your organization's preferences. Common examples include dashboard, documentation, healthcheck, logs, metrics, and runbook.

Via the Cortex UI

Before editing an entity via the UI, make sure that UI editing is enabled on the Entities settings page under the GitOps tab.

1. In Cortex, navigate to an entity.
2. In the upper right corner of the entity details page, click Configure entity.
3. On the left, click Links.
4. Click Add link.
5. Configure the link:
   • Type: Select the type of link.
     • To create a new type, enter the type name then click the name in the dropdown.
   • Name: Enter a name for the link.
   • URL: Enter the URL.
   • Description: Optionally add a description of the link.
6. Click Save link.
7. Click Save.

tip

You can look up links easily using our Slackbot!

Add API documentation

There are several options for embedding API documentation. Cortex supports displaying Swagger/OpenAPI or AsyncAPI specs for each entity in the "API Explorer" tab of an entity. You can also authorize your API and run queries directly in the API explorer.

Swagger/OpenAPI documentation

Entity descriptor

You can use your entity descriptor file as an OpenAPI spec file. As mentioned in the documentation on entities, the entity descriptor file extends the OpenAPI spec, so you can 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), 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 Git repository, you can embed it by adding it as a relative URL with type openapi. For example:

x-cortex-link:
  - name: My Spec
    type: OPENAPI
    url: ./docs/my-openapi-spec.yaml

Relative links in another repo

In addition to providing the ability to link to specs within the service repo, Cortex also allows 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, 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

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

Field	Type	Description
spec	string	The 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), 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.

Relative links

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

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 or from the root directory. If Cortex detects relevant files, these docs show up under the Integrations > Documents tab on the entity details page.

Cortex uses the React markdown library for rendering the documents.

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://example.com

• The type field is an optional enum of three types.
• The url field is the src value for the iframe embed generated by your dashboard tool.
  • You must use your tool's embed URL for individual charts.

The type field is used when generating screenshots for certain Slack integration points. If you do not plan to use this feature, leave the type field blank and only add the URL, as it's ignored entirely when embedding in the catalog.

tip

Note that you can only embed charts, not dashboards.

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