Skip to main content
Version: v4.8

Manage sidecars

Check and manage the health and availability of Cyral sidecar clusters and instances.

Check sidecar cluster status

Click the Sidecars tab to display a list of sidecars.



In the main Sidecars list, each row provides a summary of a sidecar cluster:

  • The leftmost column provides a registration/health summary indicator icon. This icon shows:
IconDetails
Icon showing a checkmark on green backgroundSidecar is registered, and all its instances are fully healthy.
Icon showing an exclamation point on a yellow triangleSidecar is registered, but not all sidecar instances are fully healthy. Some sidecar services may be down.
Icon showing an exclamation mark on a red circleSidecar has been registered, but none of its instances are fully healthy, or the sidecar is not reachable now.
Icon showing a horizontal line on a grey circleMetrics cannot be found for this sidecar. This status might indicate that someone has created the sidecar in the Cyral UI but has not deployed the sidecar, or that the Cyral control plane's sidecar monitoring service is not operating.
  • Name is the name you gave to this sidecar cluster
  • Tags are tags that you or your deployment framework have applied to identify this sidecar cluster
  • Platform is the cloud platform that hosts this sidecar cluster
  • Active Instances shows how many sidecar instances in this sidecar cluster are active and able to serve requests.
  • Data Repositories shows how many data repositories this sidecar cluster protects. Click on the row and then click Data Repositories to list them.
  • Passthrough shows a checkmark if this sidecar cluster is running in passthrough mode, meaning that it allows all requests to be served without policy enforcement, logging, or other Cyral services.

Check sidecar instance status

Usually a Cyral sidecar runs as an autoscaling cluster on your cloud platform. After you've checked the sidecar cluster status, you can check the status of individual sidecar instances in the sidecar cluster.


 

To check the status of individual sidecar instances in the sidecar cluster, click Sidecars: click the name of your sidecar, and click Instances. For each instance, the UI shows:

  • Health: A sidecar instance is fully operational when all of its services are healthy.
    • green: All of this instance's services are healthy
    • yellow: Some but not all of this instance's services are healthy
    • red: None of this instance's services are healthy
  • Instance ID: Number that identifies this sidecar instance
  • Sidecar version: Cyral version number of this sidecar instance
  • Age: Time since this sidecar was deployed or upgraded

Manage sidecar services for repositories

How to check and manage Cyral sidecar services for your repositories.

Show repositories bound to a sidecar

To list the data repositories bound to a sidecar, click Sidecars ➡️ click the name of your sidecar ➡️ Data Repositories. For each bound repository, the table shows:

  • Type indicates the repository with an icon to represent, for example, PostgreSQL or MongoDB.

  • Name is the name you gave to this data repository in Cyral.

  • Port is the port where users can connect to this repository through this sidecar (using the sidecar endpoint address).

    For a MongoDB replica set, only the first port number in the set is shown. Click the three-dots icon at the right to open the Edit Binding window where you'll see the full set of ports.

    Port numbers labelled SMART PORT are Cyral Smart Ports that can serve multiple repositories.

  • Binding status shows as ENABLED for a repository whose sidecar binding is turned on, meaning data users can reach the repository through the sidecar. A DISABLED icon indicates the binding has been turned off, in which case the sidecar does not allow connections to the repository.

    To enable or disable a repository's binding, see Enable or disable a repository binding.

Passthrough mode

Cyral sidecars can be run in passthrough mode to help troubleshoot performance problems, or better onboard new applications before turning on analysis.

In passthrough mode, the sidecar acts as a layer-4 load balancer and forwards all requests through to the repositories bound to it. In passthrough mode, the Cyral sidecar provides:

  • no SSO authentication; instead, data users must use their native repository credentials to connect through the sidecar.
  • no policy enforcement
  • no logging or alerting
tip
  1. Don't confuse passthrough mode with turning off all sidecar services for a repository. See Turn sidecar coverage on or off for a repository.
  2. Don't confuse passthrough mode with the Enter passthrough mode on failure option. Turning on Passthrough mode puts the sidecar immediately into a mode that forwards all requests. Turning on Enter passthrough mode on failure allows the sidecar to start forwarding all requests only when a sidecar failure happens.

Put a sidecar in passthrough mode

  1. Click Sidecars and click the name of your sidecar.
  2. Click the Advanced tab.
  3. Turn on the Passthrough mode toggle.
  4. Click Save.

Check whether a sidecar is in passthrough mode

To check whether a sidecar is running in passthrough mode, click the Sidecars tab in the Cyral control plane UI and find your sidecar in the list. The Passthrough column shows a checkmark if the sidecar is running in passthrough mode.

Resilient mode of sidecar operation

The Resiliency to sidecar errors mode preserves uninterrupted access to data by maintaining database connections, even if a partial software failure happens in the sidecar. When you install a sidecar, this feature is turned ON by default.

info

Resiliency mode is not intended to help in cases of the complete loss of a sidecar instance (for example due to hardware failure). In such cases, existing database connections are broken, but a new connection attempt will usually succeed because of the presence of other sidecar instances in the sidecar cluster.

When to use resiliency mode:

  • To ensure that logging and policy enforcement are always done, turn resiliency mode OFF.
  • To minimize interruptions to database connections, leave resiliency mode ON.

This toggle has the following effects:

  • With Resiliency to sidecar errors turned OFF, a partial sidecar failure affecting a database connection will force that connection to close immediately. The user will be able to reconnect after the sidecar’s services are restored.

  • With Resiliency to sidecar errors turned ON,

    • a partial sidecar failure affecting a database connection will not interrupt the connection,

    • Cyral’s logging and policy enforcement for the connection will stop until the user disconnects and reconnects.

      note

      Once a sidecar has failed over into resiliency mode, each of its running database connections will continue to operate in that mode until the connection is closed. Once a client disconnects and reconnects, it will get the latest preferred connection mode of the sidecar (typically a normal connection with policy enforcement and logging enabled).

Enable resiliency to sidecar errors for a given sidecar

  1. Click Sidecars and click the name of your sidecar.
  2. Click the Advanced tab.
  3. Turn on the Enable resiliency to sidecar errors toggle.
  4. Click Save.

Endpoint Alias

To provide a stable address on the network where users can always reach their repositories, add an endpoint alias address for the sidecar.

tip

Adding an endpoint alias requires that you first set up this alias in your network routing service using a CNAME or A record, as explained in Add a CNAME or A record for the sidecar.

Once your network routing service has been set up to route the alias you intend to use, you can add the Endpoint Alias in Cyral as follows:

  1. Navigate to Sidecars: click your sidecar's name, and click Edit.
  2. In the Edit Sidecar window, click the Endpoint Alias checkbox.
  3. In the field that appears, type the alias. This must be a valid domain name that can be routed on your network, such as db-access.example.com. This address will resolve to the sidecar load balancer address, giving your data users access to the repositories protected by the sidecar.
  4. Click Save.

Sidecar Tags

To add a tag that will help you identify a sidecar, follow these steps:

  1. Click Sidecars in the Cyral control plane UI, click your sidecar's name, and click Edit.
  2. In the Edit Sidecar window, type each tag in the Add Tags field and press enter to save it.
  3. Click Save.

Disable sidecar coverage for a repository

See Turn sidecar coverage on or off for a repository.

Check the state of sidecar services for a repository

To check whether a repository is being protected by a sidecar, follow these steps:

  1. In the Cyral management console, click Data Repos and click the name of your repository in the list. In the SIDECARS section, note the name of the sidecar through which users connect. (There may be more than one sidecar for the repository.)
  2. Click Sidecars in the menu on the left. Find the sidecar whose name you just noted, using the Search tool if needed. Check the following:
    • A green checkmark icon should appear on the left. If any other icon is shown here, click the name of the sidecar and click the Instances tab to investigate.
    • The status should be shown as Active. If any other status is shown here, click the name of the sidecar and click Edit. Passthrough mode may have been enabled. See Passthrough mode.
       

  3. Check whether sidecar coverage is on:
    • Click the name of your sidecar. The Sidecar Details page appears.
    • In the Repositories tab, find your repository in the list.
    • Make sure the Binding Status shows ENABLED. If it does not, someone may have disabled sidecar coverage for this repository. See Turn sidecar coverage on or off for a repository.
  4. Check that you've turned on all the desired services in your sidecar's configuration settings.

Troubleshoot sidecar performance

If some queries are not being analyzed or if a sidecar becomes nonresponsive, see Sidecar system metrics for help troubleshooting.

Delete a sidecar

Follow these steps to delete a sidecar:

  1. If the sidecar you're planning to delete is currently protecting repositories, move those repositories to a new sidecar if you wish to continue Cyral services for the repositories. See Unbind a repository from a sidecar
  2. Remove the sidecar from the Cyral control plane inventory. Navigate to Sidecars: click your sidecar's name, and click Edit. In the Edit Sidecar window, click Delete, and click to confirm the deletion.
  3. Deprovision and delete the sidecar cluster and its instances using the commands provided by your cloud platform. See Uninstall a sidecar

See also