Audience
This document applies to Cyral deployments that protect Snowflake repositories. These steps cover the upgrade from Cyral version 2.15 or earlier to Cyral version 2.16 or later.
Upgrade procedure
Overview
The upgrade has these phases:
Our support team upgrades your Cyral control plane.
Your team upgrades your Okta app that Cyral uses for SSO.
Your team upgrades your sidecars.
If your installation provides SSO for certain repo types, your team will upgrade your SSO credential mappings.
Before you begin
Before you begin, wait for your Cyral support team to upgrade your Cyral control plane. When the control plane is ready, we will share your updated SSO configuration values.
Note: Generally, newer Cyral control planes support their contemporary and older versions of the sidecar, but be aware that when you upgrade to a new version of the control plane, you may need to upgrade your sidecars to use features introduced in the new control plane version.
Upgrade your Okta app
Log into your Okta dashboard in classic mode.
Edit the SAML app you use to provide SSO authentication in Snowflake
Click Next to advance to the SAML Settings: General tab.
Paste the SSO configuration values your Cyral support person provided:
Single sign on URL
Audience URI
Click Advanced Settings and paste the values for:
Single log-out URL
SP issuer
Upload the Signature Certificate.
In the Attribute Statements section, most installations are able to keep their pre-upgrade values. Make sure you have mapped the Attribute Statements as follows: EMAIL maps to "user.email", FIRST_NAME maps to "user.firstName", and LAST_NAME maps to "user.lastName". In the Group Attribute Statements section, for groups, set a regex that returns the names of groups that Okta will share with Cyral. For details, see In Okta, create an app to represent Cyral in the Cyral documentation.
Click Next and click Finish.
Upgrade your sidecars
Follow this procedure to perform a rolling upgrade of a sidecar. Each sidecar in Cyral is actually an autoscaling group of sidecar instances. This upgrade will replace each sidecar instance, one at a time. This is the easiest upgrade method and is suitable when your clients and applications can tolerate and recover from a network disconnection to the database.
Sidecar upgrade instructions for Terraform-based environments
During the sidecar upgrade, the sidecar will be consistently available, but existing data client connections will be broken. To perform a zero-downtime upgrade, contact Cyral support.
Procedure
You will find or generate the deployment template for each sidecar and deploy it using the terraform init -upgrade command.
Get the sidecar deployment template: Either find the template you used to deploy your sidecar, or generate a new, identical one. To generate the template:
Open the Cyral control plane UI, click Sidecars, click Deploying sidecar to AWS EC2 using Terraform, and click Generate Template.
Set the values to match your current sidecar's settings, including:
AWS Region
AWS key pair name
AWS VPC ID
Subnet IDs as a comma-separated list
Log Integration name (the name you gave to your logging integration
Metrics Integration name
Click Generate and download the template.
You control the sequencing of the rolling upgrade by appending the Auto Scaling Group asg_min and asg_max parameters to your template. (For details, see Amazon's ASG documentation). Cyral recommends that you set asg_max to a value that's greater than or equal to (asg_desired + 1). This ensures that at least one new sidecar will be created before old sidecars are removed.
Note! If you set asg_max to the same value as asg_desired, it will cause old sidecars to be removed before their replacements are created. This is not recommended for ensuring uptime.
Upgrade the sidecar, by running:
terraform init -upgrade
terraform apply
The upgrade will only update the EC2 launch configuration which is used when deploying new sidecar instances to the asg. To update the existing sidecar instances, refresh your sidecar's Auto Scaling groups (ASGs) as follows: In your AWS Management Console, under Auto Scaling groups, find the ASG for the sidecar (the name is the first part of the sidecar endpoint, which you can find in the Cyral Control Plane UI). Go to Instance refresh and click Start Instance refresh.
Repeat the above procedure for each sidecar you want to upgrade.
Preparing for higher volume
Optional: If you need to support a higher volume of activity with your sidecar, you can increase the number of sidecar instances in the AWS Auto Scaling group. Edit the deployment template, sidecar.tf. In the module "cyral_sidecar," add the following variable assignments:
asg_min = X
asg_desired = Y
asg_max = Z
Where X is the minimum, Y is the desired, and Z is the maximum number of instances you want to have in the sidecar ASG.
Database credential handling changes for SSO
This section applies to installations that provide SSO authentication.
Note! If your Cyral SSO integration protects only Snowflake repositories, you may skip this section.
In the previous version of the sidecar, the database credentials were put into AWS Secrets Manager in a specific JSON format that included both credentials and group mappings in it. As part of this upgrade, the group mappings are removed from the structure, and the JSON blob in the secrets manager is simplified to be the following:
More details on this can be found in Authenticate repository access with SSO.
Separate secrets must be created for each such database credential JSON blob, and the secret can be placed in the secrets manager at any key location with the prefix /cyral/dbsecrets/.
For each username, create a Local Account under the data repository by providing the ARN of the secret. Below is a screenshot that shows local account creation for “analyst”
Now create a mapping between an SSO group and the local account. This is done in the tab “Identity to Account Map”. Below is a screenshot that shows the SSO group “Data Analysts” being mapped to the local account “analyst”.
After this upgrade, the sidecar no longer needs the AWS secrets manager integration. On the Integrations page, you can delete the integration that you had previously added, as shown in the screenshot below.
