Skip to main content
Version: v4.17

Upgrade procedures for sidecars below v4.10

If you have an existing sidecar running on any prior version to v4.10, use the instructions on this page to successfully upgrade your sidecar.

CloudFormation​

The CloudFormation template is now open source, meaning that it is not necessary to re-download it from the control plane on every sidecar upgrade.

In order to upgrade an existing sidecar v4.9 or older, use the cft_sidecar.yaml file available in our CloudFormation AWS EC2 repository.

For new CloudFormation sidecars, use the quick start guide for CloudFormation AWS EC2 and follow the instructions in the upgrade procedures page.

Configuring the template parameters​

A few template parameters changed from the previous version of the template that was downloaded from the control plane. When upgrading an existing sidecar, the parameters you need to configure are:

  • SidecarVersion: for the first upgrade coming from a version prior to v4.10.0 to any version v4.10.0 or later, it is required that you explicitly assign the target version in SidecarVersion. Once you upgrade the sidecar to v4.10.0 or later and at least one instance shows up green in the Sidecar Instances tab in the control plane, you may proceed to use the 1-click upgrade by setting SidecarVersion to an empty string.
  • ContainerRegistry: use Cyral's public container registry by setting it to public.ecr.aws/cyral. The previous container registry in gcr.io is deprecated.
  • ContainerRegistryKey: set it to an empty string.
  • ContainerRegistryUsername: set it to an empty string.

Datadog Metrics Support​

In case your existing sidecar exports metrics to Datadog, use the following snippet to inject a Datadog agent container onto the sidecar EC2 instances, with identical behavior to how the included Datadog agent worked for sidecars < v4.10:

export DD_API_KEY=<YOUR DATADOG API KEY> ; echo "init_config:\ninstances:\n    - prometheus_url: http://localhost:${METRICS_PORT:-9000}/metrics\n      namespace: \"cyral\"\n      metrics:\n        - go*\n        - cyral*\n        - node*\n        - up\n      prometheus_metrics_prefix: prom_\n      health_service_check: true\n      send_distribution_buckets: true\n      send_histograms_buckets: true" > conf.yaml ; sudo docker run -d --restart always --network host --name datadog -v $(pwd)/conf.yaml:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml -e DD_API_KEY=${DD_API_KEY} --log-driver json-file --log-opt max-file=5 --log-opt max-size=10m --log-opt tag="containerName=\"{{.Name}}\"" gcr.io/datadoghq/agent:7.34.0

Simply replace <YOUR DATADOG API KEY> in the code snippet above with your actual Datadog API key you wish to use. Then use the modified snippet as the value for the CFT parameter CustomUserDataPost.

Terraform​

Sidecars v4.10 require version v4.3.0 or later of our Cyral Sidecar module for AWS EC2. We recommend you to use the pessimistic version constraint operator (~>) to allow Terraform to always use the latest version v4.x.y available as follows:

module "cyral_sidecar" {
  source  = "cyralinc/sidecar-ec2/aws"  
  version = "~> 4.0" # terraform module version
  ...
}

When upgrading an existing sidecar, the parameters you need to configure are:

  • sidecar_version: for the first upgrade coming from a version prior to v4.10.0 to any version v4.10.0 or later, it is required that you explicitly assign the target version in sidecar_version. Once you upgrade the sidecar to v4.10.0 or later and at least one instance shows up green in the Sidecar Instances tab in the control plane, you may proceed to use the 1-click upgrade by setting sidecar_version to an empty string or completely removing this parameter from the module call and re-applying it.
  • container_registry: use Cyral's public container registry by setting it to public.ecr.aws/cyral. The previous container registry in gcr.io is deprecated.
  • container_registry_key: set it to an empty string.
  • container_registry_username: set it to an empty string.

Datadog Metrics Support​

In case your existing sidecar exports metrics to Datadog, use the following snippet to inject a Datadog agent container onto the sidecar EC2 instances, with identical behavior to how the included Datadog agent worked for sidecars < v4.10:

export DD_API_KEY=<YOUR DATADOG API KEY> ; echo "init_config:\ninstances:\n    - prometheus_url: http://localhost:${METRICS_PORT:-9000}/metrics\n      namespace: \"cyral\"\n      metrics:\n        - go*\n        - cyral*\n        - node*\n        - up\n      prometheus_metrics_prefix: prom_\n      health_service_check: true\n      send_distribution_buckets: true\n      send_histograms_buckets: true" > conf.yaml ; sudo docker run -d --restart always --network host --name datadog -v $(pwd)/conf.yaml:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml -e DD_API_KEY=${DD_API_KEY} --log-driver json-file --log-opt max-file=5 --log-opt max-size=10m --log-opt tag="containerName=\"{{.Name}}\"" gcr.io/datadoghq/agent:7.34.0

Simply replace <YOUR DATADOG API KEY> in the code snippet above with your actual Datadog API key you wish to use. Then use the modified snippet as the value for the parameter custom_user_data using the following format:

{"pre": "", "pre_sidecar_start": "", "post": "<CODE SNIPPET HERE>"}

Helm​

Follow the upgrade procedure in the Helm sidecar quick start.

Linux​

Follow the upgrade procedure in the Linux sidecar quick start.