Team Catalog

The Team Catalog is the place for you to store all of your team data in Cortex. Your other entities can then interact with your teams (e.g. by providing a x-cortex-owners field).

x-cortex-team section

Although teams can have many of the same tags as other entities in Cortex, they uniquely can have a x-cortex-team tag. The x-cortex-team tag has two main sections: groups and members.

Groups

groups can be used to link your team entity with a team on a different platform that you have integrated with Cortex. For example, you can specify:

openapi: 3.0.0
info:
  title: Example Team
  description: My Cool Team
  x-cortex-type: team
  x-cortex-tag: example-team
  x-cortex-team:
      groups:
      - name: okta-security-team
        provider: OKTA

And with specifying that, your team will contain all the members from the okta-security-team! Now, if you specify the okta-security-team in your x-cortex-owners on any of your other services, resources, or domains, they will automatically recognize example-team as a team that owns their entity.

Members

members can be used to add individual members to your team when you have a use case for a team entity that doesn't correspond exactly to a team on one of your integrations. This can be particularly useful when you want to add an Engineering Manager, Product Manager, or Designer. For example, you can specify:

openapi: 3.0.0
info:
  title: Example Team
  description: My Cool Team
  x-cortex-type: team
  x-cortex-tag: example-team
  x-cortex-team:
      members:
      - name: Product Manager
        email: product-manager@cortex.io
        notificationsEnabled: true
      - name: Engineering Manager
        email: engineering-manager@cortex.io
        notificationsEnabled: true        

And with specifying that, your team now will contain Product Manager and Engineering Manager. Now, if product-manager@cortex.io or engineering-manager@cortex.io were to correspond with the email of an actual account in Cortex, they would start seeing example-team being displayed as a team that they're a part of (e.g. it would start showing up in their Mine tab in the Team Catalog page).

caution

In order to be considered valid, a team must either have a non-empty group, described in the section above, or have at least one member with notificationsEnabled: true.

Team children

You can define a list of other teams as children, allowing you to represent a hierarchy of how your teams are modeled across your workspace, using the x-cortex-children tag.

openapi: 3.0.0
info:
  title: Payments
  description: This is my cool team.
  x-cortex-tag: payments-team
  x-cortex-type: team
  x-cortex-children:
  - tag: child-team-1
  - tag: child-team-2

This hierarchy is available to look at in the Hierarchy tab on the Team Catalog page.

Team parents

Team children allow you to define the team relationship from the top-down, but in some cases it may be easier to define the team hierarchy from the bottom-up. For these cases, x-cortex-parents can be added to any entity's YAML to define its parents.

caution

Today, teams can have at most one parent team defined. The x-cortex-parents descriptor takes in a list so that we can extend this model in the future.

openapi: 3.0.0
info:
  title: Payments
  description: This is my cool team.
  x-cortex-tag: payments-team
  x-cortex-type: team
  x-cortex-parents:
  - tag: parent-team-1

GitOps

When using GitOps you can define any number of teams in any repository. Team definitions should live in the .cortex/teams directory in your repository.

.
└── .cortex
    ├── catalog
    │   ├── database.yml
    │   ├── s3-bucket.yml
    │   ├── auth-service.yml
    │   └── billing-service.yml
    ├── teams
        ├── eng-team.yml
        └── sre-team.yml