Add service to Repertoire

Repertoire implements static service discovery, which means that the URLs for services are determined by its Phalanx configuration and information about the Phalanx environment injected by Argo CD.

Entries in service discovery are generated by Repertoire rules. The config.rules Helm setting for Repertoire maps the names of Phalanx applications to lists of rules. Each rule adds one service entry to service discovery.

This page explains how to write new rules when adding a new service or a new endpoint to an existing service.

Service types

Services are classified as one of three types:

data

A user-facing API service to retrieve or process information from a specific dataset. The base URL for the service may vary based on the dataset. This type of service is used for all user-facing services even if their base URLs currently do not vary based on dataset. This will allow us to provide different endpoints for different datasets in the future if we need to for backwards compatibility reasons.

internal

An internal API service used mostly by other services and not tied to any particular dataset.

ui

A service that provides a web-based user interface intended to be accessed via a web browser. This may be user-facing or only for administrators.

Writing a rule

Here is an example rule for a Phalanx application:

gafaelfawr:
  - type: "internal"
    name: "gafaelfawr"
    template: "https://{{base_hostname}}/auth/api/v1"
    openapi: "https://{{base_hostname}}/auth/openapi.json"
  - type: "ui"
    name: "tokens"
    template: "https://{{base_hostname}}/auth/tokens"

This rule says that if the gafaelfawr Phalanx application is enabled for that environment, add an internal service named gafaelfawr and a UI service named tokens.

The template field defines the template used to generate the primary URL. The openapi field (only for internal and data services) defines the template used to generate the URL to the OpenAPI schema for that service, and can be omitted if the service doesn’t publish an OpenAPI schema. The only supported template variable is base_hostname, which is replaced with the base hostname of the Phalanx environment.

Here is an example of a data service:

sia:
  - type: "data"
    name: "sia"
    datasets:
      - "dp02"
      - "dp1"
    template: "https://{{base_hostname}}/api/sia/{{dataset}}"
    openapi: "https://{{base_hostname}}/api/sia/openapi.json"

This is very similar, but has an additional datasets setting, which lists the datasets for which this service is available. If this setting is omitted, the service is assumed to support every dataset that is available in the Phalanx environment.

The URL templates (both template and openapi) for data services support an additional template variable, dataset, which is replaced with the label of the dataset when generating URLs for each supported dataset.

These rules should be added to the config.rules setting in applications/repertoire/values.yaml. It is possible to add rules directly in applications/repertoire/values-environment.yaml for a specific environment, but this pattern is discouraged since applications are rarely deployed in only one environment. Instead, add the rules to the main values.yaml file; the rule will be ignored if that application is not deployed in a given environment.

Warning

There is currently no way to write a rule that is conditional on particular settings for a Phalanx application. All rules for the application are processed if the application is enabled. This restriction will probably be lifted in a future version.

Subdomain rules

Currently, most Phalanx applications register routes under the base hostname of the Phalanx environment. In the future, some applications will be moving to subdomains in at least some environments to provide better JavaScript and web security isolation.

If an application supports running in a subdomain, write two rule blocks for that application, one in config.rules and one in config.subdomainRules. The one in config.subdomainRules should generate the URLs for that application if it is deployed in a subdomain.

The config.useSubdomains setting should then be overridden for each Phalanx environment that uses subdomains to list the applications running in subdomains at that environment. Repertoire will choose either the regular rules or the subdomain rules depending on whether the application appears in that list.