Merge pull request #379 from kosli-dev/add-what-do-i-do-if-kosli-is-down-faq

Add what-do-i-do-if-kosli-is-down tutorial (linked from faq)

Author: JonJagger

docs.kosli.com/content/faq/_index.md

@@ -11,6 +11,10 @@ If you can't find the answer you're looking for please:
 * email us at [[email protected]](mailto:[email protected])
 * join our slack community [here](https://join.slack.com/t/koslicommunity/shared_invite/zt-1dlchm3s7-DEP6TKjP3Mr58OZVB3hCBw)
 
+## What do I do if Kosli is down?
+
+There is a [tutorial](/tutorials/what_do_i_do_if_kosli_is_down/) dedicated to this.
+
 ## Why am I getting "unknown flag" error?
 
 If you see an error like below (or similar, with a different flag):

docs.kosli.com/content/getting_started/install.md

@@ -113,7 +113,7 @@ Among these options, priority is given in the following order: Option 1 holds th
 
 ### Assigning flags via environment variables
 
-To assign a CLI flag using environment variables, generate a variable prefixed with KOSLI_. Utilize the flag's name in uppercase and substitute any internal dashes with underscores. For instance:
+To assign a CLI flag using environment variables, generate a variable prefixed with KOSLI_. Use the flag's name in uppercase and substitute any internal dashes with underscores. For instance:
 
 
 * `--api-token` corresponds to `KOSLI_API_TOKEN` 

docs.kosli.com/content/getting_started/next.md

@@ -5,8 +5,10 @@ weight: 310
 ---
 # Part 10: Next Steps
 
-In the previous chapters, you explored Kosli Flows and Environments and have reported some data to Kosli. The next steps would be to harness the benefits of your hard work. Here are a few areas to look at next:
+In the previous chapters, you explored Kosli Flows and Environments and have reported some data to Kosli. 
+The next steps would be to harness the benefits of your hard work. Here are a few areas to look at next:
 
+- [What do I do if Kosli is down?](/tutorials/what_do_i_do_if_kosli_is_down/)
 - [Querying Kosli](/tutorials/querying_kosli/)
 - [Setup Actions on Environment changes](/integrations/actions/)
 - [Integrate Slack and Kosli](/integrations/slack/)

docs.kosli.com/content/getting_started/overview.md

@@ -5,7 +5,7 @@ weight: 210
 ---
 # Part 1: Overview
 
-The "Getting Started" section encompasses the steps you can follow to implement Kosli in your organization. It focuses on general instructions for utilizing Kosli and doesn't delve into specific tutorials for integrating Kosli with particular tools or runtime environments. For tailored tutorials catering to specific integrations, please refer to [tutorials](/tutorials).
+The "Getting Started" section encompasses the steps you can follow to implement Kosli in your organization. It focuses on general instructions for using Kosli and doesn't delve into specific tutorials for integrating Kosli with particular tools or runtime environments. For tailored tutorials catering to specific integrations, please refer to [tutorials](/tutorials).
 
 {{< hint success >}}
 If you're eager to start using Kosli right away, check our ["Get familiar with Kosli"](/tutorials/get_familiar_with_kosli/) tutorial that allows you to quickly try out Kosli features without the need to spin up a separate environment. No CI required.

docs.kosli.com/content/getting_started/service-accounts.md

@@ -7,7 +7,7 @@ weight: 230
 
 Prior to engaging with Kosli, authentication is necessary. There are two methods to achieve this:
 
-1. Utilizing a service account API key (recommended).
+1. Using a service account API key (recommended).
 2. Using a personal API key.
 
 ## Service Accounts
@@ -33,7 +33,7 @@ To create a service account:
 ## Personal API Keys
 
 {{< hint warning >}}
-Personal API keys possess equivalent permissions to your user account, encompassing access to multiple organizations. Therefore, exercise caution while utilizing personal API keys. These keys grant access and perform actions as per the associated user's permissions across various organizations.
+Personal API keys possess equivalent permissions to your user account, encompassing access to multiple organizations. Therefore, exercise caution while using personal API keys. These keys grant access and perform actions as per the associated user's permissions across various organizations.
 {{< /hint >}}
 
 To create a personal API key:
@@ -51,7 +51,7 @@ You can execute a zero-downtime API key rotation by following these steps:
 Create a new API key that will replace the existing key.
 
 - **Replace the Old Key Where Used**: 
-Implement the new key in all areas where the old key is currently utilized for authentication or access.
+Implement the new key in all areas where the old key is currently used for authentication or access.
 
 - **Delete the Old Key:**
 Once the new key is in place and operational, remove or delete the old key from the system or applications where it was previously employed for security or authentication purposes.

docs.kosli.com/content/integrations/actions.md

@@ -30,7 +30,7 @@ Use the app to create notification settings by running the `/kosli subscribe` sl
 2) Using Slack Incoming Webhooks
 
 - Create a [Slack incoming webhook](https://api.slack.com/messaging/webhooks#create_a_webhook).
-- Utilize this webhook to [create a notification settings in the Kosli UI](/integrations/actions/#manage-actions-in-the-ui).
+- Use this webhook to [create a notification settings in the Kosli UI](/integrations/actions/#manage-actions-in-the-ui).
 
 Both approaches allow you to configure Kosli notifications in Slack, offering flexibility based on your preferences.
 

docs.kosli.com/content/tutorials/what_do_i_do_if_kosli_is_down.md

@@ -0,0 +1,59 @@
+---
+title: "What do I do if Kosli is down?"
+bookCollapseSection: false
+weight: 507
+---
+
+# What do I do if Kosli is down?
+
+Customers use Kosli to attest evidence of their business and software processes.
+If Kosli is down, these attestations will fail.
+This will break CI workflow pipelines, blocking artifacts from being deployed.
+In this situation there is a built-in mechanism to instantly turn Kosli off and keep the pipeline flowing.
+When Kosli is back up, you can instantly turn Kosli back on.
+
+## Turning Kosli CLI calls on and off instantly
+
+If the `KOSLI_DRY_RUN` environment variable is set to `true` then all Kosli CLI commands will:
+* Not communicate with Kosli at all
+* Print the payload they would have sent
+* Exit with a zero status code
+
+We recommend creating an Org-level KOSLI_DRY_RUN variable in your CI system and, in all CI workflows,
+ensuring there is an environment variable set from it. 
+
+For example, in a [Github Action workflow](https://github.com/cyber-dojo/differ/blob/main/.github/workflows/main.yml):
+
+```yaml
+name: Main
+...
+env:
+  KOSLI_DRY_RUN: ${{ vars.KOSLI_DRY_RUN }}           # true iff Kosli is down
+```
+
+
+## Turning Kosli API calls on and off instantly
+
+If you are using the Kosli API in your workflows (e.g. using `curl`), we recommend using the same Org-level `KOSLI_DRY_RUN` 
+environment variable and guarding the `curl` call with a simple if statement. For example:
+
+```shell
+#!/usr/bin/env bash
+
+kosli_curl()
+{
+  local URL="${1}"
+  local JSON_PAYLOAD="${2}"
+
+  if [ "${KOSLI_DRY_RUN:-}" == "true" ]; then
+    echo KOSLI_DRY_RUN is set to true. This is the payload that would have been sent
+    echo "${JSON_PAYLOAD}" | jq .
+  else
+    curl ... --data="${JSON_PAYLOAD}" "${URL}"
+  fi
+}
+```
+
+
+
+

docs.kosli.com/content/understand_kosli/what_is_kosli.md

@@ -33,15 +33,15 @@ Kosli serves as a versatile solution for a variety of use cases. Two primary sce
 - Enhancing Overall Observability of Changes in Complex Systems and Environments:
   Beyond compliance considerations, Kosli remains valuable as a comprehensive platform, offering a unified view to different stakeholders. It provides visibility into changes occurring across various components of complex systems, even when there are no specific compliance requirements in place. This single pane of glass enhances overall observability.
 
-Feel free to contact us with any additional questions or if you require further information regarding the capabilities of Kosli. Alternatively, [explore how our customers have successfully implemented and utilized our services](https://www.kosli.com/case-studies/).
+Feel free to contact us with any additional questions or if you require further information regarding the capabilities of Kosli. Alternatively, [explore how our customers have successfully implemented and used our services](https://www.kosli.com/case-studies/).
 
 # Where does Kosli fit in the growing tools landscape?
 
 Kosli is tool-agnostic, specifically crafted to seamlessly integrate with various tools, including CI systems, code analysis tools, runtime environments, and more. Serving as a comprehensive compliance and change data hub, Kosli consolidates information from all your tools into a unified platform. It acts as your singular compliance and change management interface, providing a consolidated and streamlined view of data from diverse sources.
 
 # How does Kosli work?
 
-Kosli operates akin to a black box recorder, functioning as an append-only repository for immutable change records. To utilize Kosli, users report specific changes of interest through the command line interface (CLI) or API. Kosli, in turn, captures and stores these changes while actively monitoring compliance with designated policies.
+Kosli operates akin to a black box recorder, functioning as an append-only repository for immutable change records. Users report specific changes of interest through the command line interface (CLI) or API. Kosli, in turn, captures and stores these changes while actively monitoring compliance with designated policies.
 
 Notably, change sources can originate from diverse environments, including build systems (such as CI systems) and runtime environments (for instance, a Kubernetes cluster). This flexibility ensures that Kosli effectively captures and monitors changes across various stages of development and deployment.