Skip to content

Commit

Permalink
docs: prepare v0.3.0 release (#76)
Browse files Browse the repository at this point in the history 
* docs: adjust check docs

* chore: example config headers

* docs: add chart value docs

* docs: specify delay formulation

* docs: update docu for helm & checks config

* docs: fix small docu issues

* docs: fix small docu issues+

* docs: typos & rephrasing chart value docu

* docs: switch to active wording

* chore: '

* docs: enhance clarity in binary section

* docs: installation section correct grammar

* docs: helm section improve grammar and accuracy

* docs: improve loader phrasings

* docs: api and metrics sections phrasing clarity and readability

* docs: adjust target manager section

* chore: link correct check config docs

* docs: correct formulations, grammar, typos etc.

* chore: url -> URL

* docs: readd loader explanation to startup config part

* chore: uppercase url

---------

Co-authored-by: [email protected] <[email protected]>
  • Loading branch information
@lvlcn-t @y-eight
lvlcn-t and y-eight authored Jan 23, 2024
1 parent c4a6b54 commit 823a439
Show file tree
Hide file tree
Showing 3 changed files with 88 additions and 80 deletions.
155 changes: 80 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,15 @@
- [Image](#image)
- [Configuration](#configuration)
- [Startup](#startup)
- [Example startup configuration](#example-startup-configuration)
- [Loader](#loader)
- [Runtime](#runtime)
- [Checks](#checks)
- [Target Manager](#target-manager)
- [Check: Health](#check-health)
- [Example configuration](#example-configuration)
- [Health Metrics](#health-metrics)
- [Check: Latency](#check-latency)
- [Example configuration](#example-configuration-1)
- [Latency Metrics](#latency-metrics)
- [API](#api)
- [Metrics](#metrics)
Expand Down Expand Up @@ -49,23 +52,22 @@ The following checks are available:

The `sparrow` is provided as a small binary & a container image.

Please see the [release notes](https://github.com/caas-team/sparrow/releases) for to get the latest version.
Please refer to the [release notes](https://github.com/caas-team/sparrow/releases) to get the latest version.

### 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. To install the binary, use a provided bundle or source. Replace `${RELEASE_VERSION}` with the desired release version:

```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`:
For example, for release `v0.3.0`:

```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
curl https://github.com/caas-team/sparrow/releases/download/v0.3.0/sparrow_0.3.0_linux_amd64.tar.gz -Lo sparrow.tar.gz
curl https://github.com/caas-team/sparrow/releases/download/v0.3.0/sparrow_0.3.0_checksums.txt -Lo checksums.txt
```

Extract the binary:
Expand All @@ -81,27 +83,31 @@ dedicated [release](https://github.com/caas-team/sparrow/releases) can be found

### Helm

Sparrow can be installed via Helm Chart. The chart is provided in the GitHub registry:
Sparrow can be installed via Helm Chart. The chart is available in the GitHub registry:

```sh
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.

To be able to load the configuration during the runtime dynamically, the sparrow loader needs to be set to type `http`.
The default settings are suitable for a local configuration. With the default Helm values, the sparrow loader uses a checks' configuration provided in a ConfigMap (the `file` loader is used). Define the `checksConfig` section to set the ConfigMap.

Use the following configuration values to use a runtime configuration by the `http` loader:

```yaml
startupConfig:
loaderType: http
loaderHttpUrl: https://url-to-runtime-config.de/api/config%2Eyaml
...
loader:
type: http
http:
url: https://url-to-checks-config.de/api/config%2Eyaml

runtimeConfig: { }
checksConfig: {}
```
To provide the sparrow container with the token, manually create a secret containing the `SPARROW_LOADER_HTTP_TOKEN` environment variable. Utilize the `envFromSecrets` in the `values.yaml` to enable access to this secret by the sparrow container. Avoid adding sensitive data like the token used by the `http` loader (`loader.http.token`) directly in the values section.

The same applies to the target manager token. Use the `SPARROW_TARGETMANAGER_GITLAB_TOKEN` in a secret and bind it with the `envFromSecrets` in the `values.yaml`.

For all available value options see [Chart README](./chart/README.md).

Additionally check out the sparrow [configuration](#configuration) variants.
Expand All @@ -126,9 +132,8 @@ e.g. `docker run -v /config:/config ghcr.io/caas-team/sparrow --config /config/

## 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 consists of the checks' configuration.
The configuration is divided into two parts. The startup configuration and the checks' configuration. The startup
configuration is a technical configuration to configure the `sparrow` instance itself.

### Startup

Expand All @@ -148,7 +153,7 @@ Every value in the config file can be set through environment variables.
You can set a token for the http loader:

```bash
export SPARROW_LOADER_HTTP_TOKEN="Bearer xxxxxx"
export SPARROW_LOADER_HTTP_TOKEN="xxxxxx"
```

Or for any other config attribute:
Expand All @@ -159,12 +164,14 @@ export SPARROW_ANY_OTHER_OPTION="Some value"

Just write out the path to the attribute, delimited by `_`.

#### Example configuration
To be able to load the configuration for the [checks](#checks) during runtime dynamically, the sparrow loader needs to be set to type `http`.

#### Example startup configuration

```yaml
# DNS sparrow is exposed on
name: sparrow.example.com
# Selects and configures a loader for continuosly fetching the configuration at runtime
# Selects and configures a loader to continuously fetch the checks' configuration at runtime
loader:
# defines which loader to use. Options: "file | http"
type: http
Expand All @@ -188,15 +195,15 @@ loader:
# The file loader is not intended for production use and does
# not refresh the config after reading it the first time
file:
# where to read the runtime config from
# location of the file in the local filesystem
path: ./config.yaml
# Configures the api
api:
# Which address to expose sparrows rest api on
address: :8080
# Configures the targetmanager
# Configures the target manager
targetManager:
# time between checking for new targets
checkInterval: 1m
Expand All @@ -220,29 +227,25 @@ targetManager:

#### Loader

The loader component of the `sparrow` will load the [Runtime](#runtime) configuration dynamically.
The loader component of the `sparrow` dynamically loads the [checks](#checks)' configuration during runtime.

The loader can be selected by specifying the `loaderType` configuration parameter.
You select which loader is used by setting the `loaderType` parameter.

The default loader is an `http` loader that is able to get the runtime configuration from a remote endpoint.
Available loaders:

Available loader:
- `http` (default): Retrieves the checks' configuration from a remote endpoint during runtime. Additional configuration parameters are set in the `loader.http` section.

- `http`: The default. Loads configuration from a remote endpoint. Token authentication is available. Additional
configuration parameters have the prefix `loaderHttp`.
- `file` (experimental): Loads configuration once from a local file. Additional configuration parameters have the
prefix `loaderFile`. This is just for development purposes.
- `file` (experimental): Intended for development, it loads the configuration once from a local file and does not refresh after the first load. The target manager is currently not functional in combination with this loader type.

### Runtime
### Checks

In addition to the technical startup configuration, the `sparrow` checks' configuration can be dynamically loaded from
an HTTP endpoint during runtime. The `loader` is capable of dynamically loading and configuring checks. You can enable,
disable, and configure checks as needed.
In addition to the technical startup configuration, the `sparrow` checks' configuration can be dynamically loaded from an HTTP endpoint during runtime.
For local use, you may directly load the configuration using a `file` loader. The `loader` is capable of dynamically loading and configuring checks.

For detailed information on available loader configuration options, please refer
to [this documentation](docs/sparrow_run.md).

Example format of a runtime configuration:
Example format of a configuration file for the checks:

```YAML
apiVersion: 0.0.1
Expand All @@ -254,27 +257,21 @@ checks:

### 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 and can be set in the startup YAML configuration file, as shown in
the [example configuration](#example-configuration).

| Type | Description | Default |
|--------------------------------------|-------------------------------------------------------------------------------|----------------------|
| `targetManager.checkInterval` | The interval in seconds to check for new targets. | `300s` |
| `targetManager.unhealthyThreshold` | The threshold in seconds to mark a target as unhealthy and remove it from the
state. | `600s` |
| `targetManager.registrationInterval` | The interval in seconds to register the current sparrow at the targets
backend. | `300s` |
| `targetManager.gitlab.token` | The token to authenticate against the gitlab instance. | `""` |
| `targetManager.gitlab.baseUrl` | 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 `sparrow` can optionally manage targets for checks and register itself as a target on a (remote) backend through the `TargetManager` interface. This feature is optional; if the startup configuration does not include the `targetManager`, it will not be used. When configured, it offers various settings, detailed below, which can be set in the startup YAML configuration file as shown in the [example configuration](#example-startup-configuration).

| Type | Description | Default Value |
| ------------------------------------ | ------------------------------------------------------------------- | -------------------- |
| `targetManager.checkInterval` | Interval for checking new targets. | `300s` |
| `targetManager.unhealthyThreshold` | Threshold for marking a target as unhealthy. | `600s` |
| `targetManager.registrationInterval` | Interval for registering the current sparrow at the target backend. | `300s` |
| `targetManager.gitlab.token` | Token for authenticating with the GitLab instance. | `""` |
| `targetManager.gitlab.baseUrl` | Base URL of the GitLab instance. | `https://gitlab.com` |
| `targetManager.gitlab.projectId` | Project ID for the GitLab project used as a remote state backend. | `""` |

Currently, only one target manager exists: the Gitlab target manager. It 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,
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
Expand All @@ -288,17 +285,29 @@ which is named after the DNS name of the `sparrow`. The state file contains the

Available configuration options:

- `checks.health.targets` (list of strings): List of targets to send health probe. Needs to be a valid url. Can be
another `sparrow` instance. Automatically used when target manager is activated otherwise use the health endpoint of
the remote sparrow, e.g. `https://sparrow-dns.telekom.de/checks/health`.
- `checks`
- `health`
- `interval` (duration): Interval to perform the health check.
- `timeout` (duration): Timeout for the health check.
- `retry`
- `count` (integer): Number of retries for the health check.
- `delay` (duration): Initial delay between retries for the health check.
- `targets` (list of strings): List of targets to send health probe. Needs to be a valid URL. Can be
another `sparrow` instance. Automatically updated when a targetManager is configured.

Example configuration:
#### Example configuration

```YAML
```yaml
checks:
health:
interval: 10s
timeout: 30s
retry:
count: 3
delay: 1s
targets:
- "https://gitlab.devops.telekom.de"
- https://example.com/
- https://google.com/
```

#### Health Metrics
Expand All @@ -318,19 +327,17 @@ Available configuration options:
- `timeout` (duration): Timeout for the latency check.
- `retry`
- `count` (integer): Number of retries for the latency check.
- `delay` (duration): Delay 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. Automatically used when the target manager is enabled otherwise
use latency endpoint, e.g. `https://sparrow-dns.telekom.de/checks/latency`.
- `latencyEndpoint` (boolean): Needs to be activated when the `sparrow` should expose its own latency endpoint.
Mandatory if another `sparrow` instance wants to perform a latency check.
Example configuration:
- `delay` (duration): Initial delay 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. Automatically updated when a targetManager is configured.

#### Example configuration

```yaml
checks:
latency:
interval: 1s
timeout: 3s
interval: 10s
timeout: 30s
retry:
count: 3
delay: 1s
Expand Down Expand Up @@ -358,13 +365,11 @@ 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 for accessing the results of various checks. Each check registers its own endpoint at `/v1/metrics/{check-name}`. The API's definition is available at `/openapi`.

## Metrics

The `sparrow` is providing a `/metrics` endpoint to expose application metrics. Besides metrics about runtime
information the sparrow is also provided `Check` specific metrics. See the Checks section for more information.
The `sparrow` provides a `/metrics` endpoint to expose application metrics. In addition to runtime information, the sparrow provides specific metrics for each check. Refer to the [Checks](#checks) section for more detailed information.

## Code of Conduct

Expand All @@ -386,7 +391,7 @@ 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
Expand Down
6 changes: 3 additions & 3 deletions chart/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ A Helm chart to install Sparrow
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| affinity | object | `{}` | |
| checksConfig.checks | object | `{}` | |
| checksConfig | object | `{"checks":{}}` | Check configuration of the Sparrow read on runtime see: https://github.com/caas-team/sparrow?tab=readme-ov-file#checks |
| env | object | `{}` | |
| envFromSecrets | list | `[]` | extra environment variables Allows you to set environment variables through secrets you defined outside of the helm chart Useful for sensitive information like the http loader token |
| extraArgs | object | `{}` | extra command line start parameters see: https://github.com/caas-team/sparrow/blob/main/docs/sparrow_run.md |
| extraArgs | object | `{}` | Extra command line start parameters see: https://github.com/caas-team/sparrow/blob/main/docs/sparrow_run.md |
| fullnameOverride | string | `""` | |
| image.pullPolicy | string | `"IfNotPresent"` | |
| image.repository | string | `"ghcr.io/caas-team/sparrow"` | |
Expand Down Expand Up @@ -62,6 +62,6 @@ A Helm chart to install Sparrow
| serviceMonitor.interval | string | `"30s"` | Sets the scrape interval |
| serviceMonitor.labels | object | `{}` | Additional label added to the service Monitor |
| serviceMonitor.scrapeTimeout | string | `"5s"` | Sets the scrape timeout |
| sparrowConfig | object | `{"loader":{"path":"/config/checksConfig.yaml","type":"file"},"name":"sparrow.com"}` | startup configuration of the Sparrow see: https://github.com/caas-team/sparrow/blob/main/docs/sparrow_run.md |
| sparrowConfig | object | `{"loader":{"path":"/config/checksConfig.yaml","type":"file"},"name":"sparrow.com"}` | Sparrow configuration read on startup see: https://github.com/caas-team/sparrow/blob/main/docs/sparrow_run.md |
| tolerations | list | `[]` | |

7 changes: 5 additions & 2 deletions chart/values.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ tolerations: []

affinity: {}

# -- extra command line start parameters
# -- Extra command line start parameters
# see: https://github.com/caas-team/sparrow/blob/main/docs/sparrow_run.md
extraArgs: {}

Expand All @@ -105,7 +105,7 @@ envFromSecrets:
# secretName: sparrow-auth
# key: SPARROW_LOADER_HTTP_TOKEN

# -- startup configuration of the Sparrow
# -- Sparrow configuration read on startup
# see: https://github.com/caas-team/sparrow/blob/main/docs/sparrow_run.md
sparrowConfig:
name: sparrow.com
Expand Down Expand Up @@ -134,6 +134,9 @@ sparrowConfig:
# token: ""
# baseUrl: https://gitlab.com
# projectId: ""

# -- Check configuration of the Sparrow read on runtime
# see: https://github.com/caas-team/sparrow?tab=readme-ov-file#checks
checksConfig:
checks: {}
# checks:
Expand Down

0 comments on commit 823a439

Please sign in to comment.