Add guides - Resolve calc policy evaluation error(s) Closes #223 (#293)

Co-authored-by: raj <[email protected]>

docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/index.md

@@ -0,0 +1,80 @@
+---
+title: Resolve Calculated Policy Errors
+sidebar_label: Resolve Calculated Policy Errors
+---
+
+# Resolve Calculated Policy Evaluation Errors
+
+In this guide, you will:
+- Use Guardrails console to identify and resolve calculated policy evaluation errors.
+
+A [Calculated Policy](/guardrails/docs/reference/glossary#calculated-policy) dynamically determines policy settings by sourcing CMDB data, executing a GraphQL query, and applying a [Nunjucks](/guardrails/docs/guides/using-guardrails/nunjucks) template to generate a resource-specific policy value. Any policy setting can be calculated, making policies more context-aware and adaptable.
+
+However, calculated policies can sometimes encounter errors due to misconfigurations or data inconsistencies, leading to controls entering an error state. Ensuring these policies are properly configured and promptly fixed is crucial for maintaining compliance and system stability.
+
+## Prerequisites
+
+- **Turbot/Admin** permissions at the Turbot resource level.
+- Familiarity with the Guardrails console.
+- Knowledge of the [Jinja2/Nunjucks](https://jinja.palletsprojects.com/en/stable/templates/) template language.
+
+## Step 1: Navigate to Policies
+
+Log into the Guardrails console with provided local credentials or by using any SAML based login and Select **Policies** from the top navigation menu.
+
+![Navigate to Reports](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-policies.png)
+
+## Step 2: Select Policy Value
+
+Select the calculated policy in an error state that needs to be resolved. This redirects to the Policy Value page, where the error message is displayed.
+
+Here, the error occurs due to `TypeError: Cannot read properties of undefined (reading 'toString')`, indicating that the referenced property is undefined and cannot be converted to a string.
+
+![Select Calculated Policy](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png)
+
+## Step 3: Select Calculated Policy
+
+Select the **Calculated** policy, with an ✅ `EFFECTIVE SETTING`.
+
+![Effective Setting](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png)
+
+## Step 4: Edit Policy Setting
+
+Select **Edit** from the top right corner.
+
+![Select Edit](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-edit.png)
+
+Choose **Launch calculated policy builder**.
+
+![Launch Calculated Policy Builder](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png)
+
+This displays the `GraphQL` query and `Jinja2/Nunjucks` template used in the calculated policy, providing insight into how the policy value is generated.
+
+![Calculated Policy Builder Page](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png)
+
+## Step 5: Resolve Calculated Policy
+
+Select the `Test Resource`, update the corrected Jinja2/Nunjucks template, and view the real-time output to verify if the fix is successful. Choose **Update**.
+
+![Resolve Error](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png)
+
+Select **Update** from the Update Policy Setting page.
+
+![Select Update](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-update-policy.png)
+
+## Step 6: Review
+
+- [ ] Verify that the policy value transitions to an `OK` state, confirming the issue has been resolved successfully.
+
+![Policy Value State](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png)
+
+- [ ] Verify that the affected control transitions to an `OK` state.
+
+![Control State](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png)
+
+## Troubleshooting
+
+| Issue                                      | Description                                                                                                                                                                                                 | Guide                                |
+|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
+| Common errors.                     | Any common errors preventing controls to run.   |Refer [Common Troubleshooting](/guardrails/docs/guides/troubleshooting) for more information.
+| Further Assistance                       | If you encounter further issues with Calculated Policies, please open a ticket with us and attach the relevant information to assist you more efficiently.                                                 | [Open Support Ticket](https://support.turbot.com)   |

docs/guides/using-guardrails/troubleshooting/index.md

@@ -9,3 +9,4 @@ The following guides will assist with the self-resolution of common problems. If
 
 - [Access Control Logs](/guardrails/docs/guides/using-guardrails/troubleshooting/access-control-logs)
 - [Fix Invalid Controls](/guardrails/docs/guides/using-guardrails/troubleshooting/fix-invalid-controls)
+- [Resolve Calculated Policy Errors](/guardrails/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors)

docs/guides/using-guardrails/troubleshooting/run-controls-using-scripts/index.md

@@ -0,0 +1,118 @@
+---
+title: Run Controls Using Scripts
+sidebar_label: Run Controls Using Scripts
+---
+
+# Run Controls Using Scripts
+
+In this guide, you will:
+- Use the Guardrails Console to identify controls in an error state and resolve them using scripts.
+
+[Controls](/guardrails/docs/reference/glossary#control) enforce [policies](/guardrails/docs/reference/glossary#policy) to ensure cloud resources remain compliant and Guardrails operates effectively. However, a large number of controls may encounter errors due to factors like network outages. To efficiently resolve these errors, use the script available in the [guardrails-samples](https://github.com/turbot/guardrails-samples/tree/main/guardrails_utilities/shell_utils/run-controls) GitHub repository to rerun the affected controls. Regularly addressing controls in an Error state helps maintain system stability and compliance.
+
+## Prerequisites
+
+- **Turbot/Operator** permissions at the Turbot resource level.
+- Familiarity with Github and the Guardrails console.
+
+## Step 1: Navigate to Controls
+
+Log into the Guardrails console with provided local credentials or by using any SAML based login and Select **Controls** from the top navigation menu.
+
+![Navigate to Controls](/images/docs/guardrails/guides/using-guardrails/troubleshooting/run-controls-using-scripts/guardrails-navigate-to-controls.png)
+
+## Step 2: Identify Control Errors
+
+In the Controls section, filter and select the controls in an `Error` state that need to be re-run.
+
+![Identify Control Errors](/images/docs/guardrails/guides/using-guardrails/troubleshooting/run-controls-using-scripts/identify-controls-errors.png)
+
+## Step 3: Retrieve Control Type URI
+
+Open the control details, navigate to the **Developers** tab, and copy the `Control Type URI` for use in later steps.
+
+![Control Type URI](/images/docs/guardrails/guides/using-guardrails/troubleshooting/run-controls-using-scripts/guardrails-retrieve-control-uri.png)
+
+## Step 4: Clone Guardrails Samples Repository
+
+Go to [guardrails-samples](https://github.com/turbot/guardrails-samples) and clone the repository.
+
+![Guardrails Samples](/images/docs/guardrails/guides/using-guardrails/troubleshooting/run-controls-using-scripts/github-guardrails-samples-repo.png)
+
+## Step 5: Navigate to Run-Controls Directory
+
+In the cloned repository, navigate to the following folder:
+
+`guardrails_utilities/shell_utils/run-controls`
+
+## Step 6: Set Environment Variables
+
+Set the necessary environment variables using the command below:
+
+```
+export TURBOT_WORKSPACE="https://<environment-name>.cloud.turbot.com/"
+export TURBOT_ACCESS_KEY_ID=ac61d2e4-730c-4b54-8c3c-6ef172390814
+export TURBOT_SECRET_ACCESS_KEY=151b296b-0694-4a28-94c4-4b67fa82ab2c
+```
+
+## Step 7: Run Controls via Script
+
+Execute this script using the Control Type URI from [Step 3](#step-3-retrieve-control-type-uri). The batch size is set to 25 to minimize database load.
+
+```
+./run-controls.sh --filter 'state:error controlTypeId:tmod:@turbot/turbot#/control/types/controlInstalled' --batch-size 25
+```
+The script should start running and output results similar to below:
+
+```
+[INFO] Control 1 of 22
+[INFO]    Type: "Type Installed"
+[INFO]    Resource: "Turbot > @turbot/aws-rds > Update Performance Configuration"
+[INFO]    State: "error"
+[INFO]    Reason: "Error running trusted inline"
+[INFO]    ID: "311522861481171"
+[INFO] Control 2 of 22
+[INFO]    Type: "Type Installed"
+[INFO]    Resource: "Turbot > @turbot/aws-rds > Set Tags"
+[INFO]    State: "error"
+[INFO]    Reason: "Error running trusted inline"
+[INFO]    ID: "293907562769114"
+[INFO] Control 3 of 22
+[INFO]    Type: "Type Installed"
+[INFO]    Resource: "Turbot > @turbot/aws-rds > Delete from AWS"
+[INFO]    State: "error"
+[INFO]    Reason: "Error running trusted inline"
+[INFO]    ID: "293907548601779"
+[INFO] Control 4 of 22
+[INFO]    Type: "Type Installed"
+[INFO]    Resource: "Turbot > @turbot/aws-rds > Delete from AWS"
+[INFO]    State: "error"
+[INFO]    Reason: "Error running trusted inline"
+[INFO]    ID: "293907547759782"
+[INFO] Control 22 of 22
+[INFO]    Type: "Type Installed"
+[INFO]    Resource: "Turbot > @turbot/aws-rds > Update Access Logging"
+[INFO]    State: "error"
+[INFO]    Reason: "Error running trusted inline"
+[INFO]    ID: "195756668765883"
+[INFO] Total amount of controls re-run: 22
+[INFO] Total time taken 7 second(s)
+```
+
+The command stops once all controls have successfully run.
+
+## Step 8: Verify Control Status
+
+Confirm that all controls have moved to an `OK` state.
+
+![Navigate to Reports](/images/docs/guardrails/guides/using-guardrails/troubleshooting/run-controls-using-scripts/guardrails-verify-control-status.png)
+
+**Additional Execution for Policies**
+
+To resolve policies in an Error state, execute the run-policies script using the same approach.
+
+## Troubleshooting
+
+| Issue                                      | Description                                                                                                                                                                                                 | Guide                                |
+|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
+| Further Assistance                       | If you encounter further issues with Calculated Policies, please open a ticket with us and attach the relevant information to assist you more efficiently.                                                 | [Open Support Ticket](https://support.turbot.com)   |

docs/sidebar.json

@@ -338,7 +338,9 @@
             "link": "guides/using-guardrails/troubleshooting",
             "items": [
               "guides/using-guardrails/troubleshooting/fix-invalid-controls",
-              "guides/using-guardrails/troubleshooting/access-control-logs"
+              "guides/using-guardrails/troubleshooting/access-control-logs",
+              "guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors",
+              "guides/using-guardrails/troubleshooting/run-controls-using-scripts"
             ]
           },
           {