Adding external documentation
Last updated
Last updated
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:
If you have configured the Slack integration, you can use Slack Bot commands to list an entity's docs links directly in Slack.
Links appear on an entity details page in the Links & docs section:
On entities, you can add links to docs, runbooks, tech specs, dashboards, and more.
Before editing an entity via the UI, make sure that UI editing is enabled on the Entities settings page under the GitOps tab.
In Cortex, navigate to an entity.
In the upper right corner of the entity details page, click Configure entity.
Click the Links tab.
Click +Add.
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.
Click Add.
You can quickly look up links using the Cortex Slack Bot.
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.
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.
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.
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:
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.
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.
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)
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:
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.
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.
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.
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.
