From cd3c928c7856b3377c9af4d03f4c2e58303c2132 Mon Sep 17 00:00:00 2001 From: Aditya Thebe Date: Wed, 20 Dec 2023 10:46:41 +0545 Subject: [PATCH 1/2] feat: add artifacts documentation & exec connections, checkouts, env --- canary-checker/docs/concepts/artifacts.md | 90 +++++++++++++++++++ canary-checker/docs/reference/connections.mdx | 31 +++++++ canary-checker/docs/reference/exec.mdx | 72 +++++++++++---- canary-checker/docs/reference/junit.mdx | 85 ++++++++++-------- canary-checker/sidebars.js | 29 +++--- .../docs/playbooks/actions/exec.md | 2 +- 6 files changed, 240 insertions(+), 69 deletions(-) create mode 100644 canary-checker/docs/concepts/artifacts.md create mode 100644 canary-checker/docs/reference/connections.mdx diff --git a/canary-checker/docs/concepts/artifacts.md b/canary-checker/docs/concepts/artifacts.md new file mode 100644 index 00000000..f5eb8bcb --- /dev/null +++ b/canary-checker/docs/concepts/artifacts.md @@ -0,0 +1,90 @@ +# Artifacts + +Artifacts allow you to archive files generated by some checks to a file store of your choice. + +## Filestores + +- AWS S3 +- Google Cloud Storage +- SFTP +- SMB +- Local Filesystem + +## Setting up artifact store + +One of the above filestores can be used as the global artifact store. To setup an artifact store, pass the connection name of the store using the `artifact-connection` flag. If the artifact connection isn't setup, the artifacts are simply ignored. + +Example: + +```bash +canary-checker --artifact-connection='connection://sftp/artifacts' +``` + +## Archiving artifacts + +The following checks support archiving artifacts + +- [Exec](../reference/exec) +- [Junit](../reference/junit) + +The only configuration required is to provide the path(s) of the artifacts generated by the check. + +### Ex1. Archiving `/tmp/results/` directory + +For the following script in an exec check + +``` +mkdir -p /tmp/results +curl -sL 'https://example.com' > /tmp/results/example.com +curl -sL 'https://flanksource.com' > /tmp/results/flanksource.com +``` + +one can provide the artifact paths as follows + +```yaml title="archive-websites.yaml" +apiVersion: canaries.flanksource.com/v1 +kind: Canary +metadata: + name: exec-artifact +spec: + interval: 30 + exec: + - name: Download example.com and flanksource.com + script: | + mkdir -p /tmp/results + curl -sL 'https://example.com' > /tmp/results/example.com + curl -sL 'https://flanksource.com' > /tmp/results/flanksource.com + artifacts: + - path: /tmp/results/example.com + - path: /tmp/results/flanksource.com +``` + +or, use a glob as + +```yaml +artifacts + - path: '/tmp/results/*.com' +``` + +### Ex2. Archiving artifacts from stdout/stderr + +The path field accepts two special paths + +- `/dev/stdout` +- `/dev/stderr` + +```yaml title="archive-website.yaml" +apiVersion: canaries.flanksource.com/v1 +kind: Canary +metadata: + name: exec-artifact +spec: + interval: 30 + exec: + - name: Archive response of example.com + script: | + curl -sL 'https://example.com' + artifacts: + - path: /dev/stdout + - path: /dev/stderr +``` diff --git a/canary-checker/docs/reference/connections.mdx b/canary-checker/docs/reference/connections.mdx new file mode 100644 index 00000000..a503f123 --- /dev/null +++ b/canary-checker/docs/reference/connections.mdx @@ -0,0 +1,31 @@ +# Connections + +### AWS Connection + +| Field | Description | Type | Required | +| ---------------- | --------------- | ----------------------------------------------------------------------------- | -------- | +| `connectionName` | Connection name | `string` | | +| `accessKey` | Access key | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `secretKey` | Secret key | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `region` | Region | `string` | | +| `endpoint` | Endpoint | `string` | | +| `skipTLSVerify` | Skip TLS verify | `bool` | | +| `objectPath` | Object path | `string` | | +| `usePathStyle` | Use path style | `bool` | | + +### GCP Connection + +| Field | Description | Type | Required | +| ---------------- | --------------- | ----------------------------------------------------------------------------- | -------- | +| `connectionName` | Connection name | `string` | | +| `endpoint` | Endpoint | `string` | | +| `credentials` | Credentials | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | + +### Azure Connection + +| Field | Description | Type | Required | +| ---------------- | --------------- | ----------------------------------------------------------------------------- | -------- | +| `connectionName` | Connection name | `string` | | +| `clientID` | Client ID | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `clientSecret` | Client Secret | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `tenantID` | Tenant ID | `string` | | diff --git a/canary-checker/docs/reference/exec.mdx b/canary-checker/docs/reference/exec.mdx index 9e44ca0f..bb08c077 100644 --- a/canary-checker/docs/reference/exec.mdx +++ b/canary-checker/docs/reference/exec.mdx @@ -6,7 +6,7 @@ title: Exec -Executes a bash (linux) or powershell (windows) script. The check is considered passing if the script exits with `0` +Executes a bash (linux) or powershell (windows) script. The check is considered passing if the script exits with `0` ```yaml apiVersion: canaries.flanksource.com/v1 @@ -16,27 +16,63 @@ metadata: spec: interval: 30 exec: - - description: "exec dummy check" - script: | - echo "hello" - name: exec-pass-check - test: - expr: 'results.Stdout == "hello"' + - description: "exec dummy check" + script: | + echo "hello" + name: exec-pass-check + test: + expr: 'results.Stdout == "hello"' ``` -| Field | Description | Scheme | Required | -| ----- | ----------- | ------ | -------- | -| **`script`** | Script can be a inline script or a path to a script that needs to be executed. On windows executed via Powershell and in darwin and linux executed using bash. | *string* | Yes | -| **`name`** | Name of the check, must be unique within the canary | `string` | Yes | -| `description` | Description for the check | `string` | | -| `icon` | Icon for overwriting default icon on the dashboard | `string` | | -| `labels` | Labels for check | `map[string]string` | | -| `test` | Evaluate whether a check is healthy | [`Expression`](../concepts/health-evaluation) | | -| `display` | Expression to change the formatting of the display | [`Expression`](../concepts/display-formatting) | | -| `transform` | Transform data from a check into multiple individual checks | [`Expression`](../concepts/transforms) | | -| `metrics` | Metrics to export from | [`[]Metrics`](../concepts/metrics-exporter) | | +| Field | Description | Scheme | Required | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------- | +| **`script`** | Script can be a inline script or a path to a script that needs to be executed. On windows executed via Powershell and in darwin and linux executed using bash. | _string_ | Yes | +| **`name`** | Name of the check, must be unique within the canary | `string` | Yes | +| `artifacts` | Specify what files/folders generated by the script needs to be archived | [`[]Artifact`](#artifact) | | +| `checkout` | Specify git repository to mount to the exec process | [`[]GitCheckout`](#git-checkout) | | +| `connections` | Setup connections for the script (eg: aws credentials) | [`ExecConnection`](#exec-connection) | | +| `env` | Setup environment variables that are accessible to the exec process | [`[]types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `namespace` | Namespace of the check | `string` | | +| `description` | Description for the check | `string` | | +| `icon` | Icon for overwriting default icon on the dashboard | `string` | | +| `labels` | Labels for check | `map[string]string` | | +| `metrics` | Metrics to export from | [`[]Metrics`](../concepts/metrics-exporter) | | +| `test` | Evaluate whether a check is healthy | [`Expression`](../concepts/health-evaluation) | | +| `display` | Expression to change the formatting of the display | [`Expression`](../concepts/display-formatting) | | +| `transform` | Transform data from a check into multiple individual checks | [`Expression`](../concepts/transforms) | | :::tip Docker Image variants See [image-variants](../concepts/image-variants) ::: +### Exec Connection + +Exec connections allow you to specify credentials for a list of CLI tools that are needed by your scripts. Eg: You can specify the AWS connection name and the credential files along with the necessary environment variables +will be setup on the host running the script. + +| Field | Description | Type | Required | +| ------- | ---------------- | ----------------------------------------------------------------- | -------- | +| `aws` | AWS connection | [`AWSConnection`](../reference/connections.md#aws-connection) | | +| `gcp` | GCP connection | [`GCPConnection`](../reference/connections.md#gcp-connection) | | +| `azure` | Azure connection | [`AzureConnection`](../reference/connections.md#azure-connection) | | + +### Artifact + +| Field | Description | Type | Required | +| ------ | ------------- | -------- | -------- | +| `path` | Path or glob. | `string` | `true` | + +[Read more ...](../concepts/artifacts) + +### Git Checkout + +For authentication, either provide the connection name or the basic auth or the certificate. + +| Field | Description | Type | Required | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------- | +| `url` | Git repository URL. | `string` | `true` | +| `connection` | Specify the connection name to use for git authentication (if required) | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `username` | Git auth username. | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `password` | Git auth password. | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `certificate` | Git auth certificate. | [`types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | +| `destination` | Destination is the full path to where the contents of the URL should be downloaded to. If left empty, the sha256 hash of the URL will be used as the dir name. | `string` | | diff --git a/canary-checker/docs/reference/junit.mdx b/canary-checker/docs/reference/junit.mdx index 5a622454..06ad4e34 100644 --- a/canary-checker/docs/reference/junit.mdx +++ b/canary-checker/docs/reference/junit.mdx @@ -37,53 +37,62 @@ spec: command: ["/start.sh"] ``` -| Field | Description | Scheme | Required | -| ----- | ----------- | ------ | -------- | -| **`spec`** | Pod specification | [*v1.PodSpec*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podspec-v1-core) | Yes | -| **`testResults`** | Directory where the results will be published | *string* | Yes | -| `timeout` | Timeout in minutes to wait for specified container to finish its job. Defaults to 5 minutes | *int* | | -| **`name`** | Name of the check, must be unique within the canary | `string` | Yes | -| `description` | Description for the check | `string` | | -| `icon` | Icon for overwriting default icon on the dashboard | `string` | | -| `labels` | Labels for check | `map[string]string` | | -| `test` | Evaluate whether a check is healthy | [`Expression`](../concepts/health-evaluation) | | -| `display` | Expression to change the formatting of the display | [`Expression`](../concepts/display-formatting) | | -| `transform` | Transform data from a check into multiple individual checks | [`Expression`](../concepts/transforms) | | -| `metrics` | Metrics to export from | [`[]Metrics`](../concepts/metrics-exporter) | | +| Field | Description | Scheme | Required | +| ----------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | +| **`spec`** | Pod specification | [_v1.PodSpec_](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podspec-v1-core) | Yes | +| **`testResults`** | Directory where the results will be published | _string_ | Yes | +| `timeout` | Timeout in minutes to wait for specified container to finish its job. Defaults to 5 minutes | _int_ | | +| **`name`** | Name of the check, must be unique within the canary | `string` | Yes | +| `artifacts` | Specify what files/folders generated by the script needs to be archived | [`[]Artifact`](#artifact) | | +| `description` | Description for the check | `string` | | +| `icon` | Icon for overwriting default icon on the dashboard | `string` | | +| `labels` | Labels for check | `map[string]string` | | +| `test` | Evaluate whether a check is healthy | [`Expression`](../concepts/health-evaluation) | | +| `display` | Expression to change the formatting of the display | [`Expression`](../concepts/display-formatting) | | +| `transform` | Transform data from a check into multiple individual checks | [`Expression`](../concepts/transforms) | | +| `metrics` | Metrics to export from | [`[]Metrics`](../concepts/metrics-exporter) | | ## Test Result Variables -| Name | Description | Scheme | -| ---------- | --------------------- | ---------------- | -| `suites` | | [`[]JunitSuite`](#junit-suite) | -| `passed` | Number of passing tests | *int* | -| `failed` | Number of failed tests | *int* | -| `skipped` | NUmber of tests that were skipped | *int* | -| `error` | Number of errors produced when running the tests | *int* | -| `duration` | Total time in seconds | *float64* | +| Name | Description | Scheme | +| ---------- | ------------------------------------------------ | ------------------------------ | +| `suites` | | [`[]JunitSuite`](#junit-suite) | +| `passed` | Number of passing tests | _int_ | +| `failed` | Number of failed tests | _int_ | +| `skipped` | NUmber of tests that were skipped | _int_ | +| `error` | Number of errors produced when running the tests | _int_ | +| `duration` | Total time in seconds | _float64_ | ### Junit Suite -| Name | Description | Scheme | -| ---------- | --------------------- | ---------------- | -| `name` | | *string* | -| `tests` | | [`[]JunitTest`](#junit-test) | -| `passed` | Number of passing tests | *int* | -| `failed` | Number of failed tests | *int* | -| `skipped` | NUmber of tests that were skipped | *int* | -| `error` | Number of errors produced when running the tests | *int* | -| `duration` | Total time in seconds | *float64* | +| Name | Description | Scheme | +| ---------- | ------------------------------------------------ | ---------------------------- | +| `name` | | _string_ | +| `tests` | | [`[]JunitTest`](#junit-test) | +| `passed` | Number of passing tests | _int_ | +| `failed` | Number of failed tests | _int_ | +| `skipped` | NUmber of tests that were skipped | _int_ | +| `error` | Number of errors produced when running the tests | _int_ | +| `duration` | Total time in seconds | _float64_ | ### Junit Test | Name | Description | Scheme | | ------------ | ------------------------------------------------------- | ------------------- | -| `name` | | *string* | -| `classname` | an additional descriptor for the hierarchy of the test. | *string* | -| `duration` | Time in seconds | *float64* | -| `status` | One of `passed`, `skipped`, `failed` or `error` | *string* | -| `message` | Description optionally included with a skipped, | *string* | +| `name` | | _string_ | +| `classname` | an additional descriptor for the hierarchy of the test. | _string_ | +| `duration` | Time in seconds | _float64_ | +| `status` | One of `passed`, `skipped`, `failed` or `error` | _string_ | +| `message` | Description optionally included with a skipped, | _string_ | | `properties` | Additional info about the test | `map[string]string` | -| `error` | Any errors encountered when running atest | *string* | -| `stdout` | Standard output produced during test | *string* | -| `stderr` | Standard error output produced during test | *string* | +| `error` | Any errors encountered when running atest | _string_ | +| `stdout` | Standard output produced during test | _string_ | +| `stderr` | Standard error output produced during test | _string_ | + +### Artifact + +| Field | Description | Type | Required | +| ------ | ------------- | -------- | -------- | +| `path` | Path or glob. | `string` | `true` | + +[Read more ...](../concepts/artifacts) diff --git a/canary-checker/sidebars.js b/canary-checker/sidebars.js index 98dd618a..435ae9da 100644 --- a/canary-checker/sidebars.js +++ b/canary-checker/sidebars.js @@ -49,6 +49,12 @@ module.exports = { id: 'concepts/metrics-exporter', label: 'Metrics Exporter', }, + { + type: 'doc', + + id: 'concepts/artifacts', + label: 'Artifacts', + }, { @@ -105,7 +111,6 @@ module.exports = { link: { type: 'generated-index', title: 'Probes / Alerts', - // description: 'Learn about the most important Docusaurus concepts!', slug: '/types', keywords: ['guides'], image: '/img/docusaurus.png', @@ -116,7 +121,6 @@ module.exports = { id: 'reference/http', label: 'HTTP', }, - { type: 'doc', id: 'reference/tcp', @@ -132,7 +136,6 @@ module.exports = { id: 'reference/icmp', label: 'ICMP', }, - { type: 'doc', id: 'reference/alert-manager', @@ -148,11 +151,8 @@ module.exports = { id: 'reference/aws-config-rule', label: 'AWS Config Rule', }, - - ], }, - { type: 'category', label: 'Folder / Backups', @@ -260,31 +260,25 @@ module.exports = { ], }, - - { type: 'category', label: 'Active / Integration', items: [ - { type: 'doc', id: 'reference/exec', label: 'Exec', }, - { type: 'doc', id: 'reference/junit', label: 'JUnit', }, - { type: 'doc', id: 'reference/azure-devops', label: 'Azure DevOps', }, - ], }, { @@ -377,5 +371,16 @@ module.exports = { }, ], }, + { + type: 'category', + label: 'References', + items: [ + { + type: 'doc', + id: 'reference/connections', + label: 'Connections', + }, + ], + } ], }; diff --git a/mission-control/docs/playbooks/actions/exec.md b/mission-control/docs/playbooks/actions/exec.md index b5571a92..b7e3327c 100644 --- a/mission-control/docs/playbooks/actions/exec.md +++ b/mission-control/docs/playbooks/actions/exec.md @@ -40,7 +40,7 @@ spec: | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------- | ----------- | | `script` | Script can be an inline script or a path to a script that needs to be executed. Executed via Powershell on windows and via bash on Darwin and Linux. | _string_ | `true` | `true` | | `connections` | Connections for some CLIs | [`ExecConnection`](#exec-connection) | | | -| `artifacts` | Specify what artifacts generated by the exec action needs to be saved | [`[]Artifact`](#artifacts) | | | +| `artifacts` | Specify what artifacts generated by the exec action needs to be saved | [`[]Artifact`](#artifact) | | | | `env` | Specify environment variables that are available to exec processes | [`[]types.EnvVar`](https://pkg.go.dev/github.com/flanksource/duty/types#EnvVar) | | | | `checkout` | Checkout details the git repository that should be mounted to the process | [`[]GitCheckout`](#git-checkout) | | | From 2be4ac50d9f0615f7242016a647f24b69d55b139 Mon Sep 17 00:00:00 2001 From: Aditya Thebe Date: Wed, 20 Dec 2023 11:16:11 +0545 Subject: [PATCH 2/2] feat: docs for canary scaling up/down --- canary-checker/docs/concepts/scaling.md | 43 +++++++++++++++++++++++++ canary-checker/sidebars.js | 8 +++-- 2 files changed, 48 insertions(+), 3 deletions(-) create mode 100644 canary-checker/docs/concepts/scaling.md diff --git a/canary-checker/docs/concepts/scaling.md b/canary-checker/docs/concepts/scaling.md new file mode 100644 index 00000000..6a0d98eb --- /dev/null +++ b/canary-checker/docs/concepts/scaling.md @@ -0,0 +1,43 @@ +# Scaling Canaries up/down + +Canaries can be scaled up or down just like other kubernetes resources. However, scaling to more than one replica is identical to having just one replica. In other words, scaling a canary can be thought of as a mechanism to turn on/off the canary. + +## Example + +1. List all the canaries + +```bash +kubectl get canaries -o wide +# NAME REPLICAS INTERVAL STATUS LAST CHECK UPTIME 1H LATENCY 1H LAST TRANSITIONED ... +# folder-pass 1 300 Failed 34s 0/35 0% 16ms +# folder-pass-empty 1 300 Passed 34s 37/37 (100.0%) 0ms +# s3-bucket-pass 1 30 Failed 3s 0/358 0% 1s +``` + +2. Scale one of the canaries to 10 replicas + +```bash +kubectl scale --replicas=10 canaries.canaries.flanksource.com folder-pass +# canary.canaries.flanksource.com/folder-pass scaled +``` + +```bash +kubectl get canaries folder-pass -o wide +# NAME REPLICAS INTERVAL STATUS LAST CHECK UPTIME 1H LATENCY 1H LAST TRANSITIONED MESSAGE ERROR +# folder-pass 10 300 Failed 3m13s 0/35 0% 16ms +``` + +3. Scale it down to 0 replicas + +```bash +kubectl scale --replicas=0 canaries.canaries.flanksource.com folder-pass +# canary.canaries.flanksource.com/folder-pass scaled +``` + +```bash +kubectl get canaries folder-pass -o wide +# NAME REPLICAS INTERVAL STATUS LAST CHECK UPTIME 1H LATENCY 1H LAST TRANSITIONED MESSAGE ERROR +# folder-pass 0 300 Failed 3m13s 0/35 0% 16ms +``` + +This effectively stops the canary from running. diff --git a/canary-checker/sidebars.js b/canary-checker/sidebars.js index 435ae9da..19cd662a 100644 --- a/canary-checker/sidebars.js +++ b/canary-checker/sidebars.js @@ -51,12 +51,14 @@ module.exports = { }, { type: 'doc', - id: 'concepts/artifacts', label: 'Artifacts', }, - - + { + type: 'doc', + id: 'concepts/scaling', + label: 'Scaling Canaries', + }, { type: 'doc', id: 'concepts/secret-management',