Skip to main content
Version: v4.1

Manage sidecar secrets

The Cyral sidecar secrets contain the credentials used to authenticate the sidecar to the Cyral control plane and to download container images in the Cyral container registry. Below, we show how to keep these secrets secure, and how to rotate them.

Keep secrets out of sidecar templates​

By default, for Cloudformation-deployed sidecars and Terraform-deployed sidecars, the sidecar templates control the lifecycle of the sidecar secrets.

The sidecar secrets are represented in the templates by the following variables.

  • For Cloudformation:
    • SidecarClientID
    • SidecarClientSecret
    • ContainerRegistryKey
  • For Terraform:
    • client_id
    • client_secret
    • container_registry_key

All these variables are properly assigned when the sidecar template is downloaded from the control plane, meaning that the template will work out of the box, and the sidecar instances will be able to properly download the necessary container images and also authenticate to the control plane.

If you want to store the template file in a source code repository to have the sidecar deployed by a CI/CD pipeline or simply want to avoid the credentials being shown, for example, in the Terraform state file, then handling the secret outside of the template is the best option. For such situations, we'll outline two options below that allow you to manage the secrets yourself so that you can avoid having your credentials appear in your template files.

Option A: Prevent the sidecar from managing the secret (preferred method)​

With this option you can prevent the sidecar template from handling the secret. You will be in charge of creating the secret and providing the path for the sidecar template so sidecar instances can read it.

Procedure​

  1. Download the sidecar template from the control plane.
  2. Create a new secret entry in AWS Secrets Manager (in case of AWS sidecar template) and add the following keys to the secret (keys are case sensitive), assigning the values found in the downloaded template:
    • clientId: assign value from SidecarClientId or client_id
    • clientSecret: assign value from SidecarClienteSecret or client_secret
    • containerRegistryKey: assign value from ContainerRegistryKey or container_registry_key
  3. Store the secret. You may set your own name for the secret or, for this name, use the value found in the variable SecretsLocation or secrets_location (for CloudFormation and Terraform, respectively). Using the existing name is the preferred method.
  4. In the downloaded template:
    • Remove the values from the credentials variables you copied to the secret in the previous step;
    • Set DeploySecrets or deploy_secrets (for CloudFormation and Terraform, respectively) to false;
    • If you set your own name for the secret created in the previous step, set the variable SecretsLocation or secrets_location to your secret's name.
  5. Deploy the sidecar.

Option B: Let the sidecar manage the secret entry, but using fake credentials​

This option may be useful if you want to manage the secret entry using the sidecar template, but do not want to show the secret in the template file. In this scenario, the sidecar will still deploy the secret entry, but you will be responsible for setting the actual credentials values after the secret entry has been created. In this specific scenario, the sidecar instance will not be online until you set the proper credentials.

Procedure​

  1. Download the sidecar template from the control plane.
  2. Copy the credential variables content from the downloaded template to a secret vault of your choice. After that, set the credential variables in the downloaded template file to any value of your choice.
  3. Deploy the sidecar normally (in case of an AWS sidecar, the auto scaling group will try to spin up new instances and they will not stabilize);
  4. Open the secret entry created by the sidecar. The entry path is indicated by variable SecretsLocation or secrets_location (for CloudFormation and Terraform, respectively). If this is an AWS-deployed sidecar, the entry will be in AWS Secrets Manager.
  5. Edit the secret and replace the values you set in Step 2 with the actual credentials from your secret keys, clientId, clientSecret and containerRegistryKey.
  6. Once the proper credentials are in place, the sidecar instances will stabilize and the sidecar will be displayed with a green icon in the Cyral control plane UI.

Rotate the client secret for a sidecar​

Communications between the Cyral control plane and sidecar are secured using a client secret, which has an associated client ID. Cyral automatically creates each sidecar's initial client ID and client secret when you create the sidecar's deployment template.

When you deploy a new sidecar, you'll see its Client ID and Client Secret specified in the SidecarClientID and SidecarClientSecret parameters of the deployment template.

Once a sidecar is deployed and running, you can replace its client secret at any time. This is typically called rotating the sidecar credentials. Follow these steps:

  1. In the Cyral control plane UI, click Sidecars, click the name of your sidecar, and click Sidecar registration.
  2. Click the + sign to generate a new client ID and client secret.
     

  3. The generated values appear in the pop-up window. Use the copy buttons to copy the values so that you can paste them into your secrets manager.

    Important! You will see the client secret only once, so be sure to keep this window open until you've copied it. If you do lose your newly created secret, you can create another new one by following this process again. If you create a client secret but don't wish to use it, click the delete button to remove it.

  4. Open your secrets manager, such as AWS Secrets Manager or Hashicorp Vault. Find the secret record for the sidecar and edit it, pasting the new client ID and client secret values. Below, we show an example of doing this in AWS.
     

Once the sidecar has connected to the Cyral control plane with its new client ID and secret, the old client ID row will disappear from the Sidecar Registration tab in Cyral, and the new, active client ID will remain visible in the tab as long as its secret is active.