Skip to content

README.md

Latest commit

 

History

History
131 lines (89 loc) · 35.5 KB

README.md

File metadata and controls

131 lines (89 loc) · 35.5 KB

Elastio Connector Terraform Deployment

This directory contains terraform modules that you may use to automate the deployment of the Elastio Connector stacks in your AWS accounts.

Obtain a Personal Access Token (PAT)

First of all, you'll need a secret PAT token to authenticate your Elastio installation with the Elastio Portal. You can generate one by following the steps below.

  1. Open the Elastio Portal in your web browser.
  2. Go to the Settings page.
  3. Open the API access tab.
  4. Click on Add New Access Token.
  5. Enter the name for the token, for example Elastio deployment.
  6. Select the scope Sources: Write for the token.
  7. Click on Generate Token.
  8. Copy the generated token.
  9. Optional step. Save the token in a secure place like 1Password or any other secret management system of your choice. This way you won't lose it.

Add Elastio to Your Terraform

There is are several terraform modules that you can use. We'll review all of them below.

Installation

Configure the Elastio terraform module registry before adding any Elastio terraform modules to your project.

elastio-connector module

This module provides the easiest way to get started. It resides as the top-level module in this directory. It deploys all the necessary resources for Elastio to operate in a single module for the entire AWS account and covers many regions.

Add this terraform module to your terraform project and specify the necessary input variables. Here you'll need to pass the PAT token you generated earlier.

Important

Make sure curl of version at least 7.76.0 is installed on the machine that runs the terraform deployment (terraform apply). The provided terraform module uses a local-exec provisioner that uses curl to do a REST API call to Elastio Portal.

Here is the basic example usage of the module that deploys Elastio Connectors in several regions allowing you to scan your assets in these regions.

module "elastio_connector" {
  source  = "terraform.cloudsmith.io/public/elastio-connector/aws"
  version = "0.33.1"

  elastio_tenant = var.elastio_tenant
  elastio_pat    = var.elastio_pat

  elastio_cloud_connectors = [
    {
      region = "us-east-1"
    },
    {
      region = "us-east-2",
    }
  ]
}

You can find the full version of this example in examples/basic.

This module deploys the following three modules internally, that you can deploy individually if a finer grained control over the deployment is required. You may use them, for example, if you need to deploy regional stacks in separate terraform projects instead of using a single one that deploys all regions.

elastio-connector-account module

Creates an AWS CloudFormation stack named elastio-account-level-stack, which is deployed once per AWS account and contains the required IAM resources (roles, policies, etc.) for Elastio Connector to operate in the same account.

See modules/account directory for details.

elastio-connector-region module

Deploys the Elastio Cloud Connector stack via a REST API call to the Elastio Portal. The final stack contains Lambda functions, DynamoDB databases, S3 buckets, AWS Batch compute environments and other non-IAM resources.

See modules/region directory for details.

elastio-nat-provision module

Optional. AWS CloudFormation stack named elastio-nat-provision-lambda which deploys NAT gateways in the private subnets where Elastio scan job workers run. This is necessary only if you deploy Elastio into private subnets that don't have outbound Internet access already. Alternatively, you can deploy your own NAT gateway if you want to.

See modules/nat-provision directory for details.

Documentation for elastio-connector module

Requirements

Name Version
terraform ~> 1.0
aws ~> 5.0
http ~> 3.0

Providers

No providers.

Modules

Name Source Version
account ./modules/account n/a
nat_provision ./modules/nat-provision n/a
region ./modules/region n/a

Resources

No resources.

Inputs

Name Description Type Default Required
disable_customer_managed_iam_policies If this is set to false (or omitted), then the stack will create
additional customer-managed IAM policies that you can attach to your
IAM identities to grant them direct access to the Elastio Connector stack.
This way you can use elastio CLI directly to list Elastio scan jobs or
submit new scan jobs. Set this to true if you don't need these policies.		 bool null no
ecr_public_prefix Repository prefix for the ECR Public registry. Used to configure a pull-through
cache for elastio images that are downloaded from ECR Public. You can configure
your own cache via ECR private, and then specify the repository prefix here.

