Skip to content

Add > Guide > Valkey Migration #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -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) |
1 change: 1 addition & 0 deletions docs/guides/hosting-guardrails/updating-stacks/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
---
title: Migrating to Valkey Cache
sidebar_label: Migrating to Valkey Cache
---

# Migrating to Valkey Cache

<!-- # Migrating ElastiCache for Valkey - Refer https://aws.amazon.com/elasticache/what-is-valkey/-->

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) |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 2 additions & 1 deletion docs/sidebar.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down