diff --git a/docs/guides/hosting-guardrails/installation/install-ted/index.md b/docs/guides/hosting-guardrails/installation/install-ted/index.md index ed0bf505..5b728902 100644 --- a/docs/guides/hosting-guardrails/installation/install-ted/index.md +++ b/docs/guides/hosting-guardrails/installation/install-ted/index.md @@ -123,6 +123,12 @@ 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) +### 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, [here is how to update to Valkey](/docs/guides/hosting-guardrails/updating-stacks/upgrade-to-valkey). + ## 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. 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/updating-stacks/Upgrade-to-valkey/index.md b/docs/guides/hosting-guardrails/updating-stacks/Upgrade-to-valkey/index.md new file mode 100644 index 00000000..016648fc --- /dev/null +++ b/docs/guides/hosting-guardrails/updating-stacks/Upgrade-to-valkey/index.md @@ -0,0 +1,89 @@ +--- + +title: Upgrade to Valkey Cache +sidebar_label: Upgrade to Valkey Cache +-------------------------------------- + +# Upgrade 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 1.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. + +## 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. + +## Step 1: 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 doesn't offer a direct path for migrating from Valkey back to Redis within ElastiCache. The supported migration path is from Redis to Valkey. + +Step 2: Select TED Version + +To begin the upgrade process, you’ll need to locate the TED provisioned product in AWS Service Catalog and initiate an update. + +Follow the initial steps outlined in the Updating TED guide to: +- Access the AWS Service Catalog +- Select the TED provisioned product +- Initiate the Update action + +Once you’ve initiated the update, 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 3: 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 4: Update TED + +After verifying all parameters, scroll down and select **Update**. This initiates an update of several nested CloudFormation stacks, which you can monitor directly from the CloudFormation console. + +![Select Update](./service-catalog-ted-update-action.png) + +## Step 5: Review Deployment + +- [ ] The TED CloudFormation stack status should change to `UPDATE_COMPLETE` indicating the update completed successfully. + +![Update Progress ](./cfn-ted-update-progress.png) + +- [ ] The newly created Valkey caches will be available under `Valkey caches` in the AWS ElastiCache dashboard. + +![Verify Cache](./aws-valkey-cache-complete.png) + +## Step 6: Start Events + +Enable event processing. Refer [Enable the events](/guardrails/docs/guides/hosting-guardrails/troubleshooting/pause-events#enable-event-processing). + +## 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 | 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/index.md b/docs/guides/hosting-guardrails/updating-stacks/index.md index 90118588..01286466 100644 --- a/docs/guides/hosting-guardrails/updating-stacks/index.md +++ b/docs/guides/hosting-guardrails/updating-stacks/index.md @@ -18,5 +18,6 @@ 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) +- [Migrate to Valkey Cache](guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache) 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/migrate-to-valkey-cache/aws-service-catalog-console.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/aws-service-catalog-console.png new file mode 100644 index 00000000..5ce4584b Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/aws-service-catalog-console.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/aws-valkey-cache-complete.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-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/migrate-to-valkey-cache/aws-valkey-cache-complete.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/index.md b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/index.md new file mode 100644 index 00000000..4a03549e --- /dev/null +++ b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/index.md @@ -0,0 +1,91 @@ +--- +title: Migrating to Valkey Cache +sidebar_label: Migrating to Valkey Cache +--- + +# Migrating 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. + +Know 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 doesn't offer a direct path for migrating from Valkey back to Redis within ElastiCache. The supported migration path is from Redis to 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. + +## Step 5: Verify Valkey Cache Deployment + +* [ ] 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: + +* 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 | 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/migrate-to-valkey-cache/service-catalog-actions-update.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-actions-update.png new file mode 100644 index 00000000..c04ec8e7 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-actions-update.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-find-provisioned-product-ted.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-find-provisioned-product-ted.png new file mode 100644 index 00000000..f4a5b66c Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-find-provisioned-product-ted.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-provisioned-products.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-provisioned-products.png new file mode 100644 index 00000000..c6ca61bb Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-provisioned-products.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-select-access-filter.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-select-access-filter.png new file mode 100644 index 00000000..ff45dbe6 Binary files /dev/null and b/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-select-access-filter.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-select-ted-version.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-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/migrate-to-valkey-cache/service-catalog-select-ted-version.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-ted-update-action.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-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/migrate-to-valkey-cache/service-catalog-ted-update-action.png differ diff --git a/docs/guides/hosting-guardrails/updating-stacks/migrate-to-valkey-cache/service-catalog-ted-update-parameters.png b/docs/guides/hosting-guardrails/updating-stacks/migrate-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/migrate-to-valkey-cache/service-catalog-ted-update-parameters.png differ 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..72cffc0d 100644 --- a/docs/guides/hosting-guardrails/updating-stacks/update-ted/index.md +++ b/docs/guides/hosting-guardrails/updating-stacks/update-ted/index.md @@ -88,6 +88,12 @@ The values of the parameters will initially be set to match previous run of the > 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, [here is how to update to Valkey](/docs/guides/hosting-guardrails/updating-stacks/valkey-migration). + ## Step 11: Update TED After verifying any changes to existing parameters, select **Update** at the bottom of the screen. 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/sidebar.json b/docs/sidebar.json index 965c00b8..96a1333f 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -422,7 +422,8 @@ "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/migrate-to-valkey-cache" ] }, "guides/hosting-guardrails/FAQ",