This field supports 'account_id' and 'region' interpolation.
For example, such value can be provided:
'{{account_id}}.dkr.ecr.{{region}}.amazonaws.com/ecr-public'		 string null no
elastio_cloud_connectors List of regions where Cloud Connectors are to be deployed, VPC and subnet(s) to use,
and other regional configurations (mostly for regulatory compliance).		 
list(object({
 region = string

 # Should not be set if network_configuration
 # is set to Auto (which is the default)
 vpc_id = optional(string)
 subnet_ids = optional(list(string))

 s3_access_logging = optional(object({
 target_bucket = string
 target_prefix = optional(string)

 # Can be one of the following:
 # - SimplePrefix
 # - PartitionedPrefix:EventTime
 # - PartitionedPrefix:DeliveryTime
 target_object_key_format = optional(string)
 }))
 }))
 n/a yes
elastio_nat_provision_stack Specifies the version of Elastio NAT provision stack to deploy (e.g. v5).

This is a CloudFormation stack that automatically provisions NAT Gateways in
your VPC when Elastio worker instances run to provide them with the outbound
Internet access when Elastio is deployed in private subnets.

If you don't need this stack (e.g. you already have NAT gateways in your VPC
or you deploy into public subnets) you can omit this parameter. The default
value of null means there won't be any NAT provision stack deployed.

The source code of this stack can be found here:
https://github.com/elastio/contrib/tree/master/elastio-nat-provision-lambda		 string null no
elastio_pat Personal Access Token generated by the Elastio Portal string n/a yes
elastio_tenant Name of your Elastio tenant. For example mycompany.app.elastio.com string n/a yes
encrypt_with_cmk Provision additional customer-managed KMS keys to encrypt
Lambda environment variables, DynamoDB tables, S3. Note that
by default data is encrypted with AWS-managed keys.

Enable this option only if your compliance requirements mandate the usage of CMKs.

If this option is disabled Elastio creates only 1 CMK per region where
the Elastio Connector stack is deployed. If this option is enabled then
Elastio creates 1 KMS key per AWS account and 2 KMS keys per every AWS
region where Elastio is deployed in your AWS account.

If you have elastio_nat_provision_stack enabled as well, then 1 more KMS key
will be created as part of that stack as well (for a total of 3 KMS keys per region).		 bool null no
global_managed_policies List of IAM managed policies ARNs to attach to all Elastio IAM roles set(string) null no
global_permission_boundary The ARN of the IAM managed policy to use as a permission boundary for all Elastio IAM roles string null no
iam_resource_names_prefix Add a custom prefix to names of all IAM resources deployed by this stack.
The sum of the length of the prefix and suffix must not exceed 14 characters.		 string null no
iam_resource_names_static If enabled, the stack will use static resource names without random characters in them.

This parameter is set to true by default, and it shouldn't be changed. The older
versions of Elastio stack used random names generated by CloudFormation for IAM
resources, which is inconvenient to work with. New deployments that use the terraform
automation should have this set to true for easier management of IAM resources.		 bool true no
iam_resource_names_suffix Add a custom prefix to names of all IAM resources deployed by this stack.
The sum of the length of the prefix and suffix must not exceed 14 characters.		 string null no
lambda_tracing Enable AWS X-Ray tracing for Lambda functions. This increases the cost of
the stack. Enable only if needed		 bool null no
network_configuration Can be set to either Auto or Manual. If set to Auto, Elastio will
automatically create a VPC and subnets in the specified regions for the
scan clusters to run in.

If set to Manual, you must provide the VPC ID and subnet IDs in the
elastio_cloud_connectors with the network config for each region.		 string "Manual" no
service_linked_roles By default the CFN stack creates the service-linked IAM roles needed by the stack.
Since these are global in your account, they can't be defined as regular resources
in the CFN, because these roles may already exist in your account and thus
the deployment would fail on a name conflict.

Instead, by default, they are deployed using an AWS::CloudFormation::CustomResource
which invokes an AWS Lambda function that creates the service-linked roles only if
they don't exist and doesn't fail if they do.

The default approach of creating the service-linked roles via the CFN requires
creating a lambda function in your environment that has IAM write permission of
iam:CreateServiceLinkedRole. If you can't afford creating such a lambda function
then set this parameter to tf and this terraform module will create the
service-linked roles without the need for a lambda function.

If you set this to tf, then make sure you have the AWS CLI installed and
configured with the necessary credentials on the machine where you run terraform.		 string "cfn" no

Outputs

No outputs.