Get Started Sign In

Cyral sidecar upgrade: Parallel upgrade

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.


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


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.

  1. Click Clone

Note! The clone operation copies the existing sidecar's settings and associations at the time of cloning. If you make changes to the original sidecar after it's been cloned, those changes will not be reflected in the clone.

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

  2. 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.

Note! The values you provide here will be reflected in the clone template, but Cyral does not save them for subsequent use. If you return to this window later to clone a template again, you must retype these values.

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. 

Note! You cannot rename sidecars, so this name will remain for the life of the sidecar. This name is not visible to database users; they connect using the sidecar's domain name, which you will set using a CNAME, below.

  • 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 RegionAWS key pair nameAWS 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).

  1. 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.

  2. 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 --version VERSION

    • For Helm 3, to upgrade to Cyral 2.19 or earlier, use the helm upgrade command.
  3. 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.

  4. 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.

  5. 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

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.