Audience and supported versions

These steps cover the upgrade from Cyral version 2.17.1 or later to subsequent Cyral versions. Earlier versions do not offer the Clone button to assist with sidecar upgrade. For upgrades from earlier versions, contact Cyral support for help getting your sidecar templates.

For an introduction to Cyral version compatibility and upgrades, see Sidecar upgrades and control plane upgrades.

Overview

Cyral offers a sidecar clone option that allows you to make a copy of an existing sidecar that retains your existing sidecar's repository bindings. You can use the clone feature to perform a parallel, or blue-green style upgrade. This upgrade approach is suitable if your deployment includes applications that are not tolerant to network/database disconnections, or you need to phase the traffic migration. This approach allows you to migrate these connections in a controlled way (for example, by restarting the application once the upgraded sidecar is running).

When you perform a parallel upgrade, you create a duplicate sidecar with the same settings as the original sidecar and, you update your CNAME record for the new sidecar so that each new repository connection will use the new sidecar. After the CNAME switch, any existing connections via the old sidecar will continue to be served by the old sidecar. Once all connections have moved over (either naturally or by manually restarting your applications), you can remove the old sidecar.

Figure 1: A parallel upgrade allows the old sidecar to continue serving existing connections while the new, cloned sidecar handles all new connections.

Upgrade your sidecars

Procedure

You will clone each sidecar and deploy it using your cloud platform's upgrade commands.

1. In the Cyral control plane UI, click Sidecars and click the name of the sidecar you want to upgrade.

2. Click Clone. 

3. In the Select a deployment method drop-down, choose your cloud deployment method.

4. In the Clone Sidecar window, depending on the method you choose, method-specific fields appear. Below, we show an example for the Terraform deployment method.

The values you must supply are:

• Sidecar name: The name of this clone. Use a name different from that of the sidecar you're cloning. 

• Log Integration name: Name of your logging service, as set up in the Integrations panel of Cyral

• Metrics Integration name: Name of your metrics service, as set up in the Integrations panel of Cyral

• Depending on your deployment method, there may be more parameters, such as AWS Region, AWS key pair name, AWS VPC ID, and Subnet IDs (this last parameter is a comma-separated list of subnets, one per AWS Availability Zone, to ensure high availability of the sidecar in your AWS VPC).

5. Click Generate. Two things happen:

   • Cyral creates a new sidecar record for your clone (visible in the Sidecars page)

   • Cyral generates the deployment command and deployment template for your cloned sidecar.
      
     Note! If you're upgrading sidecars from version 2.23.4 or earlier, see Cyral sidecar upgrade to version 2.23.5 or later and make the template changes explained there before you run the upgrade.
      
     

6. Install the cloned sidecar by running your cloud platform's deployment command, shown in the Cyral UI. 

   • For Cloudformation, use the commands displayed in the Cyral UI.

   • For Terraform, run terraform init -upgrade and then terraform apply.

   • For Helm 3, to upgrade to Cyral 2.20 or later, use the 

     helm upgrade

     command, where SIDECAR_K8_ID is the name created automatically for both release and namespace names when you originally downloaded the sidecar, FILENAME.yaml is the name of your downloaded config file, and VERSION is the Cyral version you want to upgrade to, such as "2.20.0". Contact Cyral support to get the latest version number.

                                   helm upgrade -i SIDECAR_K8_ID cyral-sidecar --namespace SIDECAR_K8_ID -f FILENAME.yaml --repo https://charts.cyral.com --version VERSION
                                 

     
     

     
     

   • For Helm 3, to upgrade to Cyral 2.19 or earlier, use the helm upgrade command.

7. Using the sidecar endpoint address (the address where repository users connect to the sidecar), you can optionally connect and confirm that traffic is accepted and routed to your database(s). To find the sidecar endpoint address, open the Cyral control plane UI, click Sidecars: Data Repositories and then click the name of your repository. You'll see the address in the Sidecar endpoint column.

8. Update your sidecar's domain alias to direct all new connections to your new, cloned sidecar. See Add a CNAME or A record for the sidecar. With this in place, new requests are routed to your new sidecar.

9. At this point, the old sidecar continues to handle existing connections. Once these connections have terminated naturally, you can:

   • uninstall the sidecar and 

   • remove its sidecar record from Cyral by finding its name in the Sidecars tab of the Cyral control plane UI, clicking Edit: Delete and typing its name to confirm.

See also

Rolling sidecar upgrade