Skip to main content
Version: v4.8

Install a sidecar as a single container

The single container sidecar is ideal for quick setups or to be run on containerization platforms that we don't currently have configuration for. It is important to keep in mind that there are scenarios where it's possible that the entire container crashes, preventing fail-to-wire from working, however these situations should be rare.

If you are a Terraform user and want to deploy a sidecar on AWS ECS, you can follow our Cyral Sidecar ECS deployment guide to learn how to deploy a sidecar as a single container on ECS in just a few minutes using Terraform.

If you don't use Terraform, you can follow the steps in this section.

Required components

  • Containerization platform
  • Cyral sidecar container image
  • Network connectivity must exist between the sidecar container and your data repository hosts and ports.

A note on running multiple nodes of one sidecar, or multiple sidecars:

The installation steps on this page should be performed on any host that will be running a sidecar. Take care to note the difference between multiple instances of a sidecar vs. multiple sidecars:

  • If multiple hosts will be configured as instances of the same sidecar, then repeat the installation procedure using the settings you got in the steps above.

  • If you are planning to have each host operate as an individual sidecar (each with its own configuration in the Cyral control plane), then you will also need to repeat the steps above to get a unique Sidecar ID, Client ID, and Client Secret for each host.

Get the sidecar installation values

  1. Log in to your Cyral control plane as an administrator

  2. Go to Sidecars and click the ➕ (plus sign) to create a new sidecar.

  3. Choose Deploy a sidecar using a single container.

  4. Click Generate.

  5. Enter a Sidecar Name for the sidecar. This is the name your administrators will use when they associate this sidecar with repositories.

  6. Click Generate again. The Generate sidecar window provides the information you need in order to deploy this sidecar as a container:

    • Docker registry access string
    • Variable settings for deploying your sidecar
    • Sidecar image address

    Keep this window open and proceed to the next section.

Configure your container registry

In the preceding step, the Generate sidecar window provided Docker registry access string. Use that string to configure your container registry. Then proceed to the next section.

Make sidecar settings

In your containerization environment, specify your sidecar settings as environment variables to the container. These settings specify the identity of the sidecar, secure its communications, and determine its operating options. You must set at least the parameters from the required settings list below.

Required settings

CYRAL_SIDECAR_IDRequired.Unique id of this sidecar. Provided by the Create sidecar window.
CYRAL_SIDECAR_CLIENT_IDRequired.Provided by the Create sidecar window.
CYRAL_SIDECAR_CLIENT_SECRETRequired.Secret value used to prove this sidecar's identity in control plane communication. Provided by the Create sidecar window.
CYRAL_CONTROL_PLANERequired.URL of the Cyral control plane.
CYRAL_SIDECAR_ENDPOINTRequired.This is the externally visible DNS Name of the sidecar load balancer. This establishes the address where data users will connect.

Optional settings

CYRAL_REPOSITORIES_SUPPORTEDOptional.Omit this setting to enable all repository types. To enable only a subset of repository types, set this to a comma-separated list of the desired types. The valid types are mysql, postgresql, mongodb, dremio, sqlserver, oracle, s3, rest, snowflake, dynamodb, redshift, denodo.
CYRAL_SIDECAR_INSTANCE_IDOptional.Unique ID for this sidecar instance. This defaults to a randomly assigned alphanumeric string.
CYRAL_CONTROL_PLANE_GRPC_PORTOptional.GRPC port of the Cyral control plane. Defaults to 443.
CYRAL_CONTROL_PLANE_HTTPS_PORTOptional.HTTPS port of the Cyral control plane. Defaults to 443.
CYRAL_CERTIFICATE_MANAGER_SELFSIGNED_SECRET_TYPEOptional.Indicates whether this sidecar uses a self-signed certificate. Defaults to "self". Can be set to one of: self, aws, k8s.
CYRAL_CERTIFICATE_MANAGER_SELFSIGNED_SECRET_IDDepends on config.Required if the sidecar is not using a self-signed certificate.
CYRAL_MYSQL_MULTIPLEXED_PORTOptional.This is the port number of the multiplexed port used for MySQL requests. Defaults to 0. Note that the port number you use as the multiplexed port becomes unavailable for any other repository binding.
CYRAL_LOAD_BALANCER_TLS_PORTSOptional.Comma-separated list of TLS ports that will be TLS-terminated by your environment's load balancer, rather than the sidecar.
CYRAL_SSO_LOGIN_URLOptional.URL for Snowflake SSO connections. See the Cyral support article, . This setting holds the Identity provider single sign-on URL of the SAML app.
CYRAL_SIDECAR_IDP_PUBLIC_CERTOptional.For Snowflake SSO only. This setting holds the X.509 certificate of the SAML app, formatted as a single line.

Once you've made the needed settings, proceed to the next section.

Deploy your sidecar container

Earlier, the Generate sidecar window provided a sidecar image address. Use this address to deploy the container now.


Make sure that each sidecar exposes one or more ports that data users connect to. We refer to these as the sidecar's bound ports. Make sure all bound ports are exposed on your container so that the sidecar instance can be accessed.

Your sidecar should now be running and reachable. See the logging section below for help finding its logs.

Check your installation

Perform the following steps to confirm your sidecar has been installed correctly.

Check connectivity

Run a TCP health check probe on port 9000 of the sidecar host.

Check the sidecar's status

  1. Log in to your control plane.

  2. Navigate to the Sidecars link on the left menu.

  3. Check the sidecar: Identify the sidecar you just installed from the list and open it.

    Confirm that the sidecar is shown in the list with a green checkmark. If a green checkmark does not appear, check the sidecar's metrics and logs.

  4. Check each sidecar instance: Click on the sidecar's name and go to the Instances tab.

    Confirm that the sidecar instance is shown with a green icon. If a green icon does not appear, check the sidecar's metrics and logs.


Each sidecar instance can be identified by its IP address. Depending on the local IP address of the server, this might be a private IP address.

Check repository access via the sidecar

Check that the sidecar is operational by verifying that it can handle database requests:

  1. Track a repository to the Cyral control plane, including any identity provider integrations and access rules. See the quickstart section for more information.

  2. Assign the repository to the Cyral sidecar.

  3. Configure your application to connect through the Cyral sidecar.