Starlight

The event provider facing service designed for publishing events to Horizon.

Prerequisites • Building Starlight • Configuration • Running Starlight

Overview

Horizon's Starlight provides a REST endpoint allowing event providers to publish events. Its responsibilities include event acceptance, authentication/authorization, schema validation (optional), and publishing to Horizon's underlying message broker (Kafka).

Note: Starlight is an essential part of the Horizon ecosystem. Please refer to documentation of the entire system to get the full picture.

Prerequisites

For the optimal setup, ensure you have:

• A running instance of Kafka
• Access to a Kubernetes cluster on which the Subscription (subscriber.horizon.telekom.de) custom resource definition has been registered

Building Starlight

Gradle build

./gradlew build

Docker build

The default docker base image is azul/zulu-openjdk-alpine:21-jre. This is customizable via the docker build arg DOCKER_BASE_IMAGE. Please note that the default helm values configure the kafka compression type snappy which requires gcompat to be installed in the resulting image. So either provide a base image with gcompat installed or change/disable the compression type in the helm values.

docker build -t horizon-starlight:latest --build-arg="DOCKER_BASE_IMAGE=<myjvmbaseimage:1.0.0>" . 

Multi-stage Docker build

To simplify things, we have also added a mult-stage Dockerfile to the respository, which also handles the Java build of the application in a build container. The resulting image already contains "gcompat", which is necessary for Kafka compression.

docker build -t horizon-starlight:latest . -f Dockerfile.multi-stage 

Configuration

Starlight configuration is managed through environment variables. Check the complete list of supported environment variables for setup instructions.

Schema validation

Starlight basically supports schema validation for incoming events. Unfortunately this part of starlight is not yet ready for open-source.

If you can´t wait for this, you´re able to provide your own implementation. Basically this is done via a valid bean instance of the SchemaStore interface from horizon-pubsub-spring-parent module. You are able to create your own spring-boot-starter with a custom implementation and use the environment variable ADDITIONAL_SCHEMASTORE_IMPL to build with your custom artifact and use the following configuration or make use of the available environment variables for these properties.

starlight:
  features:
    schemaValidation: true

# only used for schema validation (not yet possible as OSS for starlight)
eniapi:
  baseurl: https://api.example.com/
  refreshInterval: 60000

# only used for schema validation (not yet possible as OSS for starlight)
oidc:
  issuerUrl: https://oauth.example.com/
  clientId: foo
  clientSecret: bar

Running Starlight

Locally

Before you can run Starlight locally you must have a running instance of Kafka locally or forwarded from a remote cluster. Additionally, you need to have a Kubernetes config at ${user.home}/.kube/config.main that points to the cluster you want to use.

After that you can run Starlight in a dev mode using this command:

./gradlew bootRun --args='--spring.profiles.active=publisher-mock'

Documentation

Read more about the software architecture and the general process flow of Horizon Starlight in docs/architecture.md.

Contributing

We're committed to open source, so we welcome and encourage everyone to join its developer community and contribute, whether it's through code or feedback.
By participating in this project, you agree to abide by its Code of Conduct at all times.

Code of Conduct

This project has adopted the Contributor Covenant in version 2.1 as our code of conduct. Please see the details in our CODE_OF_CONDUCT.md. All contributors must abide by the code of conduct.

Licensing

This project follows the REUSE standard for software licensing. You can find a guide for developers at https://telekom.github.io/reuse-template/.
Each file contains copyright and license information, and license texts can be found in the ./LICENSES folder. For more information visit https://reuse.software/.