Adding external documentation

Cortex is your source of truth to external docs. Instead of digging through wikis and other resources, you can aggregate docs 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 dashboard charts

If you have configured the Slack integration, you can use Slack Bot commands to list an entity's docs links directly in Slack.

View links on an entity

Links appear on an entity details page in the Links & docs section:

Click "Links & docs" on the left side of an entity page.

Add links to an entity

On entities, you can add links to docs, runbooks, tech specs, dashboards, and more.

Cortex UI

Before editing an entity via the UI, make sure that UI editing is enabled under Settings > GitOps.

1. In Cortex, navigate to an entity.

2. In the upper right corner of the entity details page, click Configure entity.

3. Click the Links tab.

4. Click +Add.

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.

     • Learn more about OpenAPI, AsyncAPI, and dashboard chart types below.

   • Name: Enter a name for the link.

   • URL: Enter the URL.

   • Description: Add a description of the link.

6. Click Add.

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. See the sections below on this page describing OpenAPI, AsyncAPI, and dashboard charts.

You can quickly look up links using the Cortex Slack Bot.

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 Links & docs page in an entity's sidebar.

Cortex uses the React markdown library for rendering the documents.

Documentation types

When adding links to an entity, Cortex supports embedding OpenAPI or AsyncAPI specs, embedding specs from your repository, adding relative links to a repository that isn't associated with the entity, and embedding charts (from Datadog, Grafana, New Relic, or other sources). You can also create a custom type while adding a link.

Cortex supports displaying Swagger/OpenAPI or AsyncAPI specs for each entity in the API explorer on an entity details page. You can also authorize your API and run queries directly in the API explorer.

OpenAPI docs

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.

You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the x-cortex-link block, with the type openapi.

Embed specs from a git repository

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.

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.

Relative link YAML examples

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

Adding OpenAPI via the Cortex API

Using your entity tag, you can also send your OpenAPI JSON or YAML file to the public endpoint for managing OpenAPI documentation /api/v1/catalog/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 docs

You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the x-cortex-link block, with the type async_api.

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

Embedded dashboards

Cortex supports embedding charts from Datadog, Grafana, or New Relic directly into an entity for quick access. To view embedded charts, click the Dashboard page in the entity's sidebar.

x-cortex-dashboards:
  embeds:
    - type: datadog | grafana | newrelic (optional)
      url: https://example.com

• The type field is an optional enum of three types: datadog, grafana, or newrelic.

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

Note that you can embed individual charts, not dashboards.

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

Embed content from other sources

It is possible to display content from a source other than Datadog, Grafana, or New Relic. To do this, do not specify an option for the type field. The URL you add must be publicly accessible or provide cross-platform authentication for Cortex to view and display the iframe. For example, if the content is accessible via VPN, then you should be able to view it in Cortex while on the VPN.

Accessing docs links via Slack

If you have configured the Slack integration, you can use Slack Bot commands to list documentation directly in Slack:

• /slack links <tag-or-id> to list all documentation links for an entity

• /slack links [type] <tag-or-id> to list specific types of documentation links for an entity

The type corresponds to the type of documentation (e.g., openapi, documentation, etc.). Replace <tag-or-id> with the entity's tag or ID.

For example:

• To list all documentation links for an entity with ID en29f044598b112345, you could run the following command in Slack: /cortex links en29f044598b112345

• To list the OpenAPI specs for an entity with tag plugin-extension, you could run the following command in Slack: /cortex links openapi plugin-extension

The Slack Bot links command works for any docs links listed under x-cortex-links. Note that it does not list the charts listed under x-cortex-dashboards.