From 29e45f44bf447185dc871945a98b9caddbd73234 Mon Sep 17 00:00:00 2001 From: Jacob Pleiness Date: Mon, 23 Jan 2023 13:57:09 -0500 Subject: [PATCH 1/3] Update docs for `src validate kube` command --- doc/admin/validation.md | 47 ++++++++++++++++++++++++-- doc/cli/references/index.md | 2 +- doc/cli/references/validate.md | 26 -------------- doc/cli/references/validate/index.md | 7 ++++ doc/cli/references/validate/install.md | 47 ++++++++++++++++++++++++++ doc/cli/references/validate/kube.md | 38 +++++++++++++++++++++ 6 files changed, 137 insertions(+), 30 deletions(-) delete mode 100644 doc/cli/references/validate.md create mode 100644 doc/cli/references/validate/index.md create mode 100644 doc/cli/references/validate/install.md create mode 100644 doc/cli/references/validate/kube.md diff --git a/doc/admin/validation.md b/doc/admin/validation.md index 28d040dd9807..ed1cd1d4ec9f 100644 --- a/doc/admin/validation.md +++ b/doc/admin/validation.md @@ -1,14 +1,16 @@ # Sourcegraph Instance Validation ->🚨 WARNING 🚨: **Sourcegraph Instance Validation is currently experimental.** We're exploring this feature set. +>🚨 WARNING 🚨: **Sourcegraph Validation is currently experimental.** We're exploring this feature set. >Let us know what you think! [File an issue](https://github.com/sourcegraph/sourcegraph/issues/new/choose) >with feedback/problems/questions, or [contact us directly](https://about.sourcegraph.com/contact). -Instance validation provides a quick way to check that a Sourcegraph instance functions properly after a fresh install +## Validate Sourcegraph Installation + +Installation validation provides a quick way to check that a Sourcegraph installation functions properly after a fresh install or an update. The [`src` CLI](https://github.com/sourcegraph/src-cli) has an experimental command `validate install` which drives the - validation from a user-provided configuration file with a validation specification (in JSON or YAML format). If no validation specification file is provided it will execute the following: + validation from a user-provided configuration file with a validation specification (in JSON or YAML format). If no validation specification file is provided it will execute the following defaults: * temporarily adds an external service * waits for a repository to be cloned @@ -174,3 +176,42 @@ src validate install The `src` binary finds the Sourcegraph instance to validate from the environment variables [`SRC_ENDPOINT` and `SRC_ACCESS_TOKEN`](https://github.com/sourcegraph/src-cli#setup-with-your-sourcegraph-instance). + +## Validate Sourcegraph Kubernetes Deployment + +Kubernetes deployment validation provides a quick way to check that a Sourcegraph deployment on Kubernetes is configured correctly. + +The [`src` CLI](https://github.com/sourcegraph/src-cli) has an experimental command `validate kube` which performs validation of a Sourcegraph deployment on Kubernetes. These validation checks include: + +* Pod validation +* Service validation +* Persistent Volume Claim (PVC) validation +* Inter-Service network connection validation + +These validations can also include warnings for non-failure states that should be address, e.g. high restart counts. + +### Cluster Authentication + +Kubernetes cluster authentication is handled via a standard [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) file. You can also use the `--kubeconfig` option to use a different configuration file. By default this program will use the default file used by `kubectl`. + +### Usage + +Use the [`src` CLI](https://github.com/sourcegraph/src-cli) to validate Kubernetes deployment: +```shell script +src validate kube +``` + +Specify a non-default Kubernetes namespace: +```shell script +src validate kube --namespace sourcegraph +``` + +Specify a different kubeconfig file: +```shell script +src validate kube --kubeconfig ~/.kube/config +``` + +Silence output: +```shell script +src validate kube --quiet +``` diff --git a/doc/cli/references/index.md b/doc/cli/references/index.md index 8083df0bae1c..902249359945 100644 --- a/doc/cli/references/index.md +++ b/doc/cli/references/index.md @@ -18,6 +18,6 @@ * [`serve-git`](serve-git.md) * [`snapshot`](snapshot.md) * [`users`](users/index.md) -* [`validate`](validate.md) +* [`validate`](validate/index.md) * [`version`](version.md) \ No newline at end of file diff --git a/doc/cli/references/validate.md b/doc/cli/references/validate.md deleted file mode 100644 index d559c3b197c5..000000000000 --- a/doc/cli/references/validate.md +++ /dev/null @@ -1,26 +0,0 @@ -# `src validate` - - - -## Usage - -``` -'src validate' is a tool that validates a Sourcegraph instance. - -EXPERIMENTAL: 'validate' is an experimental command in the 'src' tool. - -Please visit https://docs.sourcegraph.com/admin/validation for documentation of the validate command. - -Usage: - - src validate command [command options] - -The commands are: - - install validates a Sourcegraph installation - -Use "src validate [command] -h" for more information about a command. - - -``` - \ No newline at end of file diff --git a/doc/cli/references/validate/index.md b/doc/cli/references/validate/index.md new file mode 100644 index 000000000000..0fb78b8114bc --- /dev/null +++ b/doc/cli/references/validate/index.md @@ -0,0 +1,7 @@ +# `src validate` + +## Subcommands + + +* [`install`](install.md) +* [`kube`](kube.md) \ No newline at end of file diff --git a/doc/cli/references/validate/install.md b/doc/cli/references/validate/install.md new file mode 100644 index 000000000000..f348a3116338 --- /dev/null +++ b/doc/cli/references/validate/install.md @@ -0,0 +1,47 @@ +# `src validate install` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` | +| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | + +## Usage + +``` +Usage of 'src validate install': + -dump-requests + Log GraphQL requests and responses to stdout + -get-curl + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) + -insecure-skip-verify + Skip validation of TLS certificates against trusted chains + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + -user-agent-telemetry + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) +'src validate install' is a tool that validates a Sourcegraph installation. + +Examples: + + Run default checks: + + $ src validate install + + Provide a YAML configuration file: + + $ src validate install config.yml + + Provide a JSON configuration file: + + $ src validate install config.json + +Environmental variables + + SRC_GITHUB_TOKEN GitHub access token for validation features +``` \ No newline at end of file diff --git a/doc/cli/references/validate/kube.md b/doc/cli/references/validate/kube.md new file mode 100644 index 000000000000..4c6a83f12617 --- /dev/null +++ b/doc/cli/references/validate/kube.md @@ -0,0 +1,38 @@ +# `src validate kube` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-kubeconfig` | Absolute path to the kubeconfig file | `~/.kube/config` | +| `-namespace` | Specify the Kubernetes namespace to use | `default` | +| `-quiet` | Suppress output and return exit status only | `false` | + + +## Usage + +``` +Usage of 'src validate kube': + -kubeconfig string + (optional) absolute path to the kubeconfig file (default "~/.kube/config") + -namespace string + (optional) specify the kubernetes namespace to use + -quiet + (optional) suppress output and return exit status only +'src validate kube' is a tool that validates a Kubernetes based Sourcegraph deployment + +Examples: + + Run default deployment validation: + $ src validate kube + + Specify Kubernetes namespace: + $ src validate kube --namespace sourcegraph + + Specify the kubeconfig file location: + $ src validate kube --kubeconfig ~/.kube/config + + Suppress output (useful for CI/CD pipelines) + $ src validate kube --quiet +``` \ No newline at end of file From 099bfb3a6341132cab07946b79d14f22d5c21328 Mon Sep 17 00:00:00 2001 From: Jacob Pleiness Date: Tue, 24 Jan 2023 14:35:08 -0500 Subject: [PATCH 2/3] Fix types in docs --- doc/admin/validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/admin/validation.md b/doc/admin/validation.md index ed1cd1d4ec9f..c45c353d6677 100644 --- a/doc/admin/validation.md +++ b/doc/admin/validation.md @@ -188,7 +188,7 @@ The [`src` CLI](https://github.com/sourcegraph/src-cli) has an experimental comm * Persistent Volume Claim (PVC) validation * Inter-Service network connection validation -These validations can also include warnings for non-failure states that should be address, e.g. high restart counts. +These validations can also include warnings for non-failure states that should be addressed, e.g. high restart counts. ### Cluster Authentication From b32e10501bf07fd5171b0ca6b4af38626eb33d68 Mon Sep 17 00:00:00 2001 From: Jacob Pleiness Date: Tue, 24 Jan 2023 14:41:55 -0500 Subject: [PATCH 3/3] Add `deleteWhenDone` to example configs --- doc/admin/validation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/admin/validation.md b/doc/admin/validation.md index c45c353d6677..59497515372c 100644 --- a/doc/admin/validation.md +++ b/doc/admin/validation.md @@ -74,6 +74,7 @@ insight: "timeScopeValue": 1 } ] + deleteWhenDone: true ``` #### JSON File Specification @@ -124,7 +125,8 @@ insight: "timeScopeUnit": "MONTH", "timeScopeValue": 1 } - ] + ], + "deleteWhenDone": true } }