Table of Contents

Nested clusters

Nested clusters allow a cluster to access other clusters under its own base URL using a path prefix (proxying).

This is typically used to keep everything under the same origin (avoid CORS) and/or embed a nested cluster UI in the main cluster.

This article walks through a concrete example.

Example context

TechnicalDemos

TechnicalDemos is the main cluster in which we want to display a UI view coming from a nested cluster.

It has a UI view TrackingOrderUI in which we want to display the main UI view of TrackingDemo (the nested cluster).

The cluster can be accessed at https://localhost/neos/TechnicalDemos/ in development.

It is also deployed in production at https://technicaldemos.staging.neos.groupeisagri.com/.

TrackingDemo

TrackingDemo is the nested cluster whose main UI view will be displayed inside TechnicalDemos UI view OrderTrackingUI.

The cluster can be accessed at https://localhost/neos/TrackingDemo/ in development.

It is also deployed in production at https://tracking-demo.staging.neos.groupeisagri.com/.

Configuration

To be able to access TrackingDemo inside TechnicalDemos without having to configure CORS policies, we can configure nested clusters.

The principle is that the main cluster (TechnicalDemos) can proxy HTTP requests to one or more nested clusters (TrackingDemo) using a path prefix (here: tracking).

In our case, we want to access TrackingDemo using the following URLs:

Development

In the TechnicalDemos configuration YML file:

NestedClusters:
  - Name: TrackingDemo # (required) The exact name of the nested cluster like configured in its own yml file.
    Prefix: tracking # (required) The URL prefix which will redirect to the nested cluster.
    ForwardUserNotificationsToMainCluster: true # (optional, `false` by default) Indicates whether the nested cluster forwards the user notifications to the main cluster.
    MicroFrontend: true # (optional, `false` by default) Enables the nested cluster as a micro-frontend remote. Used only by the generation.
    SupportsMultiTenancy: false # (optional, `true` by default) Indicates whether the nested cluster supports multi-tenancy. It must be set to `false` when the main cluster can be multitenant but not the nested cluster. Used only by the generation.

With this configuration, all HTTP requests matching:

  • https://localhost/neos/TechnicalDemos/tracking/*

will be forwarded to:

  • https://localhost/neos/TrackingDemo/*
Warning

This feature only works in development when using the HTTPSys web server on a Windows machine. It doesn't work if you run Neos with the Kestrel web server (e.g. neos run -ws Kestrel).

Production

In the Helm chart YML configuration file:

clusters:
  - name: TechnicalDemos
    host: technicaldemos.staging.neos.groupeisagri.com
    nestedClusters:
      - name: TrackingDemo
        pathPrefix: tracking
        forwardUserNotificationsToMainCluster: true
    # ...rest of TechnicalDemos configuration
  - name: TrackingDemo
    host: tracking-demo.staging.neos.groupeisagri.com
    # ...rest of TrackingDemo configuration

With this configuration, all HTTP requests matching:

will be forwarded to:

Display a UI view of a nested cluster in the main cluster using web-view

It is possible to use the web-view component to display a UI view of TrackingDemo inside TechnicalDemos

Warning

TechnicalDemos URLs in development and production have different base paths:

  • /neos/TechnicalDemos in development
  • / in production

We cannot hardcode the web view source URL to a single value that works in both environments.

Use a computed property as the source:

OrderTrackingUI UI view template:

<web-view source="@Computeds.TrackingUrl" expandable="false" />

TrackingUrl computed code :

string url = string.Empty;

#if PLATFORM_WEB
url = $"{SystemEnvironment.Window.Current.Location.Pathname}/tracking/".Replace("//", "/");
#endif

return url;

SystemEnvironment.Window.Current.Location.Pathname can have the following values :

  • /neos/TechnicalDemos in development
  • / in production

With this configuration, the source will be :

  • /neos/TechnicalDemos/tracking/ in development
  • /tracking/ in production

Display a UI view of a nested cluster in the main cluster using micro-frontend

Using micro-frontend, a UI view from the nested cluster can be consumed by the main cluster as a remote UI view.

Prerequisites:

  • In the main cluster, the nested cluster must be configured with MicroFrontend: true under NestedClusters.
  • In the nested cluster, the UI view(s) you want to consume must be exposed using MicroFrontend:ExposedUIViews.

Example (in the nested cluster configuration, TrackingDemo.yml):

MicroFrontend:
  ExposedUIViews:
    - OrderTrackingUI

If both clusters have the NeosNotificationCenter module, it is very likely that you want to forward notifications from the nested cluster to the main cluster. To do this, you need to set ForwardUserNotificationsToMainCluster to true in the nested cluster section of the main cluster configuration.

Using ui-view

You can embed a remote UI view using the ui-view component.

<ui-view name="OrderTrackingUI" remote="TrackingDemo" />

You can also navigate to a UI view of a nested cluster.

await NavigateAsync(new NavigationOptions(Remotes.TrackingDemo, "OrderTrackingUI"));

Notes

On first load of a nested cluster UI view:

  • The nested cluster string resources are loaded. If a resource key already exists in the main cluster, the nested one won't be available.
  • The permissions of the nested cluster UI views are loaded.
  • The nested cluster context is loaded into ApplicationContext. If a key already exists, it won't be overwritten.
  • The SignalR connection for the nested cluster is started.