# Plan Migrations and Modernizations To configure your Cortex workspace for Migrations, we recommend the following actions: * **Connect Data**: [Ingest data and ensure ownership](#step-1-ingest-data-and-solve-ownership) is assigned to your entities * **Standardize**: [Configure a Scorecard](#step-2-configure-a-scorecard-for-production-readiness) to enforce and measure migration processes and [create an Initiative](#step-2-configure-a-scorecard-and-initative-for-migrations) to motivate progress * **Streamline**: [Set up data verification](#step-3-configure-data-verification) in Cortex to ensure your data is up to date and [automate production standards via Workflows](#step-4-automate-processes-via-workflows) * **Improve**: [Review Eng Intelligence metrics and take action](#step-5-review-and-act-on-eng-intelligenc) when issues are surfaced ## Use Cortex features to prepare for migrations Expand the tiles below to learn about configuring Cortex features to prepare for Migrations.
Step 1: Ingest data and solve ownership 🔌 {% hint style="success" %} **Action Items:** * [**Import your data**](/ingesting-data-into-cortex/overview.md) * [**Ensure ownership is set**](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) * [**Configure integrations**](/ingesting-data-into-cortex/integrations.md) {% endhint %} Before getting started on any use case, it is crucial to import your services, resources, infrastructure, and other entities, and to have clear visibility into the ownership of your entities. Connecting your entities to Cortex establishes a single source of truth across your engineering organization. It enables the ability to track progress via Scorecards, automate Workflows, and gain insights from Eng Intelligence.
Setting ownership of entities ensures that every service and system is clearly linked to accountable teams or individuals, enabling faster incident response, reducing handoff friction, and making it possible to enforce standards consistently. The more data you have available, the more actionable and insightful your Scorecards can be. #### Relevant integrations To focus on migrations, Cortex recommends integrating with tools that provide visibility into your inventory, ownership, on-call, and issue tracking. Make sure you have configured integrations for the following categories: * **Version control**: [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops.md), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket.md), [GitHub](/ingesting-data-into-cortex/integrations/github.md), [GitLab](/ingesting-data-into-cortex/integrations/gitlab.md) * Surface repositories, PRs, and owners * **Teams/ownership:** [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops.md), [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr.md), [Entra ID](/ingesting-data-into-cortex/integrations/entraid.md) (formerly Azure Active Directory), [GitHub](/ingesting-data-into-cortex/integrations/github.md), [GitLab](/ingesting-data-into-cortex/integrations/gitlab.md), [Google](/ingesting-data-into-cortex/integrations/google.md), [Okta](/ingesting-data-into-cortex/integrations/okta.md), [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie.md), [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow.md), and [Workday](/ingesting-data-into-cortex/integrations/workday.md). * Ensure entities have owners and foster a culture of accountability * **On-call**: [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty.md), [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie.md), [Splunk On-Call](/ingesting-data-into-cortex/integrations/splunk-oncall.md) (formerly VictorOps), [xMatters](/ingesting-data-into-cortex/integrations/xmatters.md) * In case of any issues, ensure escalation policies are in place before migrating production services * **Project management**: [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops.md), [ClickUp](/ingesting-data-into-cortex/integrations/clickup.md), [GitHub](/ingesting-data-into-cortex/integrations/github.md), [Jira](/ingesting-data-into-cortex/integrations/jira.md) * Track migration-related tasks and failing standards Cortex also recommends [linking to runbooks and documentation](/ingesting-data-into-cortex/entities-overview/entities/external-docs.md) for your entities, ensuring your users have access to critical information. With your data in Cortex, you have a jumping-off point to start working on migrations.
Step 2: Configure a Scorecard and Initative for Migrations 📋 {% hint style="success" %} **Action Item:** [**Create a Scorecard**](/standardize/scorecards/create.md) **for migrations and an associated** [**Initiative**](/improve/initiatives.md) {% endhint %} Scorecards automate the process of checking whether services meet criteria such as ownership and on-call coverage. You can use Scorecards to define modernization rules (e.g., entity uses supported runtime, has a Helm chart, owns SLOs). To motivate developers to meet the rules in your Scorecard, you can configure an Initiative that asks them to complete certain rules by a specified deadline. See examples of migration Initiatives in the [Initiative examples docs](/improve/initiatives.md#initiative-examples). The example below walks through setting up a Scorecard that verifies entities have migrated to the latest versions for AWS RDS, Lambda, and Elasticache. ### Example: Upcoming EOL for AWS Scorecard #### Configure the basic details for the Scorecard 1. In Cortex, navigate to **Scorecards** and click **+Create Scorecard**. Start with a blank Scorecard. 2. Configure the basic details. * Include a name that helps your users understand the purpose of the Scorecard (e.g., `Upcoming EOL for AWS`) and a description. * Learn more about configuring basic fields for Scorecards in [Create a Scorecard](broken://pages/JD5p2dFCbCD5ukbib0Cg#step-1-configure-the-basic-scorecard-fields). 3. Under "Apply to specific entities," narrow the scope of your Scorecard by choosing `RDS`, `Lamba`, and `AWS Elasticache for Redis` entity types.
#### Add levels and rules 1. Under **Define evaluation rules**, add two levels: * EOL Upgrade Required * No Pending EOL Upgrade 2. In the "No Pending EOL Upgrade" level, add a rule called `PostgreSQL EOL Version Upgrade Completed`. Include a CQL expression that verifies the entities are not on EOL versions. The following rule passes when Aurora PostgreSQL is 13.x or when Aurora MySQL is 8.x: ``` (jq(aws.details(), ".resources[0].engine") == "aurora-postgresql" AND jq(aws.details(), ".resources[0].engineVersion | startswith(\"13.\")") == true) OR (jq(aws.details(), ".resources[0].engine") == "aurora-mysql" AND jq(aws.details(), ".resources[0].engineVersion | startswith(\"8.\")") == true) ``` 3. Add another rule called `Elasticache EOL Version Upgrade Completed`. Include a CQL expression that verifies the entities are not on EOL versions. The following rule passes when Redis is 7.x or newer, Memcached is 1.6 or newer, or if no Elasticache exists for the entity: ``` (jq(aws.details(), ".resources[0].metadata.engine") == "redis" AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[0] | tonumber") >= 7) OR (jq(aws.details(), ".resources[0].metadata.engine") == "memcached" AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[0] | tonumber") >= 1 AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[1] | tonumber") >= 6) ``` 4. At the bottom of the page, click **Save Scorecard**.
Step 3: Automate processes via Workflows ⚙️ {% hint style="success" %} **Action item:** [**Configure Workflows**](/streamline/workflows.md) {% endhint %} You can use Workflows to streamline and standardize processes by turning best practices into repeatable, self-service automations. This is especially valuable during modernization efforts, such as cloud or Kubernetes migrations, where consistency and speed are critical. {% hint style="info" %} Check out the [Cortex Academy "Migrations and Modernizations" course](https://academy.cortex.io/learn/course/migrations-and-modernizations/driving-migrations-with-cortex/how-cortex-tools-simplify-migrations?page=4) for a downloadable PostgreSQL upgrade prep Workflow. {% endhint %} #### Workflows to kick off a migration You could create a Workflow that kicks off a migration or upgrade pipeline for an entity. For example, after selecting an entity and specifying the target version, the Workflow could use an [HTTP Request block](/streamline/workflows/blocks.md#http-request) to trigger a CI job, like a GitHub Actions or GitLab pipeline, that handles the actual migration steps. This approach lets you standardize how migrations are initiated and monitored directly from Cortex, so teams can easily start upgrade processes without leaving Cortex. #### Workflows to establish adherence to best practices Having best practices established before a migration helps ensure a smoother migration process. * You can add manual approval steps in a Workflow to require sign-off from specific team members before a service is considered production-ready, ensuring accountability and providing an audit trail. * See the documentation on [configuring a Manual approval block](/streamline/workflows/blocks.md#manual-approval). * When Scaffolding new services, you can use templates to ensure that every new service starts with baseline standards (e.g., on-call information, runbooks, SLOs configured, and more). * See the documentation on [registering a Scaffolder template](/streamline/workflows/scaffolder.md) and [configuring a Scaffolder block](/streamline/workflows/blocks.md#scaffolder). #### Workflows based on a migration Scorecard In a Workflow, you can use an HTTP request to get an individual entity's score or the latest scores for all entities on a migration-related Scorecard, then configure additional blocks to take actions based on the score. You can [reference the output of this block in subsequent blocks](/streamline/workflows/blocks/states.md), allowing you to streamline the followup actions you take based on an entity's migration status. For example, you could create a Workflow that blocks deployment based on Scorecard scores, ensuring that a deployment is blocked if an entity has not yet migrated. * See an example of this Workflow in the template "Deploy to prod based on Scorecard score" in your Cortex workspace:
See the "Deploy to prod based on Scorecard score" template in Cortex.
* When the Workflow runs, it checks whether the entity has achieved the "Gold" level standard in the Scorecard. If it has, the deployment continues. If it has not, the Workflow automatically sends a Slack message to notify the entity owner. * Note that the template is configured to check a Production Readiness Scorecard; In the configuration of the HTTP Request block, you will need to configure it to point at your migration Scorecard.
Step 4: Review reports and Eng Intelligence 📈 {% hint style="success" %} **Action Item:** [**Review Eng Intelligence metrics**](/improve/eng-intelligence.md) **and** [**reports**](/improve/reports.md) {% endhint %} Review [reports](/improve/reports.md) for visibility into migration progress, compliance, and blockers. The [Bird's Eye report](/improve/reports/birds-eye.md) gives you quick insight into where gaps are across the organization:
The bird's eye report shows a heatmap of entity progress on a Scorecard.
Use Eng Intelligence features — such as the [Velocity Dashboard](/improve/eng-intelligence/dashboards/velocity-dashboard.md) and [Metrics Explorer](/improve/eng-intelligence/metrics-explorer.md) — to understand your baseline metrics and for insight into how metrics are impacted during and after a migration.
Review trends in Eng Intelligence graphs and metrics.
Review trends in areas such as deployment frequency, incident response, and other indicators that are important to your organization. This helps you identify areas where teams or services are falling behind.
## Migrations in action Learn about what an ongoing migration looks like in [Migrations in action](/solutions/migrations/in-action.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/solutions/migrations/configure.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.