From f558155714c2d2dd6fdbc3f8db66411fb00c5278 Mon Sep 17 00:00:00 2001 From: Vibhor Dabas Date: Wed, 20 Dec 2023 18:00:34 +0530 Subject: [PATCH 1/2] fix: update installation docs --- .../docs/concepts/metrics-exporter.md | 2 +- canary-checker/docs/database.md | 4 +-- canary-checker/docs/getting-started.md | 19 +++++++++++--- canary-checker/docs/helm.md | 26 +++++++++---------- 4 files changed, 32 insertions(+), 19 deletions(-) diff --git a/canary-checker/docs/concepts/metrics-exporter.md b/canary-checker/docs/concepts/metrics-exporter.md index 2bfc808d..13fbb223 100644 --- a/canary-checker/docs/concepts/metrics-exporter.md +++ b/canary-checker/docs/concepts/metrics-exporter.md @@ -4,7 +4,7 @@ title: Metrics Exporter -Canary checker can export custom metrics from any check type, replacing and/or consolidating multiple standaline Prometheus Exporters into a single exporter. +Canary checker can export custom metrics from any check type, replacing and/or consolidating multiple standalone Prometheus Exporters into a single exporter. In the example below, exchange rates against the USD are exported by first calling an HTTP api and then using the values from the JSON response to create the metrics: diff --git a/canary-checker/docs/database.md b/canary-checker/docs/database.md index 38df0f61..2afd6fef 100644 --- a/canary-checker/docs/database.md +++ b/canary-checker/docs/database.md @@ -48,7 +48,7 @@ To specify a username and password for the chart-managed Postgres server, create ### Connecting to an external db -In order to connect to an existing Postgres server, a database must be created on the server, along with a user that has administrator permissions for the database.git +In order to connect to an existing Postgres server, a database must be created on the server, along with a user that has administrator permissions for the database. ```yaml title="values.yaml" db: @@ -57,6 +57,6 @@ db: create: false secretKeyRef: name: postgres-connection # name of secret that contains a key containging the postgres connection URI - key: POSTGRES_URL # name of the key in the secret that contains the postgres connection URI + key: POSTGRES_URL # name of the key in the secret that contains the postgres connection URI. The URI must be in the format 'postgresql://"$user":"$password"@"$host"/"$database"' # ... ``` diff --git a/canary-checker/docs/getting-started.md b/canary-checker/docs/getting-started.md index 7545cb5e..72ce9e2f 100644 --- a/canary-checker/docs/getting-started.md +++ b/canary-checker/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -1. Install canary checker: +## Install canary checker ```bash helm repo add flanksource https://flanksource.github.io/charts @@ -8,7 +8,7 @@ helm install canary-checker flanksource/canary-checker -n "canary-checker" --create-namespace ``` -2. Create a new check +## Create a new check ```yaml title="canary.yaml" apiVersion: canaries.flanksource.com/v1 @@ -24,7 +24,7 @@ url: https://httpbin.demo.aws.flanksource.com/status/500 ``` - And then apply it to the cluster: +And then apply it to the cluster: ```shell kubectl apply -f canary.yaml @@ -52,6 +52,19 @@ ![](./images/http-checks.png) +[http://localhost:8080](http://localhost:8080) + +The canary checker itself only presents an API. To view the data graphically, the Flanksource UI is required, and is installed by default. The UI should be configured in [values.yaml](https://github.com/flanksource/canary-checker/blob/699f31a2326034f761ba1b30d966436d6318dd06/chart/values.yaml#L105) to allow external access via ingress + +| Parameter | Description | +|------------------------------------|---------------------------------------------------------------| +| `flanksource-ui.ingress.host` | URL at which the UI will be accessed | +| `flanksource-ui.ingress.annotations` | Map of annotations required by the ingress controller or certificate issuer | +| `flanksource-ui.ingress.tls` | Map of configuration options for TLS | + +More details regarding ingress configuration can be found in the [kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) + + ## Getting Help If you have any questions about canary checker: diff --git a/canary-checker/docs/helm.md b/canary-checker/docs/helm.md index 14485a76..d88a8b76 100644 --- a/canary-checker/docs/helm.md +++ b/canary-checker/docs/helm.md @@ -7,14 +7,14 @@ image: /static/img/icons/helm.svg The recommended method for installing Canary Checker is using [helm](https://helm.sh/) -### 1. Add the Flanksource helm repository +## 1. Add the Flanksource helm repository ```bash helm repo add flanksource https://flanksource.github.io/charts helm repo update ``` -### 2. Deploy Canary Checker using Helm +## 2. Deploy Canary Checker using Helm To install into a new `canary-checker` namespace, run @@ -61,16 +61,15 @@ spec: EOF ``` -## 4. Check the results via the CLI +## 4. Check the results via the [CLI](./cli) ```bash kubectl get canary ``` ```shell-session -$ kubectl get canary -NAME INTERVAL STATUS LAST CHECK UPTIME 1H LATENCY 1H LAST TRANSITIONED -http-check. 30 Passed 13s 18/18 (100.0%) 480ms 13s +NAME INTERVAL STATUS LAST CHECK UPTIME 1H LATENCY 1H LAST TRANSITIONED +http-check 30 Passed 13s 18/18 (100.0%) 480ms 13s ``` ## 5. Access the dashboard @@ -78,16 +77,17 @@ http-check. 30 Passed 13s 18/18 (100.0%) 480ms You can access the web dashboard by forwarding the port: ```bash -kubectl port-forward svc/canary-checker-ui 8080:80 +kubectl -n canary-checker port-forward svc/canary-checker-ui 8080:80 ``` - +![](./images/http-checks.png) [http://localhost:8080](http://localhost:8080) -The canary checker itself only presents an API. To view the data graphically, the Flanksource UI is required, and is installed by default. The UI should be configured to allow external access to via ingress +The canary checker itself only presents an API. To view the data graphically, the Flanksource UI is required, and is installed by default. The UI should be configured to allow external access via ingress -| ---------------------------------- | ------------------------------------------------------------ | -| flanksource-ui.ingress.host | URL at which the UI will be accessed | -| flanksource-ui.ingress.annotations | Map of annotations required by the ingress controller or certificate issuer | -| flanksource-ui.ingress.tls | Map of configuration options for TLS | +| Parameter | Description | +|------------------------------------|---------------------------------------------------------------| +| `flanksource-ui.ingress.host` | URL at which the UI will be accessed | +| `flanksource-ui.ingress.annotations` | Map of annotations required by the ingress controller or certificate issuer | +| `flanksource-ui.ingress.tls` | Map of configuration options for TLS | More details regarding ingress configuration can be found in the [kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) From e94eeb09de0ca8363993248dce30b0a9e96d5945 Mon Sep 17 00:00:00 2001 From: Vibhor Dabas Date: Tue, 26 Dec 2023 13:09:33 +0530 Subject: [PATCH 2/2] fix: getting started and concepts section --- canary-checker/docs/concepts/grafana.md | 2 +- .../docs/concepts/health-evaluation.md | 2 +- .../docs/concepts/metrics-exporter.md | 2 +- canary-checker/docs/concepts/transforms.md | 1 + .../docs/concepts/troubleshooting.md | 6 +- canary-checker/docs/getting-started.md | 6 ++ canary-checker/docs/helm.md | 72 ++++++++++++++++++- 7 files changed, 82 insertions(+), 9 deletions(-) diff --git a/canary-checker/docs/concepts/grafana.md b/canary-checker/docs/concepts/grafana.md index d18a2e86..331ec8ff 100644 --- a/canary-checker/docs/concepts/grafana.md +++ b/canary-checker/docs/concepts/grafana.md @@ -1,6 +1,6 @@ # Grafana -Default grafana dashboards are available, they can be installed with +Default grafana dashboards are available. After you deploy Grafana, these dashboards can be installed with ``` --set grafanaDashboards=true --set serviceMonitor=true diff --git a/canary-checker/docs/concepts/health-evaluation.md b/canary-checker/docs/concepts/health-evaluation.md index 900f04d1..ba3f4548 100644 --- a/canary-checker/docs/concepts/health-evaluation.md +++ b/canary-checker/docs/concepts/health-evaluation.md @@ -16,7 +16,7 @@ spec: - name: http pass response 200 status code endpoint: https://httpbin.demo.aws.flanksource.com/status/200 test: - expr: "code in [200,201,301] and sslAge < Duration('7d')" + expr: "code in [200,201,301] && sslAge < Duration('7d')" ``` :::info Boolean diff --git a/canary-checker/docs/concepts/metrics-exporter.md b/canary-checker/docs/concepts/metrics-exporter.md index fda944e5..d54604aa 100644 --- a/canary-checker/docs/concepts/metrics-exporter.md +++ b/canary-checker/docs/concepts/metrics-exporter.md @@ -47,7 +47,7 @@ spec: value: ILS - name: exchange_rate_api type: histogram - valueExpr: result.elapsed.getMilliseconds() + value: result.elapsed.getMilliseconds() ``` Which would output: diff --git a/canary-checker/docs/concepts/transforms.md b/canary-checker/docs/concepts/transforms.md index a73b3d4b..a00e4ed8 100644 --- a/canary-checker/docs/concepts/transforms.md +++ b/canary-checker/docs/concepts/transforms.md @@ -15,6 +15,7 @@ spec: schedule: "*/5 * * * *" alertmanager: - url: alertmanager.example.com + name: alert-manager-transform alerts: - .* ignore: diff --git a/canary-checker/docs/concepts/troubleshooting.md b/canary-checker/docs/concepts/troubleshooting.md index f8876df4..d09c7b7e 100644 --- a/canary-checker/docs/concepts/troubleshooting.md +++ b/canary-checker/docs/concepts/troubleshooting.md @@ -6,7 +6,7 @@ ## Enable trace and debug - To increase the amount of logs for a particular trace add a `trace: true` annotation: + To increase the amount of logs for a particular trace add a `debug: true` or `trace: true` annotation: ```yaml trace.yaml apiVersion: canaries.flanksource.com/v1 @@ -36,10 +36,10 @@ ## Run checks immediately using `next-runtime` -To run a canary outside of its normall schedule add the annotation: +To run a canary outside of its normal schedule add the annotation: ```bash - kubectl annotate canary next-runtime=$(date -Iseconds) -n + kubectl annotate canary next-runtime=$(date -Iseconds) ``` ## Temporarily pause a canary using `suspend` diff --git a/canary-checker/docs/getting-started.md b/canary-checker/docs/getting-started.md index 72ce9e2f..8771b55b 100644 --- a/canary-checker/docs/getting-started.md +++ b/canary-checker/docs/getting-started.md @@ -50,6 +50,12 @@ And then apply it to the cluster: 4. Check the Dashboard +You can access the web dashboard by forwarding the port: + +```bash +kubectl -n canary-checker port-forward svc/canary-checker-ui 8080:80 +``` + ![](./images/http-checks.png) [http://localhost:8080](http://localhost:8080) diff --git a/canary-checker/docs/helm.md b/canary-checker/docs/helm.md index 3dad2b66..4aa3525e 100644 --- a/canary-checker/docs/helm.md +++ b/canary-checker/docs/helm.md @@ -7,15 +7,17 @@ image: /static/img/icons/helm.svg The recommended method for installing Canary Checker is using [helm](https://helm.sh/) -## 1. Add the Flanksource helm repository +## 1. Deploy Canary Checker + +### Using Helm + +Add the Flanksource helm repository ```bash helm repo add flanksource https://flanksource.github.io/charts helm repo update ``` -## 2. Deploy Canary Checker using Helm - To install into a new `canary-checker` namespace, run ```bash @@ -41,6 +43,70 @@ flanksource-ui: - canary-checker.127.0.0.1.nip.io ``` +### Using Flux CD + +```yaml title=helmrelease.yaml +apiVersion: v1 +kind: Namespace +metadata: + name: canary-checker +--- +apiVersion: source.toolkit.fluxcd.io/v1beta2 +kind: HelmRepository +metadata: + name: flanksource + namespace: canary-checker +spec: + interval: 5m + url: https://flanksource.github.io/charts +--- +apiVersion: helm.toolkit.fluxcd.io/v2beta1 +kind: HelmRelease +metadata: + name: canary-checker + namespace: canary-checker +spec: + interval: 5m + chart: + spec: + chart: canary-checker + sourceRef: + kind: HelmRepository + name: flanksource + interval: 1m + values: + flanksource-ui: + ingress: + host: canary-checker.127.0.0.1.nip.io + annotations: + kubernetes.io/ingress.class: nginx + kubernetes.io/tls-acme: "true" + tls: + - secretName: canary-checker-tls + hosts: + - canary-checker.127.0.0.1.nip.io +``` + +```yaml title=canary-checker-kustomization.yaml +apiVersion: kustomize.toolkit.fluxcd.io/v1 +kind: Kustomization +metadata: + name: canary-checker + namespace: flux-system +spec: + interval: 5m + sourceRef: + kind: GitRepository + name: + path: path/to/canary-checker/helmrelease/folder + prune: true + healthChecks: # wait for the HelmRelease to be reconciled with + - apiVersion: helm.toolkit.fluxcd.io/v2beta1 + kind: HelmRelease + name: canary-checker + namespace: canary-checker +``` + :::info Note the default installation of canary-checker uses an embedded postgres database and does not persist history, see: [Database](database) :::