Manage entities using Cortex Terraform Provider

The Cortex Terraform Provider acts as a bridge between Terraform and the Cortex platform, allowing you to manage and provision Cortex resources (such as Scorecards, integrations, and entities) using Terraform’s infrastructure-as-code approach. The provider is a wrapper around the public Cortex API and is maintained by the Cortex team, with shared ownership and ongoing support for customers who use it.

Cortex integrates with Terraform in two different ways, depending on whether you want to manage Cortex resources using Terraform, or use Cortex to drive Terraform runs for your infrastructure.

To learn about using Cortex to drive Terraform runs, see Managing Terraform infra in Cortex.

Managing the catalog as code

Many Cortex customers manage their entire service catalog and engineering standards as code using the Cortex Terraform Provider.

Expand the tiles below for examples on how to handle different use cases with this approach.

Service catalog as code

Goal: Any time a new microservice or app is created (via a Terraform module, template repo, or platform workflow), it’s automatically added to the Cortex catalog with the right metadata and ownership. How to do it:

• Use the cortex_catalog_entity resource to create and update services, libraries, or other catalog entities from Terraform.

• Attach extra metadata with cortex_catalog_entity_custom_data – e.g. tier, business_unit, cost_center, “is_internally_facing”, etc.

• Optionally define departments (e.g. “Payments”, “Growth”) with cortex_department, and link services/teams to those for reporting and ownership.

Scorecards and standards as code

Goal: Treat operational standards (SRE, security, compliance, production-readiness gates) as code that lives next to infrastructure, reviewed via PRs and rolled out safely. How to do it:

• Define scorecards via the cortex_scorecard resource. It supports:

  • a ladder (levels with names, colors, rank)

  • rules (expressions, titles, weights, optional failure messages)

  • an evaluation window (how often to evaluate, min every 4 hours)

  • a filter to target specific entity types or groups

• Use cortex_resource_definition to standardize external signals that Scorecards rely on (e.g. “has SLO in Datadog”, “has PagerDuty service”, “has runbook link”).

• Manage changes to standards through Git review: PRs update the Terraform code, then Terraform updates the Cortex Scorecards and resources.

API contracts and org model as code

Goal: Ensure that API documentation and org metadata are always in sync, accurate, and consistent across environments. How to do it:

• Use cortex_catalog_entity_openapi to attach OpenAPI specs (YAML/JSON) to catalog entities in Cortex, keyed by the entity’s tag/ID.

• Keep department and ownership structure in Terraform via cortex_department and catalog entity custom data (e.g., department, team, criticality).

• When infrastructure changes (e.g., new API version, team moves between org units), updating Terraform automatically pushes the new OpenAPI spec + org metadata into Cortex.

Install the Terraform Provider for Cortex

For installation instructions, see the repository's README in GitHub.

Examples

See the repository for examples.