Skip to content

Integrations

Git

Our git integrations enable functionality such as a GitOps powered approach to service catalog management, scorecard rules, and more.

Github

The Github integration enables:

  • Automatically parsing cortex.yaml on every merge to master or the default branch (when using the app)
  • Dashboard support (latest commits, contributors)
  • Scorecard rules (# of issues, PRs, etc)
  • Alert context (for example, Cortex can slack you the latest commits when a Pagerduty alert is triggered)

We suggest installing our Github App for the most robust functionality.

Additionally, you can authenticate with a Github Personal Access Token.

You can also authenticate with OAuth, in which case you will have to manually upload the file to Cortex, but the dashboard functionality will still work.

You can find each option at Settings → Github.

If either the OAuth app or Personal Access Token are configured along with the Github app, we will use the Github app for all functionality.

Gitlab

The Gitlab integration enables:

  • Automatically parsing cortex.yaml on every merge to master or the default branch (when webhooks are enabled)
  • Dashboard support (latest commits, contributors)
  • Scorecard rules (# of issues, PRs, etc)
  • Alert context (for example, Cortex can slack you the latest commits when a Pagerduty alert is triggered)

Setup:

  1. Create a personal access token through your Gitlab dashboard with api permission.
  2. Add the token (and an optional host) in Gitlab settings on the Cortex dashboard at Settings → Gitlab.

This will allow Cortex to read the cortex.yaml file from the repository. To enable automatic processing of changes when the file is changed, follow setup instructions in Updating Cortex.

Bitbucket

The Bitbucket integration enables:

  • Automatically parsing cortex.yaml on every merge to master or the default branch (when using the app)
  • Scorecard rules (# of issues, PRs, etc)
  • Alert context (for example, Cortex can slack you the latest commits when a Pagerduty alert is triggered)

Get started by installing our Atlassian Connect App.

Kubernetes

Our Kubernetes integration allows you to:

  • Easily one-click import services from multiple k8s clusters into Cortex
  • Build scorecard rules to enforce your org's k8s best practices
  • View information from k8s in the service homepage, letting you easily access information such as active replicas, currently deployed versions, resource requirements, and more.

The k8s integration is powered by a lightweight, custom agent we've developed. The agent is deployed into your cluster, and periodically sends information back to Cortex.

Basics

The k8s agent collects information from your cluster (such as the current list of deployments. Using a Cortex API key, it sends this information back to Cortex, where it's exposed through the dashboard.

The k8s agent is lightweight and adds negligible impact to your cluster. It's essentially a simple cron job that collects and sends information back to your Cortex account.

The agent collects information every five minutes, by default.

Deployment

To deploy the agent, you can use our helm chart which allows for an easy installation. The helm chart is provided to you upon request.

Security

Security of your cluster is extremely important to us (and to you!). The agent's push-model ensures that you do not need to expose your cluster to the public internet.

Additionally, the helm chart comes with a predefined ClusterRole that provides the correct RBACs, which are:

  • Permissions: ["get", "watch", "list"]
  • On resources: ["deployments", "services", "pods", "replicationcontrollers"]

Communication out of the cluster to Cortex happens over HTTPS. There is no inbound traffic to the agent.

Okta

The Okta integration enables:

  • Adding ownership (i.e. team and team members) information to services
  • Automatic updates of system owners when groups change in Okta

Setup:

  1. Fetch your Okta domain by logging into Okta, and get the prefix in the url. For example, our URL is https://**{cortex}**.okta.com/app/UserHome, where cortex is the prefix.
  2. Create an API token by logging into Okta. You must have administrator privileges for the Okta account.

This will allow Cortex to keep teams, users, and groups up to date through Okta.

Slack

We have a Slack integration that provides Scorecard rules and allows for us to message service owners about upcoming deadlines -- as well as a Slackbot, to quickly query your services for information.

Configuration Steps

Navigate to the settings page and click "Add to Slack", and you'll be prompted to add our Slack app to your workspace:

Slack app verification

Slackbot

We have a list of commands you can use with our Slackbot to quickly query service metadata and scorecard scores. The service tag refers to the unique x-cortex-tag set on each service descriptor.

OIDC

We support login through OIDC through Okta or Google. Please contact us if this feature is not enabled on your account.

Supported Features

  • Custom OpenID authentication through Okta or Google initiated by the login page.

Requirements

  • As of now, all customers can set custom OIDC connectors.

Configuration Steps

After signing through our default Google OAuth provider, you can set new OpenID connectors through our settings page, under OpenID Connector. We currently support connectors from Okta and Google only.

OIDC Settings

Adding New OIDC Connection

To add a new OIDC connection, you'll need to setup a new OAuth application through your identity provider. You must enter your new application's Client ID and Client Secret through the settings page, as well as the Issuer URI , in the case of Okta connections.

How to Setup OAuth Application

Google

To setup a new Google OAuth app, you can follow the instructions here.

Add https://cortexapp.auth0.com/login/callback as an authorized redirect URI, and copy over the Client ID and Client secret. The issuer URI will be automatically filled in.

Google OIDC app

Okta

To setup a new Okta application, you can install our application from Okta's OIN.

Finding the Issuer URI

Instructions for finding your Okta issuer URI can be found here. It should look like https://{okta domain}.okta.com

Finding the Client ID and Client Secret

When you install the app via the OIN, you'll find an application titled Cortex in your Okta admin console under the "Applications" tab.

Okta OIDC app

Click into it and on the "General" tab if you scroll to the bottom you'll find your new application's Client ID and Client secret .

Okta OIDC app Okta OIDC app

Azure Active Directory

To setup a new AD application, you can following the instructions here, and make sure to add https://cortexapp.auth0.com/login/callback as an authorized redirect URI.

Next, navigate to the "Certificates & secrets" tab and create a new client secret and copy it down.

Azure OIDC client secret

After that, navigate to the "Overview" tab, noting down the Application (client) ID.

Azure OIDC client id

From there, click "Endpoints" and copy the OpenID Connect metadata document, just up to /v2.0, which will give you the issuer URL. The issuer URL should be of the format https://login.microsoftonline.com/<uuid>/v2.0.

Then navigate to the settings page and enter the above, choosing type AZURE.