Cyral sidecar module for AWS EC2

Use this Terraform module to deploy a sidecar on AWS EC2 instances.

Refer to the quickstart guide for more information on how to use this module or upgrade your sidecar.

Architecture

The elements shown in the architecture diagram above are deployed by this module. The module requires existing VPC and subnets in order to create the necessary components for the sidecar to run. In a high-level, these are the resources deployed:

• EC2
  • Auto scaling group (responsible for managing EC2 instances and EBS volumes)
  • Network load balancer (optional)
  • Security group
• Secrets Manager
  • Sidecar credentials
  • Sidecar CA certificate
  • Sidecar self-signed certificate
• IAM
  • Sidecar role
• Cloudwatch
  • Log group (optional)

Usage

provider "aws" {
  # Define the target AWS region
  region = "us-east-1"
}

module "cyral_sidecar" {
  source  = "cyralinc/sidecar-ec2/aws"  
  version = "~> 4.0" # terraform module version

  sidecar_id      = ""
  control_plane   = ""
  client_id          = ""
  client_secret      = ""
  
  # Leave empty if you prefer to perform upgrades directly
  # from the control plane.
  sidecar_version = ""

  # Considering MongoDB ports are from the range 27017 to 27019
  sidecar_ports = [443, 3306, 5432, 27017, 27018, 27019]

  vpc_id  = ""
  subnets = [""]

  # Inbound CIDR to SSH into the EC2 instances
  ssh_inbound_cidr        = ["0.0.0.0/0"]
  # Inbound CIDR to access ports defined in `sidecar_ports`
  db_inbound_cidr         = ["0.0.0.0/0"]
  # Inbound CIDR to monitor the EC2 instances (port 9000)
  monitoring_inbound_cidr = ["0.0.0.0/0"]
}

Note:

• name_prefix is defined automatically. If you wish to define a custom name_prefix, please keep in mind that its length must be at most 24 characters.

Upgrade

This module supports 1-click upgrade.

To enable the 1-click upgrade feature, leave the variable sidecar_version empty and upgrade the sidecar from Cyral control plane.

If you prefer to block upgrades from the Cyral control plane and use a static version, assign the desired sidecar version to sidecar_version. To upgrade your sidecar, update this parameter with the target version and run terraform apply.

Learn more in the sidecar upgrade procedures page.

See also the module's upgrade notes for specific instructions on how to upgrade this module from previous major versions.

Advanced

Instructions for advanced deployment configurations are available for the following topics:

• Advanced networking configuration
• Enable the S3 File Browser
• Sidecar certificates
• Sidecar instance metrics

Requirements

Name	Version
terraform	>= 1.1
aws	>= 3.73.0, < 6.0.0
tls	~> 4.0.0

Providers

Name	Version
aws	>= 3.73.0, < 6.0.0
tls	~> 4.0.0

Modules

No modules.

Resources

Name	Type
aws_autoscaling_group.cyral-sidecar-asg	resource
aws_cloudwatch_log_group.cyral-sidecar-lg	resource
aws_iam_instance_profile.sidecar_profile	resource
aws_iam_policy.init_script_policy	resource
aws_iam_policy.sidecar_custom_certificate_secrets_manager	resource
aws_iam_role.self_signed_certificate	resource
aws_iam_role.sidecar_custom_certificate	resource
aws_iam_role.sidecar_role	resource
aws_iam_role_policy_attachment.init_script_policy	resource
aws_iam_role_policy_attachment.sidecar_custom_certificate	resource
aws_iam_role_policy_attachment.user_policies	resource
aws_lambda_function.self_signed_certificate	resource
aws_lambda_invocation.self_signed_ca_certificate	resource
aws_lambda_invocation.self_signed_tls_certificate	resource
aws_launch_template.cyral_sidecar_lt	resource
aws_lb.cyral-lb	resource
aws_lb_listener.cyral-sidecar-lb-ls	resource
aws_lb_target_group.cyral-sidecar-tg	resource
aws_route53_record.cyral-sidecar-dns-record	resource
aws_secretsmanager_secret.custom_tls_certificate	resource
aws_secretsmanager_secret.self_signed_ca	resource
aws_secretsmanager_secret.self_signed_tls_cert	resource
aws_secretsmanager_secret.sidecar_secrets	resource
aws_secretsmanager_secret_version.self_signed_ca	resource
aws_secretsmanager_secret_version.self_signed_tls_cert	resource
aws_secretsmanager_secret_version.sidecar_secrets	resource
aws_security_group.instance	resource
tls_private_key.ca	resource
tls_private_key.tls	resource
tls_self_signed_cert.ca	resource
tls_self_signed_cert.tls	resource
aws_ami.amazon_linux_2	data source
aws_arn.cw_lg	data source
aws_availability_zones.all	data source
aws_caller_identity.current	data source
aws_iam_policy_document.init_script_policy	data source
aws_iam_policy_document.kms	data source
aws_iam_policy_document.sidecar	data source
aws_iam_policy_document.sidecar_custom_certificate_assume_role	data source
aws_iam_policy_document.sidecar_custom_certificate_secrets_manager	data source
aws_lbs.current	data source
aws_partition.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
additional_security_groups	Additional security groups to attach to sidecar instances	list(string)	[]	no
ami_id	Amazon Linux 2 AMI ID for sidecar EC2 instances. The default behavior is to use the latest version. In order to define a new image, provide the desired image id.	string	""	no
asg_count	Set to 1 to enable the ASG, 0 to disable. Only for debugging.	number	1	no
asg_desired	The desired number of hosts to create in the auto scaling group	number	1	no
asg_max	The maximum number of hosts to create in the auto scaling group	number	3	no
asg_min	The minimum number of hosts to create in the auto scaling group	number	1	no
asg_min_healthy_percentage	The minimum percentage of healthy instances during an ASG refresh	number	100	no
associate_public_ip_address	Associates a public IP to sidecar EC2 instances	bool	false	no
client_id	The client id assigned to the sidecar	string	n/a	yes
client_secret	The client secret assigned to the sidecar	string	n/a	yes
cloudwatch_log_group_name	(Optional) Cloudwatch log group name.	string	""	no
cloudwatch_logs_retention	Cloudwatch logs retention in days	number	14	no
container_registry	Address of the container registry where Cyral images are stored.	string	"public.ecr.aws/cyral"	no
container_registry_key	Corresponding key for the user name provided to authenticate to the container registry.	string	""	no
container_registry_username	Username to authenticate to the container registry.	string	""	no
control_plane	Address of the control plane - .cyral.com	string	n/a	yes
custom_user_data	Ancillary consumer supplied user-data script. Bash scripts must be added to a map as a value of the key pre, pre_sidecar_start, post denoting execution order with respect to sidecar installation. (Approx Input Size = 19KB)	map(any)	{ "post": "", "pre": "", "pre_sidecar_start": "" }	no
db_inbound_cidr	Allowed CIDR blocks for database access to the sidecar. Can't be combined with 'db_inbound_security_group'.	list(string)	n/a	yes
db_inbound_security_group	Pre-existing security group IDs allowed to connect to db in the EC2 host. Can't be combined with 'db_inbound_cidr'.	list(string)	[]	no
dd_api_key	(Deprecated - unused in sidecars v4.10+) API key to connect to DataDog	string	""	no
deploy_load_balancer	Deploy or not the load balancer and target groups. This option makes the ASG have only one replica, irrelevant of the Asg Min Max and Desired	bool	true	no
deploy_secrets	Create the AWS Secrets Manager resource at secret_location storing client_id, client_secret and container_registry_key.	bool	true	no
ec2_ebs_kms_arn	ARN of the KMS key used to encrypt/decrypt EBS volumes. If unset, EBS will use the default KMS key. Make sure the KMS key allows the principal arn:aws:iam::ACCOUNT_NUMBER:role/aws-service-role/autoscaling.amazonaws.com/AWSServiceRoleForAutoScaling, otherwise the ASG will not be able to launch the new instances.	string	""	no
enable_cross_zone_load_balancing	Enable cross zone load balancing	bool	true	no
hc_vault_integration_id	(Deprecated - unused in sidecars v4.10+) HashiCorp Vault integration ID	string	""	no
health_check_grace_period	The grace period in seconds before the health check will terminate the instance	number	600	no
iam_policies	(Optional) List of IAM policies ARNs that will be attached to the sidecar IAM role	list(string)	[]	no
idp_certificate	(Optional) The certificate used to verify SAML assertions from the IdP being used with Snowflake. Enter this value as a one-line string with literal new line characters (\n) specifying the line breaks.	string	""	no
idp_sso_login_url	(Optional) The IdP SSO URL for the IdP being used with Snowflake.	string	""	no
instance_metadata_token	Instance Metadata Service token requirement	string	"required"	no
instance_type	Amazon EC2 instance type for the sidecar instances	string	"t3.medium"	no
key_name	AWS key name	string	""	no
load_balancer_certificate_arn	(Optional) ARN of SSL certificate that will be used for client connections to Snowflake.	string	""	no
load_balancer_scheme	EC2 network load balancer scheme ('internal' or 'internet-facing')	string	"internal"	no
load_balancer_sticky_ports	List of ports that will have session stickiness enabled. This parameter must be a subset of 'sidecar_ports'.	list(number)	[]	no
load_balancer_subnets	Subnets to add load balancer to. If not provided, the load balancer will assume the subnets specified in the subnets parameter.	list(string)	[]	no
load_balancer_tls_ports	List of ports that will have TLS terminated at load balancer level (snowflake support, for example). If assigned, 'load_balancer_certificate_arn' must also be provided. This parameter must be a subset of 'sidecar_ports'.	list(number)	[]	no
log_integration	Logs destination	string	"cloudwatch"	no
metrics_integration	(Deprecated - unused in sidecars v4.10+) Metrics destination	string	""	no
monitoring_inbound_cidr	Allowed CIDR blocks for health check and metric requests to the sidecar. If restricting the access, consider setting to the VPC CIDR or an equivalent to cover the assigned subnets as the load balancer performs health checks on the EC2 instances.	list(string)	n/a	yes
name_prefix	Prefix for names of created resources in AWS. Maximum length is 24 characters.	string	""	no
recycle_health_check_interval_sec	(Optional) The interval (in seconds) in which the sidecar instance checks whether it has been marked or recycling.	number	30	no
reduce_security_group_rules_count	If set to false, each port in sidecar_ports will be used individually for each CIDR in db_inbound_cidr to create inbound rules in the sidecar security group, resulting in a number of inbound rules that is equal to the number of sidecar_ports * db_inbound_cidr. If set to true, the entire sidecar port range from min(sidecar_ports) to max(sidecar_ports) will be used to configure each inbound rule for each CIDR in db_inbound_cidr for the sidecar security group. Setting it to true can be useful if you need to use multiple sequential sidecar ports and different CIDRs for DB inbound (db_inbound_cidr) since it will significantly reduce the number of inbound rules and avoid hitting AWS quotas. As a side effect, it will open all the ports between min(sidecar_ports) and max(sidecar_ports) in the security group created by this module.	bool	false	no
repositories_supported	(Deprecated - unused in sidecars v4.10+) List of all repositories that will be supported by the sidecar (lower case only)	list(string)	[ "denodo", "dremio", "dynamodb", "mongodb", "mysql", "oracle", "postgresql", "redshift", "snowflake", "sqlserver", "s3" ]	no
secrets_kms_arn	ARN of the KMS key used to encrypt/decrypt secrets. If unset, secrets will use the default KMS key.	string	""	no
secrets_location	Location in AWS Secrets Manager to store client_id, client_secret and container_registry_key. If unset, will assume /cyral/sidecars/<SIDECAR_ID>/secrets.	string	""	no
sidecar_ca_certificate_role_arn	(Optional) ARN of an AWS IAM Role to assume when reading the CA certificate.	string	""	no
sidecar_ca_certificate_secret_arn	(Optional) ARN of secret in AWS Secrets Manager that contains a CA certificate to sign sidecar-generated certs.	string	""	no
sidecar_custom_certificate_account_id	(Optional) AWS Account ID where the custom certificate module will be deployed.	string	""	no
sidecar_custom_host_role	(Optional) Name of an AWS IAM Role to attach to the EC2 instance profile.	string	""	no
sidecar_dns_hosted_zone_id	(Optional) Route53 hosted zone ID for the corresponding 'sidecar_dns_name' provided	string	""	no
sidecar_dns_name	(Optional) Fully qualified domain name that will be automatically created/updated to reference the sidecar LB	string	""	no
sidecar_dns_overwrite	(Optional) Update an existing DNS name informed in 'sidecar_dns_name' variable	bool	false	no
sidecar_id	Sidecar identifier	string	n/a	yes
sidecar_ports	List of ports allowed to connect to the sidecar through the load balancer and security group. The maximum number of ports is limited to Network Load Balancers quotas (listeners and target groups). See also 'load_balancer_tls_ports'. Avoid port 9000 as it is reserved for instance monitoring.	list(number)	n/a	yes
sidecar_private_idp_key	(Optional) The private key used to sign SAML Assertions generated by the sidecar. Enter this value as a one-line string with literal new line characters ( ) specifying the line breaks.	string	""	no
sidecar_public_idp_certificate	(Optional) The public certificate used to verify signatures for SAML Assertions generated by the sidecar. Enter this value as a one-line string with literal new line characters ( ) specifying the line breaks.	string	""	no
sidecar_tls_certificate_role_arn	(Optional) ARN of an AWS IAM Role to assume when reading the TLS certificate.	string	""	no
sidecar_tls_certificate_secret_arn	(Optional) ARN of secret in AWS Secrets Manager that contains a certificate to terminate TLS connections.	string	""	no
sidecar_version	(Optional, but required for Control Planes < v4.10) The version of the sidecar. If unset and the Control Plane version is >= v4.10, the sidecar version will be dynamically retrieved from the Control Plane, otherwise an error will occur and this value must be provided.	string	""	no
ssh_inbound_cidr	Allowed CIDR blocks for SSH access to the sidecar. Can't be combined with 'ssh_inbound_security_group'.	list(string)	n/a	yes
ssh_inbound_security_group	Pre-existing security group IDs allowed to ssh into the EC2 host. Can't be combined with 'ssh_inbound_cidr'.	list(string)	[]	no
subnets	Subnets to add sidecar to (list of string)	list(string)	n/a	yes
tls_skip_verify	(Optional) Skip TLS verification for HTTPS communication with the control plane and during sidecar initialization	bool	false	no
use_single_container	(Optional) Use single container for sidecar deployment	bool	false	no
volume_size	Size of the sidecar disk	number	15	no
vpc_id	AWS VPC ID to deploy sidecar to	string	n/a	yes

Outputs

Name	Description
aws_cloudwatch_log_group_name	Name of the CloudWatch log group where sidecar logs are stored.
aws_iam_role_arn	Sidecar IAM role ARN
aws_security_group_id	Sidecar security group id
sidecar_custom_certificate_role_arn	IAM role ARN to use in the Sidecar Custom Certificate modules.
sidecar_custom_certificate_secret_arn	Secret ARN to use in the Sidecar Custom Certificate modules.
sidecar_dns	Sidecar DNS endpoint
sidecar_load_balancer_dns	Sidecar load balancer DNS endpoint