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.
info
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
Log in to your Cyral control plane as an administrator
Go to Sidecars and click the ➕ (plus sign) to create a new sidecar.
Choose Deploy a sidecar using a single container.
Click Generate.
Enter a Sidecar Name for the sidecar. This is the name your administrators will use when they associate this sidecar with repositories.
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
| Setting | Required? | Description |
|---|---|---|
CYRAL_SIDECAR_ID | Required. | Unique id of this sidecar. Provided by the Create sidecar window. |
CYRAL_SIDECAR_CLIENT_ID | Required. | Provided by the Create sidecar window. |
CYRAL_SIDECAR_CLIENT_SECRET | Required. | Secret value used to prove this sidecar's identity in control plane communication. Provided by the Create sidecar window. |
CYRAL_CONTROL_PLANE | Required. | URL of the Cyral control plane. |
CYRAL_SIDECAR_ENDPOINT | Required. | This is the externally visible DNS Name of the sidecar load balancer. This establishes the address where data users will connect. |
Optional settings
| Setting | Required? | Description |
|---|---|---|
CYRAL_REPOSITORIES_SUPPORTED | Optional. | 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_ID | Optional. | Unique ID for this sidecar instance. This defaults to a randomly assigned alphanumeric string. |
CYRAL_MONGODB_PORT_ALLOC_RANGE_LOW | Optional. | The smallest port number that will be allocated for traffic to MongoDB repositories. |
CYRAL_MONGODB_PORT_ALLOC_RANGE_HIGH | Optional. | The largest port number that will be allocated for traffic to MongoDB repositories |
CYRAL_CONTROL_PLANE_GRPC_PORT | Optional. | GRPC port of the Cyral control plane. Defaults to 9080. |
CYRAL_CONTROL_PLANE_HTTPS_PORT | Optional. | HTTPS port of the Cyral control plane. Defaults to 8000. |
CYRAL_CERTIFICATE_MANAGER_SELFSIGNED_SECRET_TYPE | Optional. | 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_ID | Depends on config. | Required if the sidecar is not using a self-signed certificate. |
CYRAL_HCVAULT_ENABLED | Optional. | Indicates whether this sidecar will load secrets from Hashicorp Vault. Defaults to false. The following settings are also required if you enable Hashicorp Vault support: CYRAL_HCVAULT_INTEGRATION_ID, CYRAL_PULL_SIDECAR_CERTIFICATES_FROM_HCVAULT, CYRAL_HCVAULT_SIDECAR_CERTIFICATE_CHAIN, CYRAL_HCVAULT_SIDECAR_SERVER_CERTIFICATE, CYRAL_HCVAULT_SIDECAR_CERTIFICATE_PRIVATE_KEY, CYRAL_HCVAULT_SIDECAR_DNS_COMMON_NAME. |
CYRAL_MYSQL_MULTIPLEXED_PORT | Optional. | 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_PORTS | Optional. | Comma-separated list of TLS ports that will be TLS-terminated by your environment's load balancer, rather than the sidecar. |
CYRAL_SSO_LOGIN_URL | Optional. | URL for Snowflake SSO connections. See the Cyral support article, https://cyral.freshdesk.com/a/solutions/articles/44002159876 . This setting holds the Identity provider single sign-on URL of the SAML app. |
CYRAL_SIDECAR_IDP_PUBLIC_CERT | Optional. | For Snowflake SSO only. This setting holds the X.509 certificate of the SAML app, formatted as a single line. |
CYRAL_SIDECAR_IDP_PRIVATE_KEY | Optional. | |
CYRAL_IDP_CERTIFICATE | Optional. |
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.
tip
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 8888 of the sidecar host.
Check the sidecar's status
Log in to your control plane.
Navigate to the Sidecars link on the left menu.
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.
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.
note
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:
Track a repository to the Cyral control plane, including any identity provider integrations and identity mappings. See the quickstart section for more information.
Assign the repository to the Cyral sidecar.
Configure your application to connect through the Cyral sidecar.