diff --git a/docs/concepts/guardrails/index.md b/docs/concepts/guardrails/index.md index 507f4c72..f4214f5e 100644 --- a/docs/concepts/guardrails/index.md +++ b/docs/concepts/guardrails/index.md @@ -21,6 +21,7 @@ there are many guardrails that are common and consistent across resources. | [Discovery](concepts/guardrails/discovery) | Mechanism by which Guardrails initially adds a resource to the CMDB. | | [Encryption at Rest](concepts/guardrails/encryption-at-rest) | A mechanism to manage data encryption at rest (i.e. AWS S3 Buckets). | | [Encryption in Transit](concepts/guardrails/encryption-in-transit) | A mechanism to manage data encryption in transit (i.e. AWS S3 Buckets). | +| [Intelligent Assessment](concepts/guardrails/intelligent-assessment) | AI-powered resource assessment to evaluate compliance using natural language. | [Public Access](concepts/guardrails/public-access) | Configure public access settings on cloud resources. | | [Scheduling](concepts/guardrails/scheduling) | Define schedules to control cloud resource usage. | | [Stacks/ Configured](concepts/guardrails/configured) | [DEPRECATED] Manage resource configuration using Terraform. | diff --git a/docs/concepts/guardrails/intelligent-assessment.md b/docs/concepts/guardrails/intelligent-assessment.md new file mode 100644 index 00000000..1416dfa6 --- /dev/null +++ b/docs/concepts/guardrails/intelligent-assessment.md @@ -0,0 +1,79 @@ +--- +title: Intelligent Assessment Guardrails +sidebar_label: Intelligent Assessment +--- + +# Intelligent Assessment Guardrails + +## Overview + +**Intelligent Assessment** introduces an AI-powered way to define and evaluate governance policies in Turbot Guardrails. + +Instead of crafting complex calculated policies, you can describe the check you want — in plain natural language — and let Guardrails interpret and check it. + +This unlocks flexible, free-form compliance use cases that would otherwise require significant coding or multiple traditional guardrails. + +Intelligent Assessment is complementary to existing controls (e.g., **Approved** and **Active**). + +Where those controls rely on structured sub-policies, Intelligent Assessment excels when you need bespoke logic, conditional checks, or multi-step reasoning. + +The primary Intelligent Assessment policy has a consistent form: +`{provider} > {service} > {resource} > Intelligent Assessment` + +
+ +
+ +The Intelligent Assessment guardrail and policy have a number of sub-settings to determine the +attributes of the assessment. The format of these policy types is +`{provider} > {service} > {resource} > Intelligent Assessment > {Items}`: + +``` +{provider} > {service} > {resource} > Intelligent Assessment > Context +{provider} > {service} > {resource} > Intelligent Assessment > User Prompt +``` + +The `Context` sub-policy includes the resource metadata by default but can be updated to include additional data. +The `User Prompt` sub-policy is where you would define a prompt to assess the resource. + +As part of the evaluation, the AI provider will respond with `State` and `Reason`. + +The `State` attribute is either: + +- `OK` - Evaluation matches the given user prompt +- `Alarm` - Evaluation does not match the given user prompt +- `Error` - User prompt is empty or AI cannot determine the outcome based on the user prompt and context + +### Example Guardrail: AWS > S3 > Bucket > Intelligent Assessment + +The `AWS > S3 > Bucket > Intelligent Assessment` policy determines the action to take on a resource. You can set the policy to skip (don't run at all), or to check whether the resource is compliant per the user prompt. + +The Intelligent Assessment sub-policies allow you to set the context and the user prompt: + +
+ +
+ +Let's assume that an S3 bucket has tags `"Environment": "Non-Compliant Tag"`, and has versioning disabled. + +```yaml +Tags: + - Key: Environment + Value: Non-Compliant Tag +Versioning: + MFADelete: Disabled + Status: Suspended +``` + +To check if the bucket has the correct `Environment` tag value and has versioning enabled: + +- Set `AWS > S3 > Bucket > Intelligent Assessment > User Prompt`: `The bucket must have an Environment tag value of staging and versioning must be enabled` + +The control will then evaluate the result using AI, and go to alarm with the response `The current tag Environment has a value of Non-Compliant Tag which is incorrect. Versioning is not enabled and set to Suspended`. diff --git a/docs/developers/developers-sidebar.json b/docs/developers/developers-sidebar.json new file mode 100644 index 00000000..ff6e4c38 --- /dev/null +++ b/docs/developers/developers-sidebar.json @@ -0,0 +1,12 @@ +{ + "type": "category", + "id": "developers", + "link": "developers", + "items": [ + "developers/install-mcp", + "developers/policy-pack-development", + "developers/graphql", + "developers/nunjucks", + "developers/fix-calc-policy-evaluation-errors" + ] +} diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png b/docs/developers/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png rename to docs/developers/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-edit.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-edit.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-edit.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-edit.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-policies.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-policies.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-policies.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-policies.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-update-policy.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-update-policy.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-update-policy.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-update-policy.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/index.md b/docs/developers/fix-calc-policy-evaluation-errors/index.md similarity index 70% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/index.md rename to docs/developers/fix-calc-policy-evaluation-errors/index.md index 589be481..d98e10e2 100644 --- a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/index.md +++ b/docs/developers/fix-calc-policy-evaluation-errors/index.md @@ -22,7 +22,7 @@ However, calculated policies can sometimes encounter errors due to misconfigurat 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) +![Navigate to Reports](./guardrails-select-policies.png) ## Step 2: Select Policy Value @@ -30,47 +30,47 @@ Select the calculated policy in an error state that needs to be resolved. This r 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) +![Select Calculated Policy](./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) +![Effective Setting](./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) +![Select Edit](./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) +![Launch Calculated Policy Builder](./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) +![Calculated Policy Builder Page](./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) +![Resolve Error](./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) +![Select Update](./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) +![Policy Value State](./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) +![Control State](./guardrails-control-ok-state.png) ## Troubleshooting diff --git a/docs/guides/using-guardrails/graphql/index.md b/docs/developers/graphql/index.md similarity index 100% rename from docs/guides/using-guardrails/graphql/index.md rename to docs/developers/graphql/index.md diff --git a/docs/developers/index.md b/docs/developers/index.md new file mode 100644 index 00000000..b135770e --- /dev/null +++ b/docs/developers/index.md @@ -0,0 +1,16 @@ +--- +title: Developers +sidebar_label: Developers +--- + +# Developing guardrails for Guardrails + +This section covers the various AI-powered features available in Guardrails. + +| Section | Description +| - | - +| [Install Guardrails MCP](/guardrails/docs/developers/install-mcp) | Learn how Guardrails Model Context Protocol (MCP) server is enabled. +| [Policy Pack Development](/guardrails/docs/developers/policy-pack-development) | Learn how to use AI to develop and validate policy packs. +| [GraphQL](/guardrails/docs/developers/graphql) | Tips and Tricks for GraphQL +| [Nunjucks](/guardrails/docs/developers/nunjucks) | Tips and tricks for using Nunjucks, including troubleshooting +| [Resolve Calculated Policy Errors](/guardrails/docs/developers/fix-calc-policy-evaluation-errors) | Troubleshooting calc policy errors \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai-tools/index.md b/docs/developers/install-mcp/index.md similarity index 98% rename from docs/guides/using-guardrails/ai-tools/index.md rename to docs/developers/install-mcp/index.md index c377f9ca..7f1fbd36 100644 --- a/docs/guides/using-guardrails/ai-tools/index.md +++ b/docs/developers/install-mcp/index.md @@ -1,9 +1,9 @@ --- -title: AI Tools (MCP) -sidebar_label: AI Tools (MCP) +title: Install Guardrails MCP +sidebar_label: Install MCP for AI --- -# Configure Guardrails MCP Server +# Install the Guardrails' MCP Server for AI Assisted Development In this guide, you will: diff --git a/docs/guides/using-guardrails/nunjucks/approve.png b/docs/developers/nunjucks/approve.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/approve.png rename to docs/developers/nunjucks/approve.png diff --git a/docs/guides/using-guardrails/nunjucks/error1.png b/docs/developers/nunjucks/error1.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error1.png rename to docs/developers/nunjucks/error1.png diff --git a/docs/guides/using-guardrails/nunjucks/error2.png b/docs/developers/nunjucks/error2.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error2.png rename to docs/developers/nunjucks/error2.png diff --git a/docs/guides/using-guardrails/nunjucks/error3.png b/docs/developers/nunjucks/error3.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error3.png rename to docs/developers/nunjucks/error3.png diff --git a/docs/guides/using-guardrails/nunjucks/error4.png b/docs/developers/nunjucks/error4.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error4.png rename to docs/developers/nunjucks/error4.png diff --git a/docs/guides/using-guardrails/nunjucks/error5.png b/docs/developers/nunjucks/error5.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error5.png rename to docs/developers/nunjucks/error5.png diff --git a/docs/guides/using-guardrails/nunjucks/error6.png b/docs/developers/nunjucks/error6.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error6.png rename to docs/developers/nunjucks/error6.png diff --git a/docs/guides/using-guardrails/nunjucks/index.md b/docs/developers/nunjucks/index.md similarity index 100% rename from docs/guides/using-guardrails/nunjucks/index.md rename to docs/developers/nunjucks/index.md diff --git a/docs/guides/using-guardrails/nunjucks/multi-tag.png b/docs/developers/nunjucks/multi-tag.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/multi-tag.png rename to docs/developers/nunjucks/multi-tag.png diff --git a/docs/guides/using-guardrails/nunjucks/object-object.png b/docs/developers/nunjucks/object-object.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/object-object.png rename to docs/developers/nunjucks/object-object.png diff --git a/docs/guides/using-guardrails/nunjucks/regex1.png b/docs/developers/nunjucks/regex1.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/regex1.png rename to docs/developers/nunjucks/regex1.png diff --git a/docs/guides/using-guardrails/nunjucks/regex2.png b/docs/developers/nunjucks/regex2.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/regex2.png rename to docs/developers/nunjucks/regex2.png diff --git a/docs/guides/using-guardrails/nunjucks/regex3.png b/docs/developers/nunjucks/regex3.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/regex3.png rename to docs/developers/nunjucks/regex3.png diff --git a/docs/guides/using-guardrails/nunjucks/tag-value.png b/docs/developers/nunjucks/tag-value.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/tag-value.png rename to docs/developers/nunjucks/tag-value.png diff --git a/docs/guides/using-guardrails/nunjucks/tag1.png b/docs/developers/nunjucks/tag1.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/tag1.png rename to docs/developers/nunjucks/tag1.png diff --git a/docs/guides/using-guardrails/nunjucks/tags.png b/docs/developers/nunjucks/tags.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/tags.png rename to docs/developers/nunjucks/tags.png diff --git a/docs/guides/using-guardrails/nunjucks/test-tag-hyphen.png b/docs/developers/nunjucks/test-tag-hyphen.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/test-tag-hyphen.png rename to docs/developers/nunjucks/test-tag-hyphen.png diff --git a/docs/guides/using-guardrails/nunjucks/turbot-tag.png b/docs/developers/nunjucks/turbot-tag.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/turbot-tag.png rename to docs/developers/nunjucks/turbot-tag.png diff --git a/docs/developers/policy-pack-development/index.md b/docs/developers/policy-pack-development/index.md new file mode 100644 index 00000000..7ba25887 --- /dev/null +++ b/docs/developers/policy-pack-development/index.md @@ -0,0 +1,205 @@ +--- +title: Policy Pack Development with AI Tools +sidebar_label: Using AI for Policy Pack Development +--- + +# Policy Pack Development with AI Tools + +In this guide, you will learn how to: + +- Use the MCP server's AI assistant to generate a production-ready Turbot policy pack +- Configure Terraform files, policy settings, and README according to Turbot best practices +- Test and validate your policy pack before deploying to production + +This step-by-step guide will help you streamline policy pack development using AI, ensuring all required components are created and validated efficiently. + +## Prerequisites + +Before you begin, ensure you have the following: + +- Guardrails MCP server installed and configured. + Follow the [Install Guardrails MCP guide](/guardrails/docs/guides/using-guardrails/ai/install-mcp) to set up the Model Context Protocol (MCP) server. +- Access to your Guardrails workspace URL (e.g., `https://your-workspace.cloud.turbot.com`). +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- A clear policy objective (for example, `Enforce EKS Public Endpoint Access`). +- Resource IDs available for testing your policy pack. + +## Step 1: Clone *guardrails-samples* Repository + +Before starting, clone the [guardrails-samples](https://github.com/turbot/guardrails-samples) repository locally. This repository contains example policy packs, recommended directory structure, and a README template. Use this as your working directory for creating and testing your new policy pack. + +```bash +git clone https://github.com/turbot/guardrails-samples.git +cd guardrails-samples/policy_packs +``` +>[!NOTE] +> Create a new branch to make sure you use this branch to raise PR against the main branch. + +Let AI create your new policy pack as a subdirectory here, following the structure and examples provided. + +## Step 2: Define Goal + +Clearly state the policy objective. For example: + +- Enforce EKS endpoint access security: + - Public access is disabled by default. + - If public access is enabled, restrict to specific CIDRs (e.g., `203.0.113.0/24`, `10.0.0.0/8`). + - Private access must always be enabled. + +### Identify Policies + +List the relevant Turbot policies to include in your policy pack. You can explore the [Guardrails Hub](https://hub.guardrails.turbot.com/) to find policies specific to your chosen cloud provider's mod. + +For example, consider the following policies: + +- [AWS > EKS > Cluster > Endpoint Access](https://hub.guardrails.turbot.com/mods/aws/policies/aws-eks/clusterEndpointAccess) +- [AWS > EKS > Cluster > Endpoint Access > CIDR Ranges](https://hub.guardrails.turbot.com/mods/aws/policies/aws-eks/clusterEndpointAccessCidrRanges) + +## Step 3: Prepare LLM Prompt + +Use the template below to guide the LLM when working in your new branch within the Cursor AI IDE or any AI-assisted development environment. + +``` +Goal: +- Enforce EKS endpoint access security: + - Public access should be disabled by default. + - If public access is enabled, restrict it to specific CIDRs (e.g., 203.0.113.0/24, 10.0.0.0/8). + - Private access must always be enabled. +- Policies must be visible in the Guardrails UI as part of the policy pack. +- Support a production workflow where customers attach the policy pack manually. + +Instructions: +1. Create a policy pack (Terraform) for AWS EKS endpoint access, following Turbot best practices and directory structure. +2. Define the policies as part of the policy pack (not as standalone policy settings). Use `turbot_policy_setting` resources with `resource = turbot_policy_pack..id`. +3. For testing: + - Add a `turbot_policy_pack_attachment` resource to attach the policy pack to a real resource (provide a test resource ID). + - After a successful test, prompt the user to validate in the Guardrails console that the policies are visible and correct. + - Once the user confirms, remove the `turbot_policy_pack_attachment` resource for production readiness. +4. For production: + - The policy pack should NOT include any `turbot_policy_pack_attachment` resource. + - Customers will attach the policy pack to their desired resources manually via the Guardrails console. +5. README: + - Generate a README for the policy pack following the rules in https://github.com/turbot/guardrails-samples/blob/main/policy_packs/README.md (categories, primary_category, type, usage, etc.). + - Validate the README and policy pack structure against all best practices. If any rule fails, revise and revalidate until all are green/OK. +6. Test: + - Initialize and apply the policy pack using Terraform, attaching it to the provided test resource. + - Confirm that the policies are visible in the Guardrails UI under the policy pack and that the resource is compliant. + - After user validation, remove the attachment for production. + +Configuration Input: +- Approved CIDR ranges: `["203.0.113.0/24", "10.0.0.0/8"]` +- Test Resource ID: (provide your real resource ID, e.g., `355421285155896`) + +Example Terraform Structure: +- `main.tf`: Defines the `turbot_policy_pack` (and, for testing only, the `turbot_policy_pack_attachment`). +- `policies.tf`: Defines `turbot_policy_setting` resources with `resource = turbot_policy_pack..id`. +- `providers.tf`: Provider block. +- `variables.tf`: Variable for the target resource. +- `README.md`: As per best practices. + +Do not proceed if no real resource is available. +Do not use standalone policy settings attached directly to the resource. +All policies must be visible in the UI as part of the policy pack. + +Workflow: +1. Develop and test with the attachment. +2. Prompt user to validate in the Guardrails console. +3. After confirmation, remove the attachment for production readiness. +``` + +## Step 4: Optimize the Feedback Loop + +Work collaboratively with the AI assistant to review, validate, and improve your policy pack. Use an iterative approach: check the generated files, provide clear feedback, and request specific changes until the policy pack meets your requirements and best practices. + +### Review the generated files + +- `README.md` +- `main.tf` +- `policies.tf` +- `providers.tf` +- `variables.tf` + +### Checklist + +- Do the policy settings match your objectives? +- Are all required files present and following the recommended structure? +- Is the documentation clear and complete? +- Are there any errors or missing configurations? + +### How to provide feedback + +You can use prompts like: + +``` +Please update the following: +- Add more detail to the usage section in README.md +- Change the approved CIDR ranges in variables.tf to ["198.51.100.0/24"] +- Add tags to the policy pack in main.tf +- Ensure all policies are visible in the Guardrails UI +- Fix the resource reference in policies.tf to use the correct variable +``` +### Iterate as needed +Repeat the review and feedback process until you are satisfied with the results. Don't hesitate to ask the AI assistant for clarifications, best practice checks, or additional examples. + +## Step 5: Actionable Execution + +Take your validated policy pack and apply it in a test environment to ensure everything works as expected. + +### Apply the Policy Pack + +1. **Plan the Deployment:** + + Let's initialize and run terraform plan. + + - Example prompt: + ``` + - Initialize the Terraform configuration + - Run terraform plan and wait for me to confirm terraform apply + ``` + +2. **Apply to a Test Resource:** + - Run `terraform apply` to deploy the policy pack, attaching it to your test resource (e.g., `355421285155896`). + - Example prompt: + ``` + - Apply the policy pack to resource 355421285155896 + ``` +#### Example Prompts + +In case any error or further validation use below + +``` +- Help me troubleshoot a Terraform apply error +- Confirm that the policy pack is visible in the Guardrails UI +- Check if the resource is compliant after applying the policy pack +``` + +### Review + +Manually review to make sure execution is successful + +- [ ] Terraform apply completed without errors. +- [ ] The policy pack and its policies are visible in the Guardrails Console. +- [ ] Resource compliance status is as expected. +- [ ] No unexpected alarms or errors. + +## Step 6: Finalize for Production + +After you have successfully tested your policy pack and validated the results, it's important to prepare your configuration for release by removing any test-specific resources or attachments. + +### Remove Test Attachments + +- Instruct the AI assistant (or manually update your Terraform files) to remove the `turbot_policy_pack_attachment` resource used for testing. +- Ensure your policy pack is now ready for release, where customers will attach it to their own resources via the Guardrails Console. + +#### Example Prompts + +``` +- Remove the test attachment for the generated policy pack. +- Update documentation for production use. +- Verify final structure matches existing policy pack structure +``` +### Review + +- [ ] All test attachments have been removed from your Terraform configuration. +- [ ] The policy pack structure matches the recommended format and best practices. +- [ ] Documentation is updated for release. diff --git a/docs/guides/hosting-guardrails/index.md b/docs/guides/hosting-guardrails/index.md index 9d818a33..6284790f 100644 --- a/docs/guides/hosting-guardrails/index.md +++ b/docs/guides/hosting-guardrails/index.md @@ -20,3 +20,6 @@ The Guardrails Enterprise installation is highly customizable, allowing you to d | [Monitoring Guides](guides/hosting-guardrails/monitoring) | How to proactively monitor your Guardrails infrastructure. | [Recovery Guides](guides/hosting-guardrails/disaster-recovery) | How to recover a Guardrails environment from backup. | [Troubleshooting Guides](guides/hosting-guardrails/troubleshooting) | How to assess and fix common hosting issues. +| [Updating Guardrails](guides/hosting-guardrails/updating-stacks) | How to keep your Guardrails infrastructure up to date. + + diff --git a/docs/guides/hosting-guardrails/installation/install-ted/index.md b/docs/guides/hosting-guardrails/installation/install-ted/index.md index ed0bf505..6391d5a8 100644 --- a/docs/guides/hosting-guardrails/installation/install-ted/index.md +++ b/docs/guides/hosting-guardrails/installation/install-ted/index.md @@ -123,6 +123,18 @@ Choose to **Use Elasticache** and select the desired values for **ElastiCache Ve ![Cache](/images/docs/guardrails/guides/hosting-guardrails/installation/install-ted/service-catalog-ted-parameter-cache.png) +## Step 16: Enable Pg Bouncer + +To improve database connection management and performance, we now recommend enabling PgBouncer, a lightweight connection pooler for PostgreSQL. +For setup instructions, learn how to [Enable PgBouncer](/guardrails/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer). + +## Step 17: Configure Advanced - Foundation Parameters and Overrides +### Upgrade to Valkey cache + +As part of the TED infrastructure, Redis has previously been the default caching engine. We now recommend moving to [Valkey](https://aws.amazon.com/elasticache/what-is-valkey/), a community-driven alternative to Redis. + +For customers currently using Redis OSS cache, [here is how to update to Valkey](/guardrails/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache). + ## Step 16: Configure Advanced - Foundation Parameters and Overrides The Foundation Parameters allow the TED stack to use SSM parameters defined in the TEF stack. You should only change these values if you did not use the default Resource Name Prefix (turbot) in the TEF stack. @@ -131,7 +143,7 @@ The Foundation Parameters allow the TED stack to use SSM parameters defined in t The Foundation Overrides allow you to override values defined in the TEF stack. You will likely want to leave these blank. -## Step 17: Advanced - Infrastructure +## Step 18: Advanced - Infrastructure Select a **Resource Name Prefix** which will be added to all Turbot Guardrails resources. Because this prefix will be used across many resource types and different resource types have different name restrictions, you should avoid special characters and uppercase letters. This prefix should match the name prefix you used in the TEF stack. @@ -140,13 +152,13 @@ Select a **Resource Name Prefix** which will be added to all Turbot Guardrails r ![Advanced Infrastructure](/images/docs/guardrails/guides/hosting-guardrails/installation/install-ted/service-catalog-ted-parameter-advanced-infrastructure.png) -## Step 18: Launch Product +## Step 19: Launch Product Select **Launch product**. ![Launch Product](/images/docs/guardrails/guides/hosting-guardrails/installation/install-ted/service-catalog-ted-launch-product-action.png) -## Step 19: Monitor Installation +## Step 20: Monitor Installation You have initiated the installation of the new TED version. This triggers an update of several nested CloudFormation stacks. @@ -154,7 +166,7 @@ The TED stack should be in the **CREATE_IN_PROGRESS** status. ![Under Change Status](/images/docs/guardrails/guides/hosting-guardrails/installation/install-ted/cfn-ted-create-progress.png) -## Step 20: Review +## Step 21: Review - [ ] The TEF CloudFormation stack status should change to `CREATE_COMPLETE` indicating the installation completed successfully. diff --git a/docs/guides/hosting-guardrails/installation/install-ted/service-catalog-ted-update-valkey-parameters.png b/docs/guides/hosting-guardrails/installation/install-ted/service-catalog-ted-update-valkey-parameters.png new file mode 100644 index 00000000..89f7a8fd Binary files /dev/null and b/docs/guides/hosting-guardrails/installation/install-ted/service-catalog-ted-update-valkey-parameters.png differ diff --git a/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-existing-vpc/index.md b/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-existing-vpc/index.md index c388eb07..93dde9a5 100644 --- a/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-existing-vpc/index.md +++ b/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-existing-vpc/index.md @@ -121,13 +121,18 @@ By default, support is provided for the `Instance Type for EC2 ECS host` and `AM You can modify the rest of the parameters as needed, or leave them at their default values. -## Step 11: Launch Product +## Step 11: Enable Pg Bouncer + +To improve database connection management and performance, we now recommend enabling PgBouncer, a lightweight connection pooler for PostgreSQL. +For setup instructions, learn how to [Enable PgBouncer](/guardrails/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer). + +## Step 12: Launch Product Select **Launch product**. ![Launch Product](/images/docs/guardrails/guides/hosting-guardrails/installation/install-tef/install-tef-into-existing-vpc/service-catalog-tef-launch-product-action.png) -## Step 12: Monitor Installation +## Step 13: Monitor Installation You have initiated the installation of the new TEF version. This triggers an update of several nested CloudFormation stacks. @@ -135,7 +140,7 @@ The TEF provisioned product should be in the **Under Change** status. ![Under Change Status](/images/docs/guardrails/guides/hosting-guardrails/installation/install-tef/install-tef-into-existing-vpc/service-catalog-tef-under-change.png) -## Step 13: Enable Termination Protection +## Step 14: Enable Termination Protection > [!IMPORTANT] > To ensure that the TEF stack is not accidentally deleted, it is strongly recommend that termination protection is enabled. @@ -156,7 +161,7 @@ Choose `Termination protection` as **Activated** and select **Save**. ![Termination Protection Activated](/images/docs/guardrails/guides/hosting-guardrails/installation/install-tef/install-tef-into-existing-vpc/cfn-stack-edit-termination-protection-activated.png) -## Step 14: Review +## Step 15: Review - [ ] The TEF CloudFormation stack status should change to `CREATE_COMPLETE` indicating the installation completed successfully. diff --git a/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-new-vpc/index.md b/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-new-vpc/index.md index 43cdcb2d..00338321 100644 --- a/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-new-vpc/index.md +++ b/docs/guides/hosting-guardrails/installation/install-tef/install-tef-into-new-vpc/index.md @@ -118,13 +118,18 @@ By default, support is provided for the `Instance Type for EC2 ECS host` and `AM You can modify the rest of the parameters as needed, or leave them at their default values. -## Step 11: Launch Product +## Step 11: Enable Pg Bouncer + +To improve database connection management and performance, we now recommend enabling PgBouncer, a lightweight connection pooler for PostgreSQL. +For setup instructions, learn how to [Enable PgBouncer](/guardrails/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer). + +## Step 12: Launch Product Select **Launch product**. ![Launch Product](/images/docs/guardrails/guides/hosting-guardrails/installation/install-tef/install-tef-into-new-vpc/service-catalog-tef-launch-product-action.png) -## Step 12: Monitor Installation +## Step 13: Monitor Installation You have initiated the installation of the new TEF version. This triggers an update of several nested CloudFormation stacks. @@ -132,7 +137,7 @@ The TEF provisioned product should be in the **Under Change** status. ![Under Change Status](/images/docs/guardrails/guides/hosting-guardrails/installation/install-tef/install-tef-into-new-vpc/service-catalog-tef-under-change.png) -## Step 13: Enable Termination Protection +## Step 14: Enable Termination Protection > [!IMPORTANT] > To ensure that the TEF stack is not accidentally deleted, it is strongly recommend that termination protection is enabled. @@ -153,7 +158,7 @@ Choose `Termination protection` as **Activated** and select **Save**. ![Termination Protection Activated](/images/docs/guardrails/guides/hosting-guardrails/installation/install-tef/install-tef-into-new-vpc/cfn-stack-edit-termination-protection-activated.png) -## Step 14: Review +## Step 15: Review - [ ] The TEF CloudFormation stack status should change to `CREATE_COMPLETE` indicating the installation completed successfully. diff --git a/docs/guides/hosting-guardrails/updating-stacks/general-purpose-gp3/index.md b/docs/guides/hosting-guardrails/updating-stacks/general-purpose-gp3/index.md index 3f4a9ff5..7b7f67a9 100644 --- a/docs/guides/hosting-guardrails/updating-stacks/general-purpose-gp3/index.md +++ b/docs/guides/hosting-guardrails/updating-stacks/general-purpose-gp3/index.md @@ -70,7 +70,7 @@ or the TE version could be different from case to case. * Storage Throughput: 0 - ![gp3-baseline](/images/docs/guardrails/gp3-baseline.png) + ![gp3-baseline](./gp3-baseline.png) If the Allocated Storage is 400GB or higher: @@ -80,7 +80,7 @@ or the TE version could be different from case to case. * Storage Throughput: 500 - ![gp3-baseline-custom](/images/docs/guardrails/gp3-baseline-custom.png) + ![gp3-baseline-custom](./gp3-baseline-custom.png) * Scroll to the bottom of the page and click on "Update" to make the above changes to the provisioned product. diff --git a/docs/guides/hosting-guardrails/updating-stacks/index.md b/docs/guides/hosting-guardrails/updating-stacks/index.md index 90118588..91fae787 100644 --- a/docs/guides/hosting-guardrails/updating-stacks/index.md +++ b/docs/guides/hosting-guardrails/updating-stacks/index.md @@ -18,5 +18,10 @@ stack will be updated in tandem with the TE stack and is never deleted. - [Update the TEF stack](guides/hosting-guardrails/updating-stacks/update-tef) - [Update the TED stack](guides/hosting-guardrails/updating-stacks/update-ted) - [Update the TE stack and custom workspace](guides/hosting-guardrails/updating-stacks/update-workspace) +- [Upgrade to Valkey Cache](guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache) + +- [Update Guardrails Domain Name](guides/hosting-guardrails/updating-stacks/domain-update) +- [Upgrade to General Purpose (gp3) EBS Volumes](guides/hosting-guardrails/updating-stacks/general-purpose-gp3) + Head over to the [Releases](/guardrails/changelog) section for release notes for TEF, TED and the TE stacks. \ No newline at end of file diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-select-ted-version.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-select-ted-version.png new file mode 100644 index 00000000..3af9cad6 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-select-ted-version.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-select-tef-version.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-select-tef-version.png new file mode 100644 index 00000000..04e6c414 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-select-tef-version.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-1.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-1.png new file mode 100644 index 00000000..3d6a7aa2 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-1.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-2.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-2.png new file mode 100644 index 00000000..8c2aa6d3 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-2.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-3.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-3.png new file mode 100644 index 00000000..4c91a8b9 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-pgbouncer-params-3.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-update.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-update.png new file mode 100644 index 00000000..11153921 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-ted-update.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-update-tef-parameters.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-update-tef-parameters.png new file mode 100644 index 00000000..ca6c6bfd Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-update-tef-parameters.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-update-tef.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-update-tef.png new file mode 100644 index 00000000..094f2888 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/aws-update-tef.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/ecs-services.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/ecs-services.png new file mode 100644 index 00000000..35075061 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/ecs-services.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/ecs-task-logs.png b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/ecs-task-logs.png new file mode 100644 index 00000000..5b30f723 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/ecs-task-logs.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/index.md b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/index.md new file mode 100644 index 00000000..5dd8cd85 --- /dev/null +++ b/docs/guides/hosting-guardrails/updating-stacks/update-pgbouncer/index.md @@ -0,0 +1,217 @@ +--- + title: Enable PgBouncer + sidebar_label: Enable PgBouncer +--- + +# Enable PgBouncer Connection Pooling + +In this guide, you will: +- Use AWS Service Catalog to enable PgBouncer in an existing environment. +- Monitor and troubleshoot the process. + +[PgBouncer](https://www.pgbouncer.org/) is a lightweight connection-pooler that sits between Turbot Guardrails services and the [Hive](https://turbot.com/guardrails/docs/reference/glossary#hive) PostgreSQL database. By multiplexing thousands of client connections into a much smaller pool of backend connections, PgBouncer dramatically reduces the number of active sessions on Hive, lowering memory consumption and protecting the database from connection storms. + +## Prerequisites + +- Access to the Guardrails AWS account with [Administrator Privileges](/guardrails/docs/enterprise/FAQ/admin-permissions). +- [TEF](/guardrails/docs/reference/glossary#turbot-guardrails-enterprise-foundation-tef) version 1.68.0 or later +- [TED](/guardrails/docs/reference/glossary#turbot-guardrails-enterprise-database-ted) version 1.50.0 or later +- [TE](/guardrails/docs/reference/glossary#turbot-guardrails-enterprise-te) version 5.52.0 or later +- Familiarity with AWS Console, Service Catalog and CloudFormation services. + +Select the desired TEF version under **Product Versions**. + +![Select TEF Version](./aws-select-tef-version.png) + +### Step 2: Update PgBouncer Parameter + +Set **Enable PgBouncer** to **true** in the `Advanced – PgBouncer` section to turn on connection pooling for your Collective. + +![Enable PG Bouncer](./aws-update-tef-parameters.png) +To begin the upgrade process, you will first need to locate and access the TEF provisioned product in AWS Service Catalog and initiate an update. + +Follow the same initial steps outlined in the [Updating TEF](/guardrails/docs/guides/hosting-guardrails/updating-stacks/update-tef) guide to: +- Access AWS Service Catalog +- Select the TEF provisioned product +- Initiate the update action + +Once you've reached the version selection step in Service Catalog, return here to continue with the pgbouncer update process. + +// Check with RahulS, this shd be TED or TEF +Select the desired TEF version under **Product Versions**. + +![Select TEF Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-select-ted-version.png) + +Set **Enable PgBouncer** to **true** in the `Advanced – PgBouncer` section to turn on connection pooling for your Collective. + +![Enable PG Bouncer](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-select-ted-version.png) + +After verifying any changes to existing parameters, select **Update** at the bottom of the screen. + +![Select TEF Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-select-ted-version.png) + +### Step 3: Update TEF + +After verifying any changes to existing parameters, select **Update** at the bottom of the screen. + +![Update TEF](./aws-update-tef.png) + +## Update TED + +Similar to TEF, locate and access the TED provisioned product in AWS Service Catalog and initiate an update. + +Follow the same initial steps outlined in the [Updating TED](/guardrails/docs/runbooks/enterprise-install/update-ted) guide to: +- Access AWS Service Catalog +- Select the TED provisioned product +- Initiate the update action + +Once you've reached the version selection step in Service Catalog, continue with the pgbouncer update steps: + +### Step 1: Select Version + +Select the desired TED version under **Product Versions**. + +![Select TED Version](./aws-select-ted-version.png) + +### Step 2: Update Parameters + +TED provides a comprehensive set of settings, but when first enabling PgBouncer, you can safely leave all values at their defaults. + +You can revisit these parameters if you need to scale PgBouncer beyond the baseline. To understand or review the available settings, see the [Configuration & Tuning](#configuration--tuning) section below. + +![PgBouncer Parameters Update](./aws-ted-pgbouncer-params-1.png) + +> [!NOTE] It is recommended to set the **PgBouncerLogStats** parameter to **enabled** in TED to verify and view PgBouncer activation logs. + +![PgBouncer Parameters Update](./aws-ted-pgbouncer-params-2.png) + +![PgBouncer Parameters Update](./aws-ted-pgbouncer-params-3.png) + +### Step 3: Update TED + +After verifying any changes to existing parameters, select **Update** at the bottom of the screen. + +![Update TED](./aws-ted-update.png) + +## Install or Update TE + +PgBouncer support requires **Turbot Guardrails Enterprise (TE) 5.52.0** or later. Use the existing [Install TE](guides/hosting-guardrails/installation/install-te) guide to install a new TE product and upgrade the workspaces. PgBouncer will activate automatically if `Enable PgBouncer` was set to `true` during the TEF update. No additional parameters need changing at the workspace level. + +## Verify PgBouncer Activation +Similar to TEF, locate and access the TED provisioned product in AWS Service Catalog and initiate an update. + +Follow the same initial steps outlined in the [Updating TED](/guardrails/docs/runbooks/enterprise-install/update-ted) guide to: +- Access AWS Service Catalog +- Select the TED provisioned product +- Initiate the update action + +Once you've reached the version selection step in Service Catalog, continue with the pgbouncer update steps: + +Select the desired TED version under **Product Versions**. + +![Select TED Version](./service-catalog-select-ted-version.png) + +TED provides a comprehensive set of settings, but when first enabling PgBouncer, you can safely leave all values at their defaults. + +You can revisit these parameters if you need to scale PgBouncer beyond the baseline. To understand or review the available settings, see the [Configuration & Tuning](#configuration--tuning) section below. + +![PgBouncer Parameters Update](./service-catalog-ted-update-parameters.png) + +> [!NOTE] It is recommended to set the **PgBouncerLogStats** parameter to **enabled** in TED to verify and view PgBouncer activation logs. + +![PgBouncer Parameters Update](./service-catalog-ted-update-parameters.png) + +![PgBouncer Parameters Update](./service-catalog-ted-update-parameters.png) + +After verifying any changes to existing parameters, select **Update** at the bottom of the screen. + +![Update TED](./service-catalog-ted-update-parameters.png) + +## Step 3: Install or Update TE + +PgBouncer support requires **Turbot Guardrails Enterprise (TE) 5.52.0** or later. Use the existing [Install TE](guides/hosting-guardrails/installation/install-te) guide to install a new TE product and upgrade the workspaces. PgBouncer will activate automatically if `Enable PgBouncer` was set to `true` during the TEF update. No additional parameters need changing at the workspace level. + +## Step 4: Verify PgBouncer Activation + +The most reliable way to verify that PgBouncer is active is by checking its statistics output from the ECS logs. + +> [!NOTE] To view PgBouncer logs, ensure the TED parameter **PgBouncerLogStats** is set to **enabled**. + +### Step 1: Navigate to ECS Service Task + +Navigate to your ECS service `__pgbouncer` (for example: `turbot_newton_pgbouncer` if using default names) and Select the running task. + +![ECS Service Task](./ecs-services.png) + +### Step 2: View Logs + +Select the **Logs** tab to view the stats displayed under `Message`. PgBouncer is confirmed to be running and actively processing database traffic based on the presence of these stats. + +The `STATS` lines appear every 5 minutes with metrics like: +Navigate to your ECS service `__pgbouncer` (for example: `turbot_newton_pgbouncer` if using default names) and Select the running task and view its logs. + +![ECS Service Task](./service-catalog-ted-update-parameters.png) + +4. The `STATS` lines appear every 5 minutes with metrics like: + ``` + stats: 9 xacts/s, 8 queries/s, 8 client parts/s, 8 server parts/s, 8 kB/s/s, in 277 B/s, out 1000 B/s, xact 54224 us, query 47520 us, wait 126 us + ``` + These stats show: + - Active client and server connections + - Query throughput + - Transaction latency + - Network traffic + +![ECS Task Logs](./ecs-task-logs.png) +![ECS Task Logs](./service-catalog-ted-update-parameters.png) + +PgBouncer is confirmed to be running and actively processing database traffic based on the presence of these stats. + +## Configuration & Tuning + +### Sizing Guidelines + +1. **Database Connections** – a good starting point is **2–3 connections per vCPU** on the Hive instance. + * r6g.large (2 vCPU) → 4–6 connections + * r6g.2xlarge (8 vCPU) → 16–24 connections + This usually represents 10–20% of the instance's Postgres `max_connections`, leaving plenty of headroom for maintenance users and bursts. + +2. **Client Connections** – the default **2000** is sufficient for most Collectives. If you need more: + * Add more PgBouncer tasks by increasing the desired task count + * Adjust container resources (CPU and memory allocation) + +3. **High Availability** – enable zone spreading and set at least 2 desired tasks so a single AZ outage doesn't break connectivity. + +### Connection Settings + +- **Maximum Client Connections** (`PgBouncerMaxClientConnections`) – raise beyond 2000 only if you have many concurrent workers +- **Maximum Database Connections** (`PgBouncerMaxDbConnections`) – adjust when you upscale your RDS instance +- **Worker Pool Size** (`PgBouncerConnectionPoolSize`) – size of the worker connection pool (default: 10) +- **API Pool Size** (`PgBouncerApiConnectionPoolSize`) – size of the API connection pool (default: 2) + +### Resource Settings + +- **Task Count** (`PgBouncerDesiredCount`) – number of PgBouncer tasks to run (≥ 2 recommended for HA) +- **CPU Units** (`PgBouncerCpuAllocation`) – CPU units per task (default: 512 = 0.5 vCPU) +- **Memory** (`PgBouncerMemoryAllocation`) – memory per task (default: 128 MiB) + +### Monitoring Settings + +- **Statistics Logging** (`PgBouncerLogStats`) – enables aggregated stats every 5 minutes showing active clients, connections, and performance metrics +- **Connection Logging** (`PgBouncerLogConnections`, `PgBouncerLogDisconnections`) – enables logging of individual connections/disconnections (useful for troubleshooting) + +## Next Steps + +Please see the following resources to learn more about Turbot Guardrails Enterprise: + +- Learn more about [Turbot Guardrails Enterprise - Architecture](/guardrails/docs/enterprise/architecture). +- Learn about [TED Installation](/guardrails/docs/enterprise/installation/ted-installation) + +## Troubleshooting + +| Issue | Description | Guide | +|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------| +| Permission Issues | If the current logged-in user lacks permission to modify, update, or create resources in the stack, or if IAM roles or SCPs have changed, preventing built-in roles from accessing needed configuration settings. | [Troubleshoot Permission Issues](/guardrails/docs/enterprise/FAQ/admin-permissions#aws-permissions-for-turbot-guardrails-administrators) | +| Stack Rollback Failure Due to Database State | If the CloudFormation stack attempts to roll back but fails because the database is in a state (e.g., Upgrading, Backing Up) that prevents a successful rollback. | [Troubleshoot Rollback Failures](guides/hosting-guardrails/troubleshooting/database-instance-not-in-available-state) | +| Service Catalog Sync Issue | If the Service Catalog Provisioned product, CloudFormation Stack, or the physical RDS instance becomes out of sync, causing issues with updates or resource management. | [Troubleshoot Sync Issues](guides/hosting-guardrails/troubleshooting/service-catalog-out-of-sync) | +| Further Assistance | If you continue to encounter issues, please open a ticket with us and attach the relevant information to assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-ted/index.md b/docs/guides/hosting-guardrails/updating-stacks/update-ted/index.md index 2191ab8a..c11a6125 100644 --- a/docs/guides/hosting-guardrails/updating-stacks/update-ted/index.md +++ b/docs/guides/hosting-guardrails/updating-stacks/update-ted/index.md @@ -25,74 +25,80 @@ TED is the database layer of a Turbot Guardrails Enterprise deployment. Creates Open the AWS Console and navigate to the RDS service in the region where TED is deployed. -![Access RDS Console](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/rds-console-access.png) +![Access RDS Console](./rds-console-access.png) ## Step 2: Find RDS Instance -![Find RDS Instance](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/rds-find-instance.png) +![Find RDS Instance](./rds-find-instance.png) ## Step 3: Check RDS Instance Status Check the DB instance `Status` in `Available` state. -![RDS Instance Status](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/rds-instance-status-available.png) +![RDS Instance Status](./rds-instance-status-available.png) ## Step 4: Access AWS Service Catalog Open the AWS Console and navigate to the Service Catalog service in the region where TED is deployed. -![AWS Console Home Page](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/aws-service-catalog-console.png) +![AWS Console Home Page](./aws-service-catalog-console.png) ## Step 5: Navigate Provisioned Products Choose **Provisioned Products** from the left navigation menu. -![Provisioned Products](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-provisioned-products.png) +![Provisioned Products](./service-catalog-provisioned-products.png) ## Step 6: View Provisioned Products Change the **Access Filter** in AWS Service Catalog from **User** to **Account** to view all TED provisioned products across the entire account. -![Access Filter](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-select-access-filter.png) +![Access Filter](./service-catalog-select-access-filter.png) ## Step 7: Find Provisioned Product The TED provisioned product is identifiable by a postfix that matches the database Hive name. -![Find TED](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-find-provisioned-product-ted.png) +![Find TED](./service-catalog-find-provisioned-product-ted.png) From the **Actions** menu, select **Update** -![Select Update](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-actions-update.png) +![Select Update](./service-catalog-actions-update.png) ## Step 8: Find Version Sort the Product versions section by **Created time** (descending) to see the latest available version. -![Find TED Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-find-ted-product-versions.png) +![Find TED Version](./service-catalog-find-ted-product-versions.png) ## Step 9: Select Version Select the desired TED version under **Product Versions**. -![Select TED Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-select-ted-version.png) +![Select TED Version](./service-catalog-select-ted-version.png) ## Step 10: Verify Parameters The values of the parameters will initially be set to match previous run of the product. Review the [release notes](https://turbot.com/guardrails/changelog?tag=ted) for the TED versions between the existing version and the version you are updating to, and identify any new parameters that require a decision about how they will be set. Generally, new parameters will be created in a way to have the least disruption on an existing environment, but care should still be taken to understand these and read any new parameter descriptions to understand their impact. -![Parameters Verification](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-ted-verify-parameters.png) +![Parameters Verification](./service-catalog-ted-verify-parameters.png) > [!CAUTION] > A frequent issue arises when databases employ auto-scaling storage. Discrepancies in storage figures between the stack and the product can occur if the database has expanded since installation. > Upgrading to a major version can introduce significant changes and potential risks. You should not upgrade to a new major version without first consulting with Turbot Support. > To ensure cost-efficiency, review and update instance types and ElastiCache Versions at least annually to align with the latest supported options. +### Upgrade to Valkey cache + +As part of the TED infrastructure, Redis has previously been the default caching engine. We now recommend moving to [Valkey](https://aws.amazon.com/elasticache/what-is-valkey/), a community-driven alternative to Redis. + +For customers currently using Redis OSS cache, [here is how to update to Valkey](/guardrails/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache). + ## Step 11: Update TED After verifying any changes to existing parameters, select **Update** at the bottom of the screen. -![Select Update](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-ted-update-action.png) +![Select Update](./service-catalog-ted-update-action.png) ## Step 12: Monitor Update @@ -103,21 +109,21 @@ You have initiated the installation of the new TED version. This triggers an upd Select the TED Provisioned Product, select the **Outputs** tab, and use the **CloudFormationStackARN** **Value** link to navigate to the CloudFormation stack and monitor the update progress. -![Navigate ](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-update-ted-navigate-to-cfn.png) +![Navigate ](./service-catalog-update-ted-navigate-to-cfn.png) The TED CloudFormation stack status should change to `UPDATE_IN_PROGRESS` indicating the update process is in progress. -![Update Progress ](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/cfn-ted-update-progress.png) +![Update Progress ](./cfn-ted-update-progress.png) ## Step 13: Review - [ ] The TED CloudFormation stack status should change to `UPDATE_COMPLETE` indicating the update completed successfully. -![Verify Status](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/cfn-ted-update-complete.png) +![Verify Status](./cfn-ted-update-complete.png) - [ ] The TED `Provisioned product` status should change to `Available`. -![TED Provisioned Product Complete Status](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-ted-update-complete.png) +![TED Provisioned Product Complete Status](./service-catalog-ted-update-complete.png) ## Next Steps diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-ted-update-parameters.png b/docs/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-ted-update-parameters.png new file mode 100644 index 00000000..89f7a8fd Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/update-ted/service-catalog-ted-update-parameters.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-tef/index.md b/docs/guides/hosting-guardrails/updating-stacks/update-tef/index.md index 0343948c..667b2d72 100644 --- a/docs/guides/hosting-guardrails/updating-stacks/update-tef/index.md +++ b/docs/guides/hosting-guardrails/updating-stacks/update-tef/index.md @@ -22,41 +22,41 @@ The TEF CloudFormation stack creates and manages the networking and compute comp Open the AWS Console and navigate to the Service Catalog service in the region where TEF is deployed. -![AWS Console Home Page](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/aws-service-catalog-console.png) +![AWS Console Home Page](./aws-service-catalog-console.png) ## Step 2: Navigate Provisioned Products Choose **Provisioned Products** from the left navigation menu. -![Provisioned Product](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-provisioned-products.png) +![Provisioned Product](./service-catalog-provisioned-products.png) ## Step 3: View Provisioned Products Change the **Access Filter** in AWS Service Catalog from **User** to **Account** to view all TEF provisioned products across the entire account. -![Access Filter](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-select-access-filter.png) +![Access Filter](./service-catalog-select-access-filter.png) ## Step 4: Select Provisioned Product Select the TEF provisioned product from the list. -![Select TEF](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-find-provisioned-product-tef.png) +![Select TEF](./service-catalog-find-provisioned-product-tef.png) Select **Actions** menu, select **Update** -![Select Update](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-actions-update.png) +![Select Update](./service-catalog-actions-update.png) ## Step 5: Find Version Sort the Product versions section by `Created time` (descending) to see the latest available version. -![Sort TEF Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-find-tef-product-versions.png) +![Sort TEF Version](./service-catalog-find-tef-product-versions.png) ## Step 6: Select Version Select the desired TEF version under **Product Versions**. -![Select TEF Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-select-tef-version.png) +![Select TEF Version](./service-catalog-select-tef-version.png) ## Step 7: Verify Parameters @@ -64,13 +64,13 @@ The values of the parameters will initially be set to match previous run of the Generally, new parameters will be created in a way to have the least disruption on an existing environment, but care should still be taken to understand these and read any new parameter descriptions to understand their impact. -![Parameters Verification](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-tef-verify-parameters.png) +![Parameters Verification](./service-catalog-tef-verify-parameters.png) ## Step 8: Update TEF After verifying any changes to existing parameters, select **Update** at the bottom of the screen. -![Select Update](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-tef-update-action.png) +![Select Update](./service-catalog-tef-update-action.png) ## Step 9: Monitor Update @@ -78,21 +78,21 @@ You have initiated the installation of the new TEF version. This triggers an upd Select the TEF Provisioned Product, click the `Outputs` tab, and use the `CloudFormationStackARN` link to navigate to CloudFormation and monitor the update progress. -![Navigate To CFN](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-update-tef-navigate-to-cfn.png) +![Navigate To CFN](./service-catalog-update-tef-navigate-to-cfn.png) - [ ] Verify TEF stack status transitions to `UPDATE_IN_PROGRESS` upon modification and review the Events tab for expected parameter/resource updates. -![Verify CFN Status](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/cfn-tef-update-progress.png) +![Verify CFN Status](./cfn-tef-update-progress.png) ## Step 10: Review - [ ] The TEF CloudFormation stack status should change to `UPDATE_COMPLETE` indicating the update completed successfully. -![CFN Update Complete](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/cfn-tef-update-complete.png) +![CFN Update Complete](./cfn-tef-update-complete.png) - [ ] The TEF Provisioned Product status should change to `Available`. -![TEF Provisioned Product Status](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-tef/service-catalog-tef-update-complete.png) +![TEF Provisioned Product Status](./service-catalog-tef-update-complete.png) ## Next Steps diff --git a/docs/guides/hosting-guardrails/updating-stacks/update-workspace/index.md b/docs/guides/hosting-guardrails/updating-stacks/update-workspace/index.md index 245bd774..0a4ac404 100644 --- a/docs/guides/hosting-guardrails/updating-stacks/update-workspace/index.md +++ b/docs/guides/hosting-guardrails/updating-stacks/update-workspace/index.md @@ -20,47 +20,47 @@ A Guardrails [Workspace](/guardrails/docs/reference/glossary#workspace) is updat Open the AWS Console and navigate to the CloudFormation service in the region where your workspace is deployed. -![AWS Console Home Page](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/aws-cloudformation-console.png) +![AWS Console Home Page](./aws-cloudformation-console.png) ## Step 2: Select Stack From the left navigation menu choose **Stacks**. -![Stacks Selection](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-stacks.png) +![Stacks Selection](./cfn-stacks.png) Search for the stack named **workspace**. -![Workspace Stack](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-select-workspace-stack.png) +![Workspace Stack](./cfn-select-workspace-stack.png) Select **Update** -![Update Stack](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-workspace-stack-select-update.png) +![Update Stack](./cfn-workspace-stack-select-update.png) ## Step 3: Update Stack Choose **Use existing template** and select **Next**. -![Select Existing Template](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-stack-use-existing-template.png) +![Select Existing Template](./cfn-stack-use-existing-template.png) Modify the version to match the new TE version number used in the TE stack (e.g., 5.45.4), then select **Next**. -![Select Existing Template](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-stack-specify-te-version.png) +![Select Existing Template](./cfn-stack-specify-te-version.png) ## Step 4: Specify TE Version -![Specify TE Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-stack-specify-te-version.png) +![Specify TE Version](./cfn-stack-specify-te-version.png) Scroll down to **Advanced options**, leave the entire section as default and select **Next** -![Advanced Option as Default TE Version](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-stack-advanced-option-as-default.png) +![Advanced Option as Default TE Version](./cfn-stack-advanced-option-as-default.png) ## Step 5: Submit Changes In **Configure stack options**, review changes under **Changeset Preview** and select **Submit**. -![Submit Changeset](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-worksapce-stack-select-submit-changes.png) +![Submit Changeset](./cfn-worksapce-stack-select-submit-changes.png) ## Step 6: Monitor Update @@ -68,17 +68,17 @@ You have initiated the update of a new TE version in the Guardrails workspace. T - [ ] The workspace CloudFormation stack status should change to `UPDATE_IN_PROGRESS` indicating the update process is in progress. -![Verify Status](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-workspace-stack-update-progress.png) +![Verify Status](./cfn-workspace-stack-update-progress.png) ## Step 7: Review - [ ] The workspace CloudFormation stack status should change to `UPDATE_COMPLETE` indicating the update completed successfully. -![Update Complete](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/cfn-workspace-stack-update-complete.png) +![Update Complete](./cfn-workspace-stack-update-complete.png) - [ ] Updated TE version should reflect in Guardrails `Workspace Admin` panel. -![Guardrails Console Admin Panel](/images/docs/guardrails/guides/hosting-guardrails/updating-stacks/update-workspace/guardrails-console-verify-version.png) +![Guardrails Console Admin Panel](./guardrails-console-verify-version.png) ## Next Steps diff --git a/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/aws-valkey-cache-complete.png b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/aws-valkey-cache-complete.png new file mode 100644 index 00000000..a8c2e69f Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/aws-valkey-cache-complete.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/index.md b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/index.md new file mode 100644 index 00000000..e51e64da --- /dev/null +++ b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/index.md @@ -0,0 +1,96 @@ +--- +title: Upgrading Redis OSS to Valkey Cache +sidebar_label: Upgrade Redis OSS to Valkey +--- + +# Upgrading Redis OSS to Valkey Cache + + + +In this guide, you will: + +- Use the Turbot Enterprise Database provisioned product in Service Catalog to migrate from Redis to Valkey. +- Monitor and troubleshoot the [Valkey](https://aws.amazon.com/elasticache/what-is-valkey/) upgrade process. + +[Turbot Guardrails Enterprise Database (TED)](/guardrails/docs/reference/glossary#turbot-guardrails-enterprise-database-ted) is an AWS Service Catalog product that automates the provisioning and management of the underlying database and caching infrastructure required for enterprise deployments of Turbot Guardrails. + +As part of its infrastructure, TED versions prior to v1.50 use Redis as the caching engine. This guide shows how to update a TED deployment using Redis to one using Valkey. + +The migration process described here will seamlessly provision new Valkey cache clusters and decommission the existing Redis instances, ensuring minimal disruption to your Guardrails environment. + +Learn more about the difference between [Valkey and Redis OSS](https://aws.amazon.com/elasticache/what-is-valkey/). + +## Prerequisites + +- Access to the Guardrails AWS account with [Administrator Privileges](/guardrails/docs/enterprise/FAQ/admin-permissions). +- Familiarity with AWS Console, Service Catalog, and CloudFormation services. +- TED version 1.50.x or higher. + +### Pause Events + +[Pause the events](/guardrails/docs/guides/hosting-guardrails/troubleshooting/pause-events#pause-event-processing) to avoid any lost events. During this time, the respective workspace will still be available in `readonly` mode. + +>[!CAUTION] +> AWS only supports migrating from Redis to Valkey within ElastiCache. There is no supported migration path from Valkey back to Redis. +> +> Additionally, AWS has announced that support for Redis in ElastiCache will be deprecated in the future. For more details, see the [official AWS announcement](https://aws.amazon.com/about-aws/whats-new/2024/05/amazon-elasticache-valkey/). + +To begin the upgrade process, you will first need to locate and access the TED provisioned product in AWS Service Catalog and initiate an update. + +Follow the same initial steps outlined in the [Updating TED](/guardrails/docs/runbooks/enterprise-install/update-ted) guide to: +- Access AWS Service Catalog +- Select the TED provisioned product +- Initiate the update action + +Once you've reached the version selection step in Service Catalog, return here to continue with the Valkey upgrade process. + +## Step 1: Select TED Version + +Select the desired TED version under **Product Versions**. + +> [!NOTE] +> Valkey is only available in TED version 1.50.x or higher. + +![Select TED Version](./service-catalog-select-ted-version.png) + +## Step 2: Update Parameters + +Under **cache**, choose `Valkey` as the ElastiCache Engine. Then select the desired version from the `Valkey Cache Version` dropdown. + +![Valkey Parameters Update](./service-catalog-ted-update-parameters.png) + +## Step 3: Update TED + +After verifying all parameters, scroll down and select **Update**. This initiates an update of several nested CloudFormation stacks. + +![Select Update](./service-catalog-ted-update-action.png) + +## Step 4: Monitor the Update + +Monitor the stack update in progress from the CloudFormation console. Refer [Update TED > Step 12: Monitor Update](/guides/hosting-guardrails/updating-stacks/update-ted#step-12-monitor-update) + +## Step 5: Review + +Verify Valkey Cache deployment is successful in the AWS console. + +* [ ] The newly created Valkey caches can be found under `Valkey caches` in the AWS ElastiCache dashboard. + +![Verify Status](./aws-valkey-cache-complete.png) + +## Next Steps + +Please see the following resources to learn more about Turbot Guardrails Enterprise: + +- [Turbot Guardrails Enterprise - Architecture](/guardrails/docs/enterprise/architecture). +- [Hosting Guardrails](/guardrails/docs/guides/hosting-guardrails) + +## Troubleshooting + +| Issue | Description | Guide | +| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Permission Issues | The current logged-in user lacks permission to modify, update, or create resources in the stack, or IAM roles/SCPs prevent built-in roles from accessing required configurations. | [Troubleshoot Permission Issues](/guardrails/docs/enterprise/FAQ/admin-permissions#aws-permissions-for-turbot-guardrails-administrators) | +| Stack Rollback Failure Due to Database State | CloudFormation stack fails to roll back because the database is in a state (e.g., Upgrading, Backing Up) that prevents rollback. | [Troubleshoot Rollback Failures](guides/hosting-guardrails/troubleshooting/database-instance-not-in-available-state) | +| Service Catalog Sync Issue | Service Catalog product, CloudFormation Stack, or physical RDS instance is out of sync, leading to update or resource management issues. | [Troubleshoot Sync Issues](guides/hosting-guardrails/troubleshooting/service-catalog-out-of-sync) | +| Further Assistance | If issues persist, open a support ticket with relevant logs and screenshots. | [Open Support Ticket](https://support.turbot.com) | diff --git a/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-select-ted-version.png b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-select-ted-version.png new file mode 100644 index 00000000..fbe6542c Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-select-ted-version.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-ted-update-action.png b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-ted-update-action.png new file mode 100644 index 00000000..9a175ff4 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-ted-update-action.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-ted-update-parameters.png b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-ted-update-parameters.png new file mode 100644 index 00000000..89f7a8fd Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache/service-catalog-ted-update-parameters.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/index.md b/docs/guides/using-guardrails/ai/ai-configuration/index.md new file mode 100644 index 00000000..8d865cfe --- /dev/null +++ b/docs/guides/using-guardrails/ai/ai-configuration/index.md @@ -0,0 +1,124 @@ +--- +title: AI Configuration +sidebar_label: AI Configuration +--- + +# Turbot AI Configuration + +In this guide, you will learn how to: + +- Configure various parameters in `Turbot > AI > Configuration` policy + +This guide is the starting point for all AI-powered features, including `Intelligent Assessment Control`, `Intelligent Fixes`, and `Policy Pack Summary`. Before using any AI capabilities in Guardrails, ensure you have completed the steps outlined in this guide. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Access credentials for the AI model. + + +## Step 1: Find Turbot > AI Policy + +Log in to the Guardrails console using your local credentials or via a SAML-based login. From the **Policies** tab, navigate to *Turbot > AI* in the Guardrails console. + +This section provides AI-related policies that allow Guardrails to govern the use of AI for various configurations and settings. Select **Configurations**. + +![Turbot > AI > Configurations](./turbot-ai-configuration.png) + +## Step 2: Configure AI Provider + +Select **Turbot > AI > Configuration > Provider [Default]** to configure the AI service provider. The default value is set to `openai`. + +In this example, `anthropic` is selected. + +![Turbot > AI > Provider](./turbot-ai-provider.png) + +## Step 3: Configure API Key + +Select **Turbot > AI > Configuration > API Key [Default]** policy under the `Turbot > AI > Configuration` main policy. + +Enter the API key for the provider chosen in Step 2. Guardrails will use this key to authenticate with your AI service provider. + +![Turbot > AI > Configuration > API Key Policy Setting](./turbot-ai-api-key.png) + +> [!IMPORTANT] +> - The API key is a sensitive credential used for authentication with your chosen AI service provider. Ensure it is stored and handled securely. +> - For OpenAI: +> - Obtain the API key from the [OpenAI platform](https://platform.openai.com/api-keys) +> - The key should start with "sk-" +> - For Anthropic: +> - Get the API key from the [Anthropic console](https://console.anthropic.com/settings/keys) +> - The key should start with "sk-ant-" +> - Store the API key securely and rotate it periodically according to your organization's security policies. +> - Never share or expose the API key in logs, code repositories, or public forums. + +## Step 4: Configure AI Model + +Select **Turbot > AI > Configuration > Model [Default]** policy under the `Turbot > AI > Configuration` main policy. + +Choose the model to use with the selected AI provider for processing requests. + +![Choose the AI Model](./turbot-ai-model.png) + +> [!NOTE] +> Supported and tested models include: +> - [OpenAI models](https://platform.openai.com/docs/pricing#latest-models): `gpt-4.1`, `gpt-4.1-mini`, `gpt-4o` +> - [Anthropic models](https://docs.anthropic.com/en/docs/about-claude/models/overview#model-names): `claude-sonnet-4-20250514`, `claude-3-7-sonnet-20250219`, `claude-3-5-haiku-20241022`, `claude-3-5-sonnet-20241022` +> +> For optimal results: +> - Use the latest model versions when possible. +> - Higher-tier models (like GPT-4 series and Claude Sonnet/Haiku series) provide more accurate and detailed assessments. +> - Lower-tier models may produce different or less consistent results. +> - Model availability may vary based on your AI provider subscription. +> - For more information about the models, see the documentation for [OpenAI](https://platform.openai.com/docs/models) and [Anthropic](https://docs.anthropic.com/en/docs/models-overview). + +## Step 5: Configure Max Tokens + +Select **Turbot > AI > Configuration > Max Tokens [Default]** under the `Turbot > AI > Configuration` main policy. The default value is set to `1000` as a best practice. + +> [!TIP] +> - Configure the maximum number of tokens to use for the AI API calls. This setting controls the length of the AI's response by limiting the number of tokens (words, subwords, or characters) that can be generated. +> - A higher value allows for longer, more detailed responses but may increase API costs and response time. +> - A lower value produces more concise responses. +> - The default value of 1000 tokens provides a good balance for most use cases, but you can adjust this based on your specific needs and the complexity of the tasks you want the AI to perform. + +You can adjust this based on your specific needs and the complexity of the tasks you want the AI to perform. + +## Step 6: Configure Temperature + +The policy **Turbot > AI > Configuration > Temperature [Default]** allows you to configure the temperature parameter for AI API calls. Temperature controls the randomness or creativity of the AI's responses. + +A lower value (closer to 0) makes responses more focused, deterministic, and consistent, while a higher value (closer to 1) makes responses more diverse and creative. The default value of 0.2 provides a good balance between consistency and creativity, suitable for most business and technical use cases. + +The default value is set to `0.2`. You may choose to update it based on your needs. + +## Step 7: Enable Configuration + +The **Turbot > AI > Configuration > Enabled [Default]** policy under `Turbot > AI > Configuration` plays an important role if you wish to apply configurations to all features under `Turbot > AI`. You may choose to continue with the default value `Disabled` and enable it in respective features separately. + +To enable it, select **New Policy Settings**, set **Resource** to `Turbot`, and choose `Enabled`. + +![Enable AI Configuration](./turbot-ai-configuration-enabled.png) + +## Review + +- [ ] Validate that all the required settings are in place. + +![Review AI Configuration](./turbot-ai-configuration-review.png) + +## Next Steps + +After completing this configuration, continue with the following guides to leverage AI features in Guardrails: + +- [Enable Intelligent Assessment](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) +- [Enable Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes/) +- [Enable Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary/) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-api-key.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-api-key.png new file mode 100644 index 00000000..49ea5142 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-api-key.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-enabled.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-enabled.png new file mode 100644 index 00000000..52c67cb0 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-review.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-review.png new file mode 100644 index 00000000..161da03c Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-review.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration.png new file mode 100644 index 00000000..c1984382 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-model.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-model.png new file mode 100644 index 00000000..0794643a Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-model.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-provider.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-provider.png new file mode 100644 index 00000000..380e06d9 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-provider.png differ diff --git a/docs/guides/using-guardrails/ai/ai-sidebar.json b/docs/guides/using-guardrails/ai/ai-sidebar.json new file mode 100644 index 00000000..91b754a1 --- /dev/null +++ b/docs/guides/using-guardrails/ai/ai-sidebar.json @@ -0,0 +1,11 @@ +{ + "type": "category", + "id": "ai", + "link": "guides/using-guardrails/ai", + "items": [ + "guides/using-guardrails/ai/ai-configuration", + "guides/using-guardrails/ai/enable-intelligent-assessment", + "guides/using-guardrails/ai/enable-intelligent-fixes", + "guides/using-guardrails/ai/enable-policy-pack-summary" + ] +} diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-create-setting.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-create-setting.png new file mode 100644 index 00000000..bff11e0d Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-create-setting.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-ia-context.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-ia-context.png new file mode 100644 index 00000000..577943a4 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-ia-context.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-intelligent-assessment-response.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-intelligent-assessment-response.png new file mode 100644 index 00000000..16eb7e9c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-intelligent-assessment-response.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-intelligent-assessment-check-mode.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-intelligent-assessment-check-mode.png new file mode 100644 index 00000000..99745c2c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-intelligent-assessment-check-mode.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/index.md b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/index.md new file mode 100644 index 00000000..7c5246f4 --- /dev/null +++ b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/index.md @@ -0,0 +1,129 @@ +--- +title: Enable Intelligent Assessment +sidebar_label: Enable Intelligent Assessment +--- + +# Enable Intelligent Assessment + +In this guide, you will learn how to: + +- Set up custom user prompts and context for resource evaluation. +- Enable Intelligent Assessment for a specific S3 bucket control as an example. + +The [Intelligent Assessment](/guardrails/docs/concepts/guardrails/intelligent-assessment) [control](/guardrails/docs/reference/glossary#control) introduces an AI-powered way to define and evaluate governance policies in Turbot Guardrails. Instead of crafting complex calculated policies, you can describe the check you want in plain natural language, and let Guardrails interpret and evaluate it. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Ensure that [Turbot > AI > Configuration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) is set up. + +## Step 1: Enable Intelligent Assessment Control + +Log in to the Guardrails console using your local credentials or via a SAML-based login. + +Enable the following policy at the Turbot level: **Turbot > AI > Control > Intelligent Assessment > Enabled**. This enables AI capabilities for Intelligent Assessment controls. + +> [!NOTE] +> - The default value is `Disabled`. You can enable it based on your requirements. +> - If enabled at the Turbot level in [Turbot AI Configuration > Step 7](/guardrails/docs/guides/using-guardrails/ai/ai-configuration#step-7-enable-configuration), the Intelligent Assessment control becomes available for use. + +For this guide, the `Turbot > AI > Control > Intelligent Assessment > Enabled` policy is set to `Enabled`. + +![Enable Intelligent Assessment Control](./turbot-ai-intelligent-assessment-enabled.png) + +## Step 2: Find Targeted S3 Bucket + +Navigate to the **Resources** tab and search for the S3 bucket you want to assess. You can filter by: + +- Resource type: `AWS > S3 > Bucket` +- Bucket name in the search bar + +![Find S3 Bucket](./locate-aws-s3-bucket.png) + +Select the bucket to view its details and controls. This will be the target resource for setting up `Intelligent Assessment`. + +> [!TIP] +> You can also find the required bucket using **Reports** > **AWS S3 Buckets**. + +## Step 3: Add User Prompt + +While in `AWS > S3 > Bucket`, select the **Policies** tab and choose the `AWS > S3 > Bucket > Intelligent Assessment > User Prompt` policy. + +Select **New Policy Setting** to add a new prompt. + +![Locate User Prompt Policy](./locate-user-prompt-policy.png) + +Here you can define the prompt that will be sent to the AI provider for resource assessment. Ensure your instructions are clear and specific. + +![Set the User Prompt Value for Assessment](./set-user-prompt-value.png) + +> [!NOTE] +> You can set this policy at the resource, account, or folder level. +> For more information, see [Guardrails Policy Hierarchy](/guardrails/docs/concepts/policies/hierarchy). + +**Example Prompt:** +``` +- Confirm that logging is enabled and logs are sent to a secure location. +- Check if versioning is enabled and multi-factor delete is configured when the bucket has a tag "Environment":"Non-Compliant Tag". If it doesn't have the tag, only check if versioning is enabled. +- Ensure that the S3 bucket is not publicly accessible and all access is restricted to specific IAM roles or users. +- Verify that server-side encryption is enabled using AWS KMS for all objects in the bucket. +- Check if the bucket policy denies unencrypted uploads and enforces HTTPS-only access. +- Confirm that lifecycle rules are configured to transition objects to Glacier storage after 30 days and delete them after 365 days. +- Ensure that the bucket has a policy to block all public ACLs and public bucket policies. +- Validate that only specific IP address ranges (e.g., 10.0.0.0/8) are allowed to access the bucket. +- Check if object lock is enabled for regulatory compliance and retention. +- Confirm that the bucket has a tag \"Owner\" with a valid email address. +- Ensure that cross-region replication is enabled to a backup bucket in another AWS region. +- Verify that access logging is enabled and logs are sent to a dedicated logging bucket with restricted access. +``` +## Step 4: Set up Context + +The sub-policy `AWS > S3 > Bucket > Intelligent Assessment > Context` defines the context information in JSON format that will be provided to the configured AI provider for the intelligent assessment of the S3 bucket. + +By default, the context includes the resource's attributes and metadata required for accurate evaluation. In this example, we will use the `default context`. + +![Intelligent Assessment Context](./aws-s3-bucket-ia-context.png) + +> [!NOTE] +> You may customize this context to include additional information relevant to your assessment needs. + +## Step 5: Set Primary Policy to Check Mode + +Now that the user prompt is set with the default context, let's set up the primary policy `AWS > S3 > Bucket > Intelligent Assessment` for this S3 bucket. + +To access the main policy, while in the `AWS > S3 > Bucket > Intelligent Assessment` **Controls**, select the **Policies** tab. If not set earlier, you may find `Intelligent Assessment` is set to `Skip`. + +![Create Settings](./aws-s3-bucket-create-setting.png) + +Select **CREATE SETTING** and set the option to `Check: User prompt`. This policy activates Intelligent Assessment for the S3 bucket based on your user prompt and context. + +> [!NOTE] +> You can set this policy at the resource, account, or folder level. +> For more information, see [Guardrails Policy Hierarchy](/guardrails/docs/concepts/policies/hierarchy). + +![Set the Intelligent Assessment Policy for S3 Bucket](./aws-s3-intelligent-assessment-check-mode.png) + +## Step 6: Check Control Status + +The control will assess the S3 bucket using the configured user prompt and evaluate the control. + +![Example Output from S3 Bucket Intelligent Assessment](./aws-s3-bucket-intelligent-assessment-response.png) + +> [!NOTE] +> The output is generated by the AI provider and may vary based on the model's capabilities and input details. + +## Next Steps + +To explore more Guardrails features: + +- [Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes) +- [Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary) +- [Configure Guardrails MCP Server](/guardrails/docs/guides/using-guardrails/ai/install-mcp) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-aws-s3-bucket.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-aws-s3-bucket.png new file mode 100644 index 00000000..2e58d97c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-aws-s3-bucket.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-user-prompt-policy.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-user-prompt-policy.png new file mode 100644 index 00000000..763b76a7 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-user-prompt-policy.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/set-user-prompt-value.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/set-user-prompt-value.png new file mode 100644 index 00000000..31124791 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/set-user-prompt-value.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/turbot-ai-intelligent-assessment-enabled.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/turbot-ai-intelligent-assessment-enabled.png new file mode 100644 index 00000000..96056c25 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/turbot-ai-intelligent-assessment-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-cli-outcome.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-cli-outcome.png new file mode 100644 index 00000000..e847a917 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-cli-outcome.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-quick-action.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-quick-action.png new file mode 100644 index 00000000..6bd18455 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-quick-action.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-steps-tf.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-steps-tf.png new file mode 100644 index 00000000..7561b5a1 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-steps-tf.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-tf-outcome.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-tf-outcome.png new file mode 100644 index 00000000..47e17ab9 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-tf-outcome.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/index.md b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/index.md new file mode 100644 index 00000000..c6712a65 --- /dev/null +++ b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/index.md @@ -0,0 +1,87 @@ +--- +title: Enable Intelligent Fixes +sidebar_label: Enable Intelligent Fixes +--- + +# Enable Intelligent Fixes + +In this guide, you will learn how to: + +- Get AI-generated remediation steps for non-compliant resources. +- Review and implement recommended fixes for security and compliance issues. +- Understand the context and impact of suggested remediation actions. + +When a resource is found to be non-compliant i.e. enters an alarm state, Intelligent Fixes analyzes: + +- **Alert Summary:** Clear explanation of why the control is in alarm and what needs to be addressed. +- **Guardrails Actions:** Available `Quick Actions` and policy changes within the platform. +- **Cloud Provider CLI:** Direct commands for AWS, Azure, gcloud, kubectl, and gh CLIs to fix the misconfiguration. +- **Infrastructure-as-Code:** Terraform plans to remediate the issue via code. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Ensure that [Turbot > AI > Configuration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) is set up. + +## Step 1: Enable Intelligent Fixes + +In the **Policies** tab, navigate to `Turbot > AI > Control > Intelligent Fixes` and select the **Enabled** option. Create a new setting by selecting **New Policy Setting**. + +![Enable Intelligent Fixes Control](./turbot-ai-intelligent-fixes-enabled.png) + +> [!NOTE] +> - The default value is `Disabled`. You can enable it based on your requirements. +> - If enabled at the Turbot level in [Turbot AI Configuration > Step 7](/guardrails/docs/guides/using-guardrails/ai/ai-configuration#step-7-enable-configuration), the Intelligent Assessment control becomes available for use. + +For this guide, the `Turbot > AI > Control > Intelligent Fixes > Enabled` policy is set to `Enabled`. + +## Step 2: Check Remediation + +Navigate to any control in the `ALARM` state. The remediation steps will automatically begin to load, and you will see an initial message: "Generating remediation steps…". + +For example, let's consider `AWS > S3 > Bucket > Tags`. + +![Generate Intelligent Fixes](./aws-s3-bucket-tags-remediation-steps-tf.png) + +The AI will analyze the non-compliant resource and generate remediation steps in multiple options such as CLI, Terraform, and CloudFormation. + +**Remediation in Terraform** + +![AWS > S3 > Bucket > Tag > CLI Remediation](./aws-s3-bucket-tags-remediation-tf-outcome.png) + +**Remediation in CLI** + +You can select the *CLI* option from the **Remediation Steps** dropdown to view the required CLI commands. + +![AWS > S3 > Bucket > Tag > CLI Remediation](./aws-s3-bucket-tags-remediation-cli-outcome.png) + +> [!NOTE] +> The output is generated by the AI provider and may vary based on the model's capabilities and input details. + +## Step 3: Check Quick Action + +`Quick Actions` provide an option to perform one-time control enforcements directly within your cloud environment. When enabled for any control, these actions appear in the remediation panel alongside the detailed remediation steps. + +Check [Quick Actions](/guardrails/docs/guides/using-guardrails/quick-actions#enabling-quick-actions) for more details on enabling it. + +![Quick Action for S3 Bucket Tags Remediation](./aws-s3-bucket-tags-remediation-quick-action.png) + +> [!NOTE] +> [Quick Actions](/guardrails/docs/guides/using-guardrails/quick-actions#enabling-quick-actions) are available for select controls and provide a fast, automated way to remediate common issues. Always review each action before applying it to ensure it aligns with your compliance requirements. + +## Next Steps + +To explore more Guardrails features: + +- [Intelligent Assessment Control](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) +- [Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary) +- [Configure Guardrails MCP Server](/guardrails/docs/guides/using-guardrails/ai/install-mcp) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/turbot-ai-intelligent-fixes-enabled.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/turbot-ai-intelligent-fixes-enabled.png new file mode 100644 index 00000000..fed04743 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/turbot-ai-intelligent-fixes-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/index.md b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/index.md new file mode 100644 index 00000000..8b7dcdf8 --- /dev/null +++ b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/index.md @@ -0,0 +1,66 @@ +--- +title: Enable Policy Pack Summary +sidebar_label: Enable Policy Pack Summary +--- + +# Enable Policy Pack Summary + +In this guide, you will learn how to: + +- Enable and configure the Policy Pack Summary feature. +- View AI-generated summaries of policy pack configurations and purposes. + +The AI-powered `Policy Pack Summary` feature provides contextual insights by analyzing policy pack configurations to generate meaningful summaries. These summaries help teams understand the intent and impact of policies, including key policy settings, dependencies, and their business context. + +> [!TIP] +> Use the policy pack summary to: +> - Validate policy pack configurations. +> - Document your governance approach. +> - Understand how to use these summaries for better policy management and team collaboration. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Ensure that [Turbot > AI > Configuration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) is set up. + +## Step 1: Enable Policy Pack Summary + +In the **Policies** tab, navigate to `Turbot > AI > Policy Pack` and select **Summary**. + +![Navigate to Policy Pack Summary](./turbot-ai-policy-pack-summary.png) + +Select **Enabled** and create a new setting by selecting **New Policy Setting**. + +![Policy Pack Summary Enabled](./turbot-ai-policy-pack-summary-enabled.png) + +> [!NOTE] +> - The default value is `Disabled`. You can enable it based on your requirements. +> - If enabled at the Turbot level in [Turbot AI Configuration > Step 7](/guardrails/docs/guides/using-guardrails/ai/ai-configuration#step-7-enable-configuration), the Intelligent Assessment control becomes available for use. + +For this guide, the `Turbot > AI > Policy Pack > Summary > Enabled` policy is set to `Enabled`. + +## Step 2: Check Policy Pack Summary + +To check the policy pack summary, navigate to the **Policy Packs** section of the **Policies** tab. Select any policy pack to view its summary. + +![Policy Pack Summary](./turbot-ai-policy-pack-summary-response.png) + +> [!NOTE] +> The output is generated by the AI provider and may vary based on the model's capabilities and input details. + +## Next Steps + +To explore more Guardrails features: + +- [Intelligent Assessment Control](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) +- [Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes) +- [Configure Guardrails MCP Server](/guardrails/docs/guides/using-guardrails/ai/install-mcp) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-enabled.png b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-enabled.png new file mode 100644 index 00000000..e7e2ca50 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-response.png b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-response.png new file mode 100644 index 00000000..a7010ddf Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-response.png differ diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary.png b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary.png new file mode 100644 index 00000000..1f9ac28c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary.png differ diff --git a/docs/guides/using-guardrails/ai/index.md b/docs/guides/using-guardrails/ai/index.md new file mode 100644 index 00000000..2cf1f199 --- /dev/null +++ b/docs/guides/using-guardrails/ai/index.md @@ -0,0 +1,15 @@ +--- +title: AI Features +sidebar_label: AI Features +--- + +# Guardrail AI + +This section covers the various AI-powered features available in Guardrails. + +| Section | Description +| - | - +| [AI API Integration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) | How to configure AI settings and preferences within Guardrails. +| [Enable Intelligent Assessment](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) | Learn about AI-powered controls using natural language prompts to evaluate cloud resource compliances. +| [Enable Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes) | Learn about AI-assisted remediation recommendations. +| [Enable Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary) | Learn about AI-generated summaries of policy packs. diff --git a/docs/guides/using-guardrails/index.md b/docs/guides/using-guardrails/index.md index 2dd76510..4d6c7908 100644 --- a/docs/guides/using-guardrails/index.md +++ b/docs/guides/using-guardrails/index.md @@ -8,14 +8,12 @@ This section provides how-to guides for common tasks. | Section | Description | - | - -| [AI Tools](guides/using-guardrails/ai-tools) | Learn how to use different AI integration tools and prompts +| [AI](guides/using-guardrails/ai) | Learn AI-powered capabilities like intelligent assessment, fixes, policy pack summaries of cloud resources | [Console](guides/console) | Navigate the Guardrails Console user interface -| [GraphQL](guides/graphql) | Tips and Tricks for GraphQL | [IAM](guides/iam) | Manage directories, users, and permissions | [Stacks](guides/using-guardrails/stacks) | Manage resource configurations using OpenTofu, an open-source implementation of Terraform | [Notifications](guides/using-guardrails/notifications) | Manage real-time alerts to be sent about events that occur in your cloud infrastructure | [Scheduling](guides/using-guardrails/scheduling) | Manage resource start and stop using custom tags -| [Nunjucks](guides/nunjucks) | Tips and tricks for using Nunjucks, including troubleshooting | [Quick Actions](guides/quick-actions) | Configuration options for Quick Actions | [Searching and Filtering](guides/searching-filtering) | Getting started with Filters in Guardrails | [Troubleshooting](/guardrails/docs/guides/using-guardrails/troubleshooting) | Learn how to troubleshoot and resolve common issues when using Guardrails. diff --git a/docs/index.md b/docs/index.md index 389e21bd..0c35512d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,3 +16,6 @@ Turbot Guardrails is a full-stack governance platform that automates discovery a | [Reference](/guardrails/docs/reference/) | Reference documentation for the API, CLI, Terraform provider, and more. | [Guides](/guardrails/docs/guides/) | Step-by-step guides for using, configuring, and hosting Guardrails. | [Frequently Asked Questions](/guardrails/docs/faq/) | Answers to our most common questions. +| [Developer Guide](/guardrails/docs/developers/) | Learn how to develop guardrails for Guardrails. + + diff --git a/docs/sidebar.json b/docs/sidebar.json index 965c00b8..9ff2666d 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -124,6 +124,7 @@ "concepts/guardrails/discovery", "concepts/guardrails/encryption-at-rest", "concepts/guardrails/encryption-in-transit", + "concepts/guardrails/intelligent-assessment", "concepts/guardrails/public-access", "concepts/guardrails/scheduling", "concepts/guardrails/stacks", @@ -295,7 +296,10 @@ "id": "using-guardrails", "link": "guides/using-guardrails", "items": [ - "guides/using-guardrails/ai-tools", + { + "type": "placeholder", + "file": "guides/using-guardrails/ai/ai-sidebar.json" + }, { "type": "category", "id": "console", @@ -313,7 +317,6 @@ "guides/using-guardrails/console/detail-pages" ] }, - "guides/using-guardrails/graphql", { "type": "category", "id": "iam", @@ -347,7 +350,6 @@ "guides/using-guardrails/scheduling/db-scheduling-using-custom-tag" ] }, - "guides/using-guardrails/nunjucks", "guides/using-guardrails/quick-actions", "guides/using-guardrails/searching-filtering", { @@ -357,7 +359,6 @@ "items": [ "guides/using-guardrails/troubleshooting/fix-invalid-controls", "guides/using-guardrails/troubleshooting/access-control-logs", - "guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors", "guides/using-guardrails/troubleshooting/run-controls-using-scripts" ] } @@ -422,10 +423,13 @@ "guides/hosting-guardrails/updating-stacks/update-ted", "guides/hosting-guardrails/updating-stacks/update-workspace", "guides/hosting-guardrails/updating-stacks/domain-update", - "guides/hosting-guardrails/updating-stacks/general-purpose-gp3" + "guides/hosting-guardrails/updating-stacks/general-purpose-gp3", + "guides/hosting-guardrails/updating-stacks/upgrade-to-valkey-cache", + "guides/hosting-guardrails/updating-stacks/update-pgbouncer" ] }, "guides/hosting-guardrails/FAQ", + { "type": "category", "id": "troubleshooting", @@ -490,6 +494,10 @@ "faq/guardrails-and-aws-scps" ] }, + { + "type": "placeholder", + "file": "developers/developers-sidebar.json" + }, { "type": "category", "id": "reference",