While there are endless options for customizing Cortex to your exact needs, we’ve made it easy to get started quickly. In about 10 minutes, you can have all the essentials set up to gain meaningful insights into your organization and software. 

Integrations

The first step is establishing some key integrations. To start, we recommend linking a cloud provider, Git provider, and an identity provider — this is the minimum you’ll need to start getting meaningful information in your catalog.

Setting up a cloud provider

To set up a cloud provider, navigate to Integrations in the Settings page, and select All Integrations. Before you’ve set up integrations, you’ll see No active integrations yet. Check the list below to get started. appear under Active Integrations — this section will populate as you add integrations.

Cortex has support for a number of providers, including Google Cloud, Azure Resources, and AWS. For our purposes, let’s add an AWS integration for our cloud provider by clicking Integrate next to AWS.

This will take you to the AWS page under Integrations. Select Add AWS Configuration to set up the integration.

This will open a modal window with instructions for creating an IAM policy for AWS and a JSON you can copy as a starting place. You’ll then need to associate that policy with a role. Then, enter your AWS account ID and the IAM role in the appropriate fields.

Once the integration is set up, you can select Test all configurations to make sure the configuration is valid. 

Setting up a Git provider

Next, we’ll want to set up a Git provider — in this example, we’ll set up GitHub, but Cortex also supports GitLab, Bitbucket, and Azure DevOps. You can add GitHub, or any of these providers, by going through All integrations, or you can select GitHub directly from the side menu.

In this case, we just need to install the Cortex app for GitHub. Click Configure and follow the prompts to integrate GitHub. 

You’ll be asked to associate the app to a particular account, and you can choose to integrate all repositories or select specific repos.

Setting up an identity provider

To set up your identity provider, you can use OpenID Connector. In our example, we’re integrating with Okta. 

You can find the Identifier and Secret from the Cortex app within Okta. Under Issuer, enter the URL for your instance of Okta.

Next, we’ll navigate to the Okta integration settings to link with Okta through an API token. This will enable Cortex to pull in data about Teams, and will establish a two-way continuous integration so the members of each Team stay updated. 

Populating the catalogs

Now that our core integrations are set up, we can start populating our catalogs. The service, resource, and team catalogs can all be found under Catalogs in the navigation bar.

Service catalog

Open the service catalog and click Import Service. 

Through Service Discovery, Cortex will automatically find services through the integrations you’ve set up. In this example, we can import services from AWS or GitHub, since we just set up both of those integrations. 

Scroll down and click Continue. On the next page, you can select all the services you want to import at this stage. Once you’ve selected services for import, select Add services. 

These services will then populate in your service catalog. You can click into any of them to view more details. Because we imported these services from GitHub, we can see the GitHub repo associated with the service. The Recent activity section shows populates events from GitHub.

Resources

The process for importing resources is very similar to adding services. Select Import Resource from the resource catalog to proceed to the discovery flow.

Select Import from cloud provider to populate discovered resources for import, and select all the resources you want to import at this stage. In our example, we’re importing from AWS.

Once you’ve selected all the resources you want to import, select Add resources. The resources will then populate in your resource catalog.

Just like with services, you can see information from the cloud provider within that resource’s home page. 

Teams

Just like with services and resources, we’ll start by selecting Create Team from the team catalog. 

Next, select Backed by identity provider to discover teams from your integrations. The teams that populate below will include a note on where the team is sourced. You can have multiple sources of truth for team members, but in this example, we’ll stick to Okta, since we know that information is most up-to-date.

Once the Engineering team is imported, all of its members and their contact information will appear under Members on that team’s page. 

Because we integrated with Okta via API earlier, this information will stay updated, even as team members change in Okta over time.

Setting up ownership

Now that we have a team set up, we can assign ownership for our services — this is a critical step for getting the most out of Cortex. 

Go back to the service catalog and select a service to assign ownership. Select Configure service and go to the Owners tab to add a team. 

Next steps: Adding data and integrations

Now that we have the essentials set up, we’ll take a look at how to add integrations going forward. Go back to Settings to add an integration — for our example, we’ll integrate with Jira. 

To integrate with Jira, we’ll need a subdomain, which you can find in your Jira URL, and an API token.

Once the integration is set up, we can see data from Jira within our service catalog. Select any service and open the Integrations tab in the sidebar, and then click Jira Tickets.

Cortex will automatically tie any tickets discovered in Jira to this service, and you’ll be able to see them all on this page. Cortex will use the service’s identifier (in this case app-direct) to link the tickets to the service.

Every service has an OpenAPI spec in Service YAML, so if there’s not a clean match between the identifier and how the service is listed in Jira, you can configure the mapping directly.