Cortex makes it easy for you to import services so that you can get started right away. When you open Cortex, you'll be taken to the service catalog. You'll see the option to Import Service next to the search bar. Click Import Service to open the import flow. 

Within the import flow, you can discover services from all of your integrated environments and pull them into your service catalog automatically. Admins should set up integrations in advance so they can hand the import flow over to team members, who can then find and import the specific services they need.

Recommendation: At the minimum, admins should integrate with Git sources (like GitHub, GitLab, Bitbucket, and Azure DevOps) before attempting to import services. At some point, you'll want to make sure integrations are set up for your APM tools (like Datadog), oncall services (like Pagerduty), and infrastructure systems (like Kubernetes). In the beginning, though, integrating with Git will give you team members access to your services and all of the libraries and projects that might not be deployed yet.

Service import flow

With integrations set up, you'll be able to see all of the services that Cortex has discovered for import. In general, if Cortex can detect a service at this stage, you'll want to import it at some point. Cortex will also hide services that have already been imported, so you never have to worry about duplicates in your catalog.

At a glance, you can see the source for each discovered service. You can also filter by integration to make it easier to find the services you're looking for. Although you have the option to bulk import services, it's best to start with just one services. Bulk importing bypasses the import flow, so to get a good feel for Cortex, you want to take a more focused approached.

Any services chosen for import will display at the top of the page under Selected services.

Cortex automatically pulls each service's name, repo identifier, and description during the import flow, which appear beneath added services.

Manually creating a service

If you don’t have a service provider set up, you can Create a new service manually.

This will open a modal window where you can enter the new service's name, identifier, and description. Click Create Service, and Cortex will do the rest.

Adding service information

If you're importing services, rather than manually creating them, select Add service to move onto the details page. 

On this page, you'll be prompted to add all of the key information about your service. In Owners, you'll define any teams responsible for the service, add email addresses for owners, and connect to Slack channels where the owner(s) can be reached. Under Links, dependencies, on-call, and repository, you'll include information about a service's runbooks, dashboards, and other crucial data about your service.

Recommendation: At the minimum, you should add ownership and on-call information. This information is important for your team members, but it also allows you to get the most out of Cortex.

Depending on which integration you’re importing from, some of this information may already be filled out for you. For example, when you import from any Git integration, the repo will be pulled automatically. Note that, unlike when manually creating a service, you do not need to enter a service's name or description.

You aren't required to add any information upfront to import a service, but it will make it easier to get the most out of Cortex from the very start. After you've added all the relevant info, select Create Service to add the service into your catalog. You'll automatically be brought to the new service's details page, where you can confirm that you entered the right information.

Once the import is complete, Cortex will automatically generate a YAML file for the new service, regardless of whether you added it manually or went through the import flow. You can continue to make edits to your service after it’s imported, either by directly editing the YAML or by going through the UI, so you’re not tied to anything you do during this stage.

Note that if you're importing more than one service, Cortex will bypass the details page and automatically add those services into the catalog. After you select Add X services, you'll see a confirmation page, with links to each imported service. 

Advanced import methods

There may be cases where you don’t want to use the UI to import a service. If you have custom use cases, or if you have internal catalog information that you want to bulk import into Cortex, we recommend that you take a look at our developer docs. We’ve provided information on how these YAML files are structured and how you can generate them yourself. Through the Cortex API, you have the option to upload handcrafted YAML files directly into your catalog, bypassing the import flow altogether.