https://github.com/telekom/pubsub-horizon-quasar
A service for synchronizing the state of custom resources with caches or databases :milky_way:
https://github.com/telekom/pubsub-horizon-quasar
crd go golang kubernetes mongodb
Last synced: 6 months ago
JSON representation
A service for synchronizing the state of custom resources with caches or databases :milky_way:
- Host: GitHub
- URL: https://github.com/telekom/pubsub-horizon-quasar
- Owner: telekom
- Created: 2024-06-07T06:56:17.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-01T20:27:26.000Z (7 months ago)
- Last Synced: 2025-05-01T21:37:52.978Z (7 months ago)
- Topics: crd, go, golang, kubernetes, mongodb
- Language: Go
- Homepage:
- Size: 211 KB
- Stars: 4
- Watchers: 5
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSES/Apache-2.0.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
Quasar
Quasar is a tiny service for synchronizing the state of custom resources with caches or databases.
Prerequisites •
Building Quasar •
Configuration •
Running Quasar
[](https://api.reuse.software/info/github.com/telekom/pubsub-horizon-quasar)
[](https://github.com/telekom/pubsub-horizon-quasar/actions/workflows/go-test.yml)
## Overview
Quasar is the config-controller powering the Horizon ecosystem.
> **Note:** Quasar is an essential part of the Horizon ecosystem. Please refer to [documentation of the entire system](https://github.com/telekom/pubsub-horizon) to get the full picture.
## Prerequisites
- A running [Kubernetes](https://github.com/kubernetes/kubernetes) cluster
- A running instance of [MongoDB](https://www.mongodb.com/) or [Redis (_not fully supported yet_)](https://redis.io)
## Building Quasar
### Go build
Assuming you have already installed [Go](https://go.dev/), simply run the following to build the executable:
```bash
go build
```
> Alternatively, you can also follow the Docker build in the following section if you want to build a Docker image without the need to have Golang installed locally.
### Docker build
This repository provides a multi-stage Dockerfile that will also take care of compiling the software, as well as dockerizing Quasar. Simply run:
```bash
docker build -t horizon-quasar:latest .
```
## Configuration
Quasar can be configured using environment variables and/or a configuration file. The following table lists all available configuration options:
**Environment variables aren't officially supported for the `resources` option. It is recommended to configure the `resources` using a configuration/configmap.**
> **Please note:** Redis isn't fully supported (yet) as Hazelcast is the primary cache method of Horizon in its current state.
| Path | Variable | Type | Default | Description |
|-----------------------------|--------------------------------|---------------|---------------------------|--------------------------------------------------------------------------------------------------------------------|
| logLevel | QUASAR_LOGLEVEL | string | info | The log-level. |
| fallback.type | QUASAR_FALLBACK_TYPE | string | mongo | The fallback type that should be used. (mongo or none) |
| fallback.mongo.database | QUASAR_FALLBACK_MONGO_DATABASE | string | horizon | The database that should be used to restore the cache in case of a CR unavailability |
| fallback.mongo.uri | QUASAR_FALLBACK_MONGO_URI | string | mongodb://localhost:27017 | MongoDB uri of the fallback database. |
| reSyncPeriod | QUASAR_RESYNCPERIOD | string | 30s | Resync-period of the Kubernetes informer. |
| store.type | QUASAR_STORE_TYPE | string | hazelcast | Type of store Quasar should write to. |
| store.hazelcast.addresses | QUASAR_HAZELCAST_ADDRESSES | string (list) | [] | The addresses to connect to. |
| store.hazelcast.clusterName | QUASAR_HAZELCAST_CLUSTERNAME | string | horizon | Hazelcast cluster to write to. |
| store.hazelcast.username | QUASAR_HAZELCAST_USERNAME | string | - | Username to authenticate with. |
| store.hazelcast.password | QUASAR_HAZELCAST_PASSWORD | string | - | Password to authenticate with. |
| store.hazelcast.writeBehind | QUASAR_HAZELCAST_WRITEBEHIND | bool | true | Whether or not to perform write-behind writes to the fallback database. |
| store.mongo.uri | QUASAR_MONGO_URI | string | mongodb://localhost:27017 | MongoDB uri of the database. |
| store.mongo.database | QUASAR_MONGO_DATABASE | string | horizon | The database that should be written to. |
| store.redis.host | QUASAR_REDIS_HOST | string | localhost | The redis host. |
| store.redis.port | QUASAR_REDIS_PORT | int | 6379 | The redis port. |
| store.redis.username | QUASAR_REDIS_USERNAME | string | - | Username to authenticate with. |
| store.redis.password | QUASAR_REDIS_PASSWORD | string | - | Password to authenticate with. |
| metrics.enabled | QUASAR_METRICS_ENABLED | bool | false | Whether or not metrics should be served. |
| metrics.port | QUASAR_METRICS_PORT | int | 8080 | The port for exposing the metrics service. |
| metrics.timeout | QUASAR_METRICS_TIMEOUT | string | 5s | Timeout of HTTP connections to the metrics service. |
| resources | - | object (list) | [] | The custom resources that should be synchronized. See [configuring resources](#configuring-resources) for details. |
### Configuring resources
The `resources` configuration option is a list of custom resources that should be synchronized. Each resource has the following fields:
```yaml
kubernetes:
group: mygroup
resource: myresource
version: v1
namespace: mynamespace
prometheus:
enabled: true
labels:
fixed_value: foobar
my_dynamic_value: $spec.myfield
mongoIndexes:
- spec.myfield: 1
- spec.myfield: 1
spec.myotherfield: 1
hazelcastIndexes:
- name: myfield_myotherfield_idx
fields:
- data.spec.environment
type: sorted
```
#### Understanding resources
- `kubernetes`: The Kubernetes resource that should be synchronized.
- `group`: The group of the resource.
- `resource`: The name of the resource.
- `version`: The version of the resource.
- `namespace`: The namespace of the resource.
- `prometheus`: Prometheus metrics configuration.
- `enabled`: Whether to expose metrics for this resource.
- `labels`: Labels that should be exposed as metrics. Labels can be fixed values or values from the resource.
- Fixed values are defined as strings.
- Values from the resource are defined as `$`.
- `mongoIndexes`: Indexes that should be created in the MongoDB database.
- `hazelcastIndexes`: Indexes that should be created in the Hazelcast cache.
- `name`: The name of the index.
- `fields`: The fields that should be indexed.
- `type`: The type of the index. Currently, only `sorted` and `hash` are supported.
#### Generating a local configuration
You can generate a local configuration file by running the following command in the directory of the executable:
```bash
./quasar init
```
## Running Quasar
Once you have prepared your configuration, you can run Quasar by executing the following command in the directory of the executable:
```bash
./quasar run
```
## 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](./CODE_OF_CONDUCT.md) at all times.
## Code of Conduct
This project has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) in version 2.1 as our code of conduct. Please see the details in our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). All contributors must abide by the code of conduct.
By participating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times.
## Licensing
This project follows the [REUSE standard for software licensing](https://reuse.software/).
Each file contains copyright and license information, and license texts can be found in the [LICENSES](./LICENSES) folder. For more information visit https://reuse.software/.
You can find a guide for developers at https://telekom.github.io/reuse-template/.