LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • Templates that add to existing services
  • Overriding the autogenerated Service Descriptor
  • Hiding template variables in the UI
  • Consuming Cortex fields in a template
  • Extending Cookiecutter: Cortex field configurations

Was this helpful?

Export as PDF
  1. Workflows
  2. Registering a Scaffolder template

Scaffolder advanced usage

Last updated 2 months ago

Was this helpful?

This page describes advanced features you can use with a Scaffolder block in a : Customizing the autogenerated cortex.yaml, building complex templates that use inputs collected by Cortex, building templates that add to existing services, and more.

Templates that add to existing services

A powerful workflow that the Scaffolder unlocks is the ability to templatize code to be added to existing services – for example, you may want templates that developers can use to add Terraform modules, CI pipelines, or build/deploy scripts to a service that's already been built.

To do so, you'll want to create a template that generates the file or directory you'd like to add to your existing service, and enable the PR-only toggle when adding the template to your workspace.

Keep in mind that your template always needs to generate a directory as expected by cookiecutter.

The Scaffolder merges files with a recursive copy. If your template generates files or directories that already exist in the target repo, Cortex will not attempt to merge the content of the files. Instead, we do a recursive copy, replacing any files that exist in the target.

Root-level files

If you're trying to add files to the root of an existing service, your template should generate the files at the root of the generated directory. Keep in mind that you can use template variables for the filenames as well.

The expected file structure of your template would be:

(template-folder)$ ls -l
cookiecutter.json
{}/
    {}-generated-file.js
    my-file-to-generate.yml

Note that the files live under a nested, templated directory. When we open a PR, the PR will still only contain the two nested files at the root of the PR. Essentially, the PR will be:

{}-generated-file.js
my-file-to-generate.yml

Directories

If you're looking to generate a directory, the template should generate the desired directory as the output. Although cookiecutter by default generates the output of the entire template into a directory, the PR feature copies output of the template out of the generated directory into the root (recursively).

For example, if you want your template to generate the directory infra-files-{} (or generate a file into this directory), your structure should look like:

(template folder)$ ls -l
cookiecutter.json
{}/
    infra-files-{}/
        my-generated-file.json

Note that you can use templated variables when generating the directory name or files in the directory.

Overriding the autogenerated Service Descriptor

To override the Service Descriptor generated by Cortex, just include a cortex.yaml or cortex.yml file in the template. If Cortex detects that the template has generated either one of these files, the Scaffolder will skip the Service Descriptor generation step.

Hiding template variables in the UI

As the complexity of your template grows, you may have variables in your cookiecutter.json that you want to hide from the UI, for example if they're autogenerated using Python or they're not something you want users to override at all.

To hide fields, just add a @cortex_hidden_keys field containing a list of variables you want to hide.

{
    "project_name": "My Project",
    "project_slug": "{}",
    "@cortex_hidden_keys": ["project_slug"],
    "version": "0.0.1"
}

We hide the version key by default, so you don't need to add that to the list!

If you have "private variables" (variables starting with _, such as "_my_secret_variable"), they will automatically be hidden from the UI.

Consuming Cortex fields in a template

The Cortex Scaffolder flow requires users to input additional information aside from the fields defined in the cookiecutter.json file when creating a service. This includes:

  • Git repository details

  • Ownership

  • Dependencies

  • Template details

You may want your template to use this information, without duplicating these fields in your cookiecutter.json and having developers fill out the information twice! For example, you may want to use the name of the git repo that's created while generating a deployment script in the template.

These fields are available to your template in a magic _@cortex_inputs variable.

The _@cortex_inputs variable

The structure of _@cortex_inputs is a dictionary that will always contain the following:

{
  "git": , // varies based on git provider, see below
  "user": ,
  "template_details": 
}

See below for details on the git object, which contains information on the repository that Cortex is creating for the new project.

You can access this variable in your template the same way you do for any of your own variables: {}.

If your template has the "Requires a new service" flag enabled, _@cortex_inputs will additionally contain the following:

{
  "service_details": {
    "tag": "my-service",
    "name": "My Service",
    "description": "Optional description if defined",
    "owners": [
      ,
      ,
      
    ],
    "serviceGroups": ["list", "of", "groups"],
    "dependencies": [
        ,
        ,
        
    ]
  }
}

Git details

The git object shown above is different based on the provider you're using. The structure is shown below.

GitHub

{
  "git": {
    "repository": 
  }
}

GitLab

{
  "git": {
    "repository": 
  }
}

Bitbucket

{
  "git": {
    "repository": 
  }
}

Azure DevOps

{
  "git": {
    "repository": 
  }
}

Extending Cookiecutter: Cortex field configurations

You can add metadata to each variable that Cortex will display during the scaffolding process.

Adding descriptions to inputs

You can tell the Scaffolder to display description of each input field by specifying the description key within the variables configuration. For text inputs, you can also surface the default values from your cookiecutter.json by marking use_default as true.

Here's an example cookiecutter.json, where full_name is an input consumed by the template. We've defined the _cortex_field_configurations object that configures a description to be displayed in the UI for the full_name variable.

We've also enabled the use of default values for this input.

{
  "full_name": "Albert Einstein",
  "_cortex_field_configurations": {
    "full_name": 
  }
}

By default, the Scaffolder generates an named cortex.yaml in the root of the repository when used to create a service. This file contains some basic information which the user inputs during the flow such as , , and .

In some cases, you may want to generate your own Service Descriptor. This may because you want to add , auto-generate groups based on the template they've selected, add placeholder links, or other such advanced use cases.

Workflow
custom data
Groups
entity ownership
groups
external docs
entity descriptor file
Entity tag