Deploy-It-Yourself: deploying a sidecar to a custom environment
If you have a specific environment or a use case not covered by the
Cyral Quick Start Templates,
you may opt for a dodeploy-it-yourself approach, create your
own deployment template and run our sidecar container in any
containerization platform.
Required components
- Containerization platform.
- Cyral sidecar container.
- Network connectivity from the environment where the sidecar container will be deployed to the Cyral control plane.
- Network connectivity 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.
Access the Deployment tab.
Click Generate Deployment Parameters. The Custom Deployment Parameters window provides the information you need in order to deploy your sidecar container:
- Sidecar ID
- Control plane URL
- Client ID
- Client Secret
Keep this window open and proceed to the next section.
Download the sidecar image
The sidecar image can be downloaded from our public repository. Make sure to use a version that is compatible with your control plane.
The control plane follows semantic versioning and is compatible with
all sidecars that have vX.Y equal or smaller than the control plane
version not considering the patch number. Thus a control plane
v4.10.1 is compatible with sidecars v4.9.0, v4.10.0, v4.10.6,
but not with sidecars v3.2.0 or v4.12.0.
Pull the image from our public registry:
docker pull public.ecr.aws/cyral/cyral-sidecar:<VERSION>
Configure 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, such as mycompany.app.cyral.com |
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_CONTROL_PLANE_GRPC_PORT | Optional. | GRPC port of the Cyral control plane. Defaults to 443. |
CYRAL_CONTROL_PLANE_HTTPS_PORT | Optional. | HTTPS port of the Cyral control plane. Defaults to 443. |
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_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. |
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
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 access rules. See the quickstart section for more information.
Assign the repository to the Cyral sidecar.
Configure your application to connect through the Cyral sidecar.
Logging
All logs are pushed to the stdout stream of the container. There are
two types of logs that will stream out, diagnostic and audit. Audit
logs will have a field activityId that can be used to filter or
redirect where diagnostic logs will have a level and msg field.
Tools like fluent bit can be used to help filter or redirect the logs
to a logging platform.
Removing
To remove just a single instance of this sidecar container, just simply remove the container. If you would like to remove the whole sidecar refer to the Remove sidecar page.