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 = "~> 5.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

Module upgrade

If you are coming from v4 of this module, read the upgrade notes for specific instructions on how to upgrade this module.

Sidecar 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.

Advanced

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

• Advanced networking configuration
• Bring your own secret
• Customer initialization scripts
• Enable the S3 File Browser
• Memory limits
• Sidecar certificates
• Sidecar instance metrics

Requirements

Name	Version
terraform	>= 1.9
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.asg	resource
aws_cloudwatch_log_group.lg	resource
aws_iam_instance_profile.sidecar_profile	resource
aws_iam_policy.init_script_policy	resource
aws_iam_role.sidecar_role	resource
aws_iam_role_policy_attachment.init_script_policy	resource
aws_iam_role_policy_attachment.user_policies	resource
aws_launch_template.lt	resource
aws_lb.lb	resource
aws_lb_listener.ls	resource
aws_lb_target_group.tg	resource
aws_route53_record.cyral-sidecar-dns-record	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	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_lbs.current	data source
aws_partition.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
additional_security_groups	List of the IDs of the additional security groups that will be attached to the sidecar instances. If providing additional_target_groups, use this parameter to provide security groups with the inbound rules to allow inbound traffic from the target groups to the instances.	list(string)	[]	no
additional_target_groups	List of the ARNs of the additional target groups that will be attached to the sidecar instances. Use it in conjunction with additional_security_groups to provide the inbound rules for the ports associated with them, otherwise the incoming traffic from the target groups will not be allowed to access the EC2 instances.	list(string)	[]	no
ami_id	AMI ID that will be used for the EC2 instances. If not provided, will use the latest Amazon Linux 2 AMI available.	string	""	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
ca_certificate_role_arn	(Optional) ARN of an AWS IAM Role to assume when reading the CA certificate.	string	""	no
ca_certificate_secret_arn	(Optional) ARN of secret in AWS Secrets Manager that contains a CA certificate to sign sidecar-generated certs.	string	""	no
client_id	(Optional) The client id assigned to the sidecar. If not provided, must provide a secret containing the respective client id using secret_arn.	string	""	no
client_secret	(Optional) The client secret assigned to the sidecar. If not provided, must provide a secret containing the respective client secret using secret_arn.	string	""	no
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
control_plane	Address of the control plane - .cyral.com	string	n/a	yes
curl_connect_timeout	(Optional) The maximum time in seconds that curl connections are allowed to take.	number	60	no
custom_host_role	(Optional) Name of an AWS IAM Role to attach to the EC2 instance profile.	string	""	no
custom_tags	Custom tags to be added to all AWS resources created	map(any)	{}	no
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
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
dns_hosted_zone_id	(Optional) Route53 hosted zone ID for the corresponding 'dns_name' provided	string	""	no
dns_name	(Optional) Fully qualified domain name that will be automatically created/updated to reference the sidecar LB	string	""	no
dns_overwrite	(Optional) Update an existing DNS name informed in dns_name.	bool	false	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
health_check_grace_period	The minimum amount of time (in seconds) to keep a new instance in service before terminating it if it's found to be unhealthy	number	300	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
launch_template_tags_resource_types	Set of resource types to be used to add custom tags to the launch template. See also custom_tags.	set(string)	[ "instance", "volume", "network-interface" ]	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) Parameter has no effect in case deploy_load_balancer = false.	string	"internal"	no
load_balancer_security_groups	List of the IDs of the additional security groups that will be attached to the load balancer. Parameter has no effect in case deploy_load_balancer = false.	list(string)	[]	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. Parameter has no effect in case deploy_load_balancer = false.	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
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	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
secret_arn	Full ARN of the AWS Secrets Manager secret used to store the sidecar secrets. If unset, sidecar will manage its own secret. See the topic Bring Your Own Secret in the Advanced documentation section.	string	""	no
secret_role_arn	(Optional) ARN of an AWS IAM Role to assume when reading the secret informed in secret_arn.	string	""	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
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_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_certificate_role_arn	(Optional) ARN of an AWS IAM Role to assume when reading the TLS certificate.	string	""	no
tls_certificate_secret_arn	(Optional) ARN of secret in AWS Secrets Manager that contains a certificate to terminate TLS connections.	string	""	no
tls_skip_verify	(Optional) Skip TLS verification for HTTPS communication with the control plane and during sidecar initialization	bool	false	no
volume_size	Size of the sidecar disk	number	15	no
volume_type	Type of the sidecar disk	string	"gp3"	no
vpc_id	AWS VPC ID to deploy sidecar to	string	n/a	yes

Outputs

Name	Description
ami_id	EC2 AMI id
autoscaling_group_arn	Auto scaling group ARN
ca_certificate_secret_arn	ARN of the CA certificate secret used by the sidecar
cloudwatch_log_group_name	Name of the CloudWatch log group where sidecar logs are stored
dns	Sidecar DNS endpoint
iam_role_arn	Sidecar IAM role ARN
launch_template_arn	Launch template ARN
load_balancer_arn	Load balancer ARN
load_balancer_dns	Sidecar load balancer DNS endpoint
secret_arn	ARN of the secret with the credentials used by the sidecar
security_group_id	Sidecar security group id
tls_certificate_secret_arn	ARN of the TLS certificate secret used by the sidecar