Skip to content

Commit

Permalink
docs: added target manager configuration
Browse files Browse the repository at this point in the history 
Signed-off-by: Bruno Bressi <[email protected]>
  • Loading branch information
@puffitos
puffitos committed Dec 15, 2023
1 parent a71ae1b commit 7b29f0e
Showing 1 changed file with 104 additions and 43 deletions.
147 changes: 104 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,38 @@

- [About this component](#about-this-component)
- [Installation](#installation)
- [Binary](#binary)
- [Container Image](#container-image)
- [Helm](#helm)
- [Binary](#binary)
- [Container Image](#container-image)
- [Helm](#helm)
- [Usage](#usage)
- [Container Image](#container-image-1)
- [Container Image](#container-image-1)
- [Configuration](#configuration)
- [Startup](#startup)
- [Loader](#loader)
- [Runtime](#runtime)
- [Check: Health](#check-health)
- [Check: Latency](#check-latency)
- [API](#api)
- [Startup](#startup)
- [Loader](#loader)
- [Runtime](#runtime)
- [TargetManager](#targetmanager)
- [Check: Health](#check-health)
- [Check: Latency](#check-latency)
- [API](#api)
- [Code of Conduct](#code-of-conduct)
- [Working Language](#working-language)
- [Support and Feedback](#support-and-feedback)
- [How to Contribute](#how-to-contribute)
- [Licensing](#licensing)


The `sparrow` is an infrastructure monitoring tool. The binary includes several checks (e.g. health check) that will be executed periodically.
The `sparrow` is an infrastructure monitoring tool. The binary includes several checks (e.g. health check) that will be
executed periodically.

## About this component

The `sparrow` performs several checks to monitor the health of the infrastructure and network from its point of view. The following checks are available:
The `sparrow` performs several checks to monitor the health of the infrastructure and network from its point of view.
The following checks are available:

1. Health check - `health`: The `sparrow` is able perform an http-based (HTTP/1.1) health check to provided endpoints. The `sparrow` will expose its own health check endpoint as well.
1. Health check - `health`: The `sparrow` is able perform an http-based (HTTP/1.1) health check to provided endpoints.
The `sparrow` will expose its own health check endpoint as well.

2. Latency check - `latency`: The `sparrow` is able to communicate with other `sparrow` instances to calculate the time a request takes to the target and back. The check is http (HTTP/1.1) based as well.
2. Latency check - `latency`: The `sparrow` is able to communicate with other `sparrow` instances to calculate the time
a request takes to the target and back. The check is http (HTTP/1.1) based as well.

## Installation

Expand All @@ -45,27 +49,31 @@ Please see the [release notes](https://github.com/caas-team/sparrow/releases) fo

### Binary

The binary is available for several distributions. Currently the binary needs to be installed from a provided bundle or source.
The binary is available for several distributions. Currently the binary needs to be installed from a provided bundle or
source.

```sh
curl https://github.com/caas-team/sparrow/releases/download/v${RELEASE_VERSION}/sparrow_${RELEASE_VERSION}_linux_amd64.tar.gz -Lo sparrow.tar.gz
curl https://github.com/caas-team/sparrow/releases/download/v${RELEASE_VERSION}/sparrow_${RELEASE_VERSION}_checksums.txt -Lo checksums.txt
```

For example release `v0.0.1`:

```sh
curl https://github.com/caas-team/sparrow/releases/download/v0.0.1/sparrow_0.0.1_linux_amd64.tar.gz -Lo sparrow.tar.gz
curl https://github.com/caas-team/sparrow/releases/download/v0.0.1/sparrow_0.0.1_checksums.txt -Lo checksums.txt
```

Extract the binary:

```sh
tar -xf sparrow.tar.gz
```

### Container Image

The [sparrow container images](https://github.com/caas-team/sparrow/pkgs/container/sparrow) for dedicated [release](https://github.com/caas-team/sparrow/releases) can be found in the GitHub registry.
The [sparrow container images](https://github.com/caas-team/sparrow/pkgs/container/sparrow) for
dedicated [release](https://github.com/caas-team/sparrow/releases) can be found in the GitHub registry.

### Helm

Expand All @@ -75,7 +83,8 @@ Sparrow can be install via Helm Chart. The chart is provided in the GitHub regis
helm -n sparrow upgrade -i sparrow oci://ghcr.io/caas-team/charts/sparrow --version 1.0.0 --create-namespace
```

The default settings are fine for a local running configuration. With the default Helm values the sparrow loader uses a runtime configuration that is provided in a ConfigMap. The ConfigMap can be set by defining the `runtimeConfig` section.
The default settings are fine for a local running configuration. With the default Helm values the sparrow loader uses a
runtime configuration that is provided in a ConfigMap. The ConfigMap can be set by defining the `runtimeConfig` section.

To be able to load the configuration during the runtime dynamically, the sparrow loader needs to be set to type `http`.

Expand All @@ -86,8 +95,9 @@ startupConfig:
loaderType: http
loaderHttpUrl: https://url-to-runtime-config.de/api/config%2Eyaml

runtimeConfig: {}
runtimeConfig: { }
```
For all available value options see [Chart README](./chart/README.md).
Additionally check out the sparrow [configuration](#configuration) variants.
Expand All @@ -102,11 +112,14 @@ Run a `sparrow` container by using e.g. `docker run ghcr.io/caas-team/sparrow`.

Pass the available configuration arguments to the container e.g. `docker run ghcr.io/caas-team/sparrow --help`.

Start the instance using a mounted startup configuration file e.g. `docker run -v /config:/config ghcr.io/caas-team/sparrow --config /config/config.yaml`.
Start the instance using a mounted startup configuration file
e.g. `docker run -v /config:/config ghcr.io/caas-team/sparrow --config /config/config.yaml`.

## Configuration

The configuration is divided into two parts. The startup configuration and the runtime configuration. The startup configuration is a technical configuration to configure the `sparrow` instance itself. The runtime configuration will be loaded by the `loader` from a remote endpoint. This configuration consist of the checks configuration.
The configuration is divided into two parts. The startup configuration and the runtime configuration. The startup
configuration is a technical configuration to configure the `sparrow` instance itself. The runtime configuration will be
loaded by the `loader` from a remote endpoint. This configuration consist of the checks configuration.

### Startup

Expand All @@ -117,7 +130,7 @@ The `sparrow` is able to get the startup configuration from different sources as
Priority of configuration (high to low):

1. CLI flags
2. Environment variables
2. Environment variables
3. Defined configuration file
4. Default configuration file

Expand All @@ -130,12 +143,18 @@ The loader can be selected by specifying the `loaderType` configuration paramete
The default loader is an `http` loader that is able to get the runtime configuration from a remote endpoint.

Available loader:
- `http`: The default. Loads configuration from a remote endpoint. Token authentication is available. Additional configuration parameter have the prefix `loaderHttp`.
- `file` (experimental): Loads configuration once from a local file. Additional configuration parameter have the prefix `loaderFile`. This is just for development purposes.

- `http`: The default. Loads configuration from a remote endpoint. Token authentication is available. Additional
configuration parameter have the prefix `loaderHttp`.
- `file` (experimental): Loads configuration once from a local file. Additional configuration parameter have the
prefix `loaderFile`. This is just for development purposes.

### Runtime

Besides the technical startup configuration the configuration for the `sparrow` checks is loaded dynamically from an http endpoint. The `loader` is able to load the configuration dynamically during the runtime. Checks can be enabled, disabled and configured. The available loader confutation options for the startup configuration can be found in [here](sparrow_run.md)
Besides the technical startup configuration the configuration for the `sparrow` checks is loaded dynamically from an
http endpoint. The `loader` is able to load the configuration dynamically during the runtime. Checks can be enabled,
disabled and configured. The available loader confutation options for the startup configuration can be found
in [here](sparrow_run.md)

Example format of a runtime configuration:

Expand All @@ -147,13 +166,44 @@ checks:
enabled: true
```

### Target Manager

The `sparrow` is able to manage the targets for the checks and register the `sparrow` as target on a (remote) backend.
This is done via a `TargetManager` interface, which can be configured on startup. The available configuration options
are listed below:

| Type | Description | Default |
|--------------------------------------|--------------------------------------------------------------------------------------|----------------------|
| `targetManager.type` | The kind of target manager to use. | `gitlab` |
| `targetManager.checkInterval` | The interval in seconds to check for new targets. | `300` |
| `targetManager.unhealthyThreshold` | The threshold in seconds to mark a target as unhealthy and remove it from the state. | `600` |
| `targetManager.registrationInterval` | The interval in seconds to register the current sparrow at the targets backend. | `300` |
| `targetManager.gitlab.token` | The token to authenticate against the gitlab instance. | `""` |
| `targetManager.gitlab.url` | The base URL of the gitlab instance. | `https://gitlab.com` |
| `targetManager.gitlab.projectID` | The project ID of the gitlab project to use as a remote state backend. | `""` |

The Gitlab target manager uses a gitlab project as the remote state backend. The various `sparrow` instances will
register themselves as targets in the project. The `sparrow` instances will also check the project for new targets and
add them to the local state. The registration is done by committing a "state" file in the main branch of the repository,
which is named after the DNS name of the `sparrow`. The state file contains the following information:

```json
{
"url": "https://<SPARROW_DNS_NAME",
"lastSeen": "2021-09-30T12:00:00Z"
}
```

### Check: Health

Available configuration options:

- `checks.health.enabled` (boolean): Currently not used.
- `checks.health.targets` (list of strings): List of targets to send health probe. Needs to be a valid url. Can be another `sparrow` instance. Use health endpoint, e.g. `https://sparrow-dns.telekom.de/checks/health`. The remote `sparrow` instance needs the `healthEndpoint` enabled.
- `checks.health.healthEndpoint` (boolean): Needs to be activated when the `sparrow` should expose its own health endpoint. Mandatory if another `sparrow` instance wants perform a health check.
- `checks.health.targets` (list of strings): List of targets to send health probe. Needs to be a valid url. Can be
another `sparrow` instance. Use health endpoint, e.g. `https://sparrow-dns.telekom.de/checks/health`. The
remote `sparrow` instance needs the `healthEndpoint` enabled.
- `checks.health.healthEndpoint` (boolean): Needs to be activated when the `sparrow` should expose its own health
endpoint. Mandatory if another `sparrow` instance wants perform a health check.

Example configuration:

Expand All @@ -171,16 +221,19 @@ checks:
Available configuration options:

- `checks`
- `latency`
- `enabled` (boolean): Currently not used.
- `interval` (integer): Interval in seconds to perform the latency check.
- `timeout` (integer): Timeout in seconds for the latency check.
- `retry`
- `count` (integer): Number of retries for the latency check.
- `delay` (integer): Delay in seconds between retries for the latency check.
- `targets` (list of strings): List of targets to send latency probe. Needs to be a valid url. Can be another `sparrow` instance. Use latency endpoint, e.g. `https://sparrow-dns.telekom.de/checks/latency`. The remote `sparrow` instance needs the `latencyEndpoint` enabled.
- `latencyEndpoint` (boolean): Needs to be activated when the `sparrow` should expose its own latency endpoint. Mandatory if another `sparrow` instance wants perform a latency check.
Example configuration:
- `latency`
- `enabled` (boolean): Currently not used.
- `interval` (integer): Interval in seconds to perform the latency check.
- `timeout` (integer): Timeout in seconds for the latency check.
- `retry`
- `count` (integer): Number of retries for the latency check.
- `delay` (integer): Delay in seconds between retries for the latency check.
- `targets` (list of strings): List of targets to send latency probe. Needs to be a valid url. Can be
another `sparrow` instance. Use latency endpoint, e.g. `https://sparrow-dns.telekom.de/checks/latency`. The
remote `sparrow` instance needs the `latencyEndpoint` enabled.
- `latencyEndpoint` (boolean): Needs to be activated when the `sparrow` should expose its own latency endpoint.
Mandatory if another `sparrow` instance wants perform a latency check.
Example configuration:

```yaml
checks:
Expand All @@ -198,11 +251,14 @@ checks:

### API

The `sparrow` exposes an API that does provide access to the check results. Each check will register its own endpoint at `/v1/metrics/{check-name}`. The API definition will be exposed at `/openapi`
The `sparrow` exposes an API that does provide access to the check results. Each check will register its own endpoint
at `/v1/metrics/{check-name}`. The API definition will be exposed at `/openapi`

## 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.
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.

## Working Language

Expand All @@ -218,19 +274,24 @@ The application itself and all end-user facing content will be made available in
The following channels are available for discussions, feedback, and support requests:

| Type | Channel |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Issues** | <a href="/../../issues/new/choose" title="General Discussion"><img src="https://img.shields.io/github/issues/caas-team/sparrow?style=flat-square"></a> |

## How to Contribute

Contribution and feedback is encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](./CONTRIBUTING.md). By participating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times.
Contribution and feedback is encouraged and always welcome. For more information about how to contribute, the project
structure, as well as additional contribution information, see our [Contribution Guidelines](./CONTRIBUTING.md). By
participating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times.

## Licensing

Copyright (c) 2023 Deutsche Telekom IT GmbH.

Licensed under the **Apache License, Version 2.0** (the "License"); you may not use this file except in compliance with the License.
Licensed under the **Apache License, Version 2.0** (the "License"); you may not use this file except in compliance with
the License.

You may obtain a copy of the License at <https://www.apache.org/licenses/LICENSE-2.0>.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the [LICENSE](./LICENSE) for the specific language governing permissions and limitations under the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "
AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the [LICENSE](./LICENSE) for
the specific language governing permissions and limitations under the License.

0 comments on commit 7b29f0e

Please sign in to comment.