Vai al contenuto

Configure Doctor Service

As core service, the Doctor Service is easily deployable on every project by using the Api Console. You just need to add the service and configure it's configuration file; we will see how, but first a short overview of how the service works.

How the service works

The Doctor Service is simply based on one file, the configurations file. With the configurations file it's easy to manage all services to check-up. Specifically, the Doctor allows the user to do two things:

  1. check-up all services in the configurations file by simply call the root path (e.g.;
  2. check-up a subgroup of services by specify the tag → all services can have a list of tags (optional) and the Doctor will expose a dedicated route for each tag, that will return the check-up of services with that tag.


NB. all the services call by the Doctor MUST have the /-/check-up route.

Steps overview

Following an overview of the steps that you have to do to integrate the Doctor Service in your project:

  1. Build the configurations file of the Doctor Service
  2. Create the service using the API Console
  3. Configure the Advanced configurations
  4. Check-up'em all


The following example is based on the Playground project of the Cattolica's API Console.

1. Build the configurations file

As previously said, the Doctor Service just needs a configurations file that has to follow this schema:

  type: 'array',
  items: {
    type: 'object',
    required: ['hostname'],
    properties: {
      hostname: { type: 'string' },
      tags: {
        type: 'array',
        items: {
          type: 'string',
      options: {
        type: 'object',
        properties: {
          prefix: {
            type: 'string',
            pattern: '^(\\/.*[A-Za-z1-9])?$',
            default: '',
          port: {
            type: 'number',
            default: 80,
          protocol: {
            type: 'string',
            default: 'http',
            enum: ['http', 'https'],
        default: {},
        additionalProperties: false,
    additionalProperties: false,

As specified into the schema, the tags property is optional → a Doctor Service can have all services without tags and it still works on the root path. Additionally, it is possible to specify an options object in order to furtherly manage how the /-/check-up route is called.
The following options can be provided:
* prefix: to specify a prefix to append before /-/check-up route. Default is an empty string. * protocol: to specify a different protocol. Only http or https can be specified. Default is http. * port: to specify a different port. Default is 80.

In the following example we will set just one tag, the core tag, just for core services:

apiVersion: v1
  'services.json': |
      { "hostname": "auth-service", "tags": ["core"] },
      { "hostname": "cms-backend", "tags": ["core"] },
      { "hostname": "crud-service", "tags": ["core"] },
      { "hostname": "microservice-gateway", "tags": ["core"] },
      { "hostname": "swagger-aggregator", "tags": ["core"] },
      { "hostname": "v1-adapter", "tags": ["core"], "options": { "prefix": "/api/v2", "port": 8888, "protocol": "https" } },
      { "hostname": "node-service" },
      { "hostname": "angular-service" },
      { "hostname": "react-service" },
      { "hostname": "java-service" },
kind: ConfigMap
  creationTimestamp: null
  name: doctor-service

This way, for swagger-aggregator service, doctor-service will call the /-/check-up route at https://auth-service:8888/api/v2/-/check-up.

In this way, we should have the following routes:

  • baseUrl/check-up → should return the check-up response of all services
  • baseUrl/check-up/core → should return the check-up response just of services with the core tag

The configurations file is ready, let's continue.

2. Doctor Service creation on the API Console

Now it's time to create the real service.

Following the steps to create the services:

  1. Open the API Console and choose the project
  2. Click, on the left, on Services
  3. Click on the Create new service button
  4. As service type, choose Import, to import an existing service
  5. Compile the fields as follow:
  6. Name: the name of the service (in the example is doctor-service)
  7. Docker image: where tag is the image tag of the service (info on the CHANGELOG)
  8. Description: the description of the service
  9. Click on the Create button
  10. Go down and check the I want to write custom k8s files for this service checkbox alt_image
  11. Insert the following service.yml

    apiVersion: v1
    kind: Service
      name: doctor-service
      type: NodePort
        - port: 80
          targetPort: 3000
          protocol: TCP
          name: http
        app: doctor-service
  12. Insert the following deployment.yml

    apiVersion: v1
    kind: DeploymentConfig
      name: doctor-service
      replicas: 1
      revisionHistoryLimit: 3
        type: Rolling
            app: doctor-service
            - name: nexus-pull-secret
            - name: doctor-service
              imagePullPolicy: Always
                  memory: 120Mi
                  memory: 70Mi
                - name: LOG_LEVEL
                  value: {{LOG_LEVEL}}
                - name: HTTP_PORT
                  value: '3000'
                - name: SERVICES_LIST_PATH
                  value: /home/node/app/config/services.json
                - name: doctor-service-config
                  mountPath: /home/node/app/config/services.json
                  subPath: services.json
                  readOnly: true
                  port: 3000
                initialDelaySeconds: 5
                periodSeconds: 10
                  path: /-/healthz
                  port: 3000
                initialDelaySeconds: 15
                periodSeconds: 20
            - name: doctor-service-config
                name: doctor-service
  13. Create a new configurations file by using the specific section alt_image

  14. Insert the previously created configurations file into the just created file
  15. Save (Commit and generate button)

3. Configure the advanced configurations

Now the Doctor Service is up, but it's not even usable. Following the instructions to configure the files in the Advanced Section.


Be care on the advanced section of the API Console

Open the API Console and click on the Advanced section button


and, after that, edit the following files by adding the doctor service entries:

  • api-gateway/

    "~^(secreted|unsecreted)-(0|1)-(0|1)-GET-/check-up" "doctor-service";
  • api-gateway/

    "~^GET-/check-up(?<path>.*)" "$path";
  • api-gateway/

    "~^GET-/check-up" "1";

4. Check-up'em all

Now the /check-up route of the project is ready to be called like this:

  • projectBaseUrl/check-up → for a check-up of all services
  • projectBaseUrl/check-up/core → for a check-up of core services only (in this example)