Skip to main content

Advanced Usage

Once you've started using Cortex's Service Creation product, you may be looking for some advanced features of templates: customizing the autogenerated cortex.yaml, building complex templates that use all the inputs collected by Cortex, and more!

Overriding the autogenerated Service Descriptor

By default, the Service Creation flow generates a Service Descriptor file named cortex.yaml in the root of the repository. This file contains some basic information which the user inputs during the flow such as service ownership, Service Groups, and external docs.

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

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 Service Creation flow 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.

cookiecutter.json
{
"project_name": "My Project",
"project_slug": "{{ cookiecutter.project_name.lower()|replace(' ', '_')|trim() }}",
"@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 Service Creation flow requires users to input additional information aside from the fields defined in the cookiecutter.json file. This includes:

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 containing the following:

{
"service_details": {
"tag": "my-service",
"name": "My Service",
"description": "Optional description if defined",
"owners": [
{"type": "SLACK", "channel": "my-channel"},
{"type":"GROUP", "name": "my-group"},
{"type": "EMAIL", "email": "user@cortex.io"}
],
"serviceGroups": ["list", "of", "groups"]
},
"git": { }
}

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

Using it in a template

You can access this variable in your template the same way you do for any of your own variables: {{ cookiecutter['@cortex_inputs'] }}.

When running Cookiecutter, this field is added to the context before your own variables, so you can refer to it in your cookiecutter.json:

cookiecutter.json
{
"project_name": "My Project",
"project_slug": "{{ cookiecutter['@cortex_inputs']['service_details']['tag'] }}",
"@cortex_hidden_keys": ["project_slug"],
"version": "0.0.1"
}

Git Details

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

GitHub
{
"git": {
"repository": {
"org": "cortexapps",
"repoName": "my-repo"
}
}
}
GitLab
{
"git": {
"repository": {
"namespace": "cortexapps",
"projectName": "my-repo"
}
}
}
Bitbucket
{
"git": {
"repository": {
"workspace": "cortexapps",
"repoSlug": "my-repo"
}
}
}