Add an external AWS network (BYOC)

Bring your own cloud (BYOC) allows you to connect your DoubleCloud organization with your existing AWS resources by creating a new VPC. This way, you can deploy ClickHouse and Kafka clusters, as well as use DoubleCloud Transfer in your AWS account. All computations, data, backups, and encryption keys will remain in your AWS project.

DoubleCloud creates external networks in AWS based on the CloudFormation stacks. When you start creating a network with your stack, CloudFormation creates a VPC and an IAM role that has permissions to create resources , such as virtual machines or disks in this VPC.

This page explains how to create a new VPC in your AWS cloud and connect it with your DoubleCloud organization.


To learn more about CloudFormation best practices, refer to the AWS documentation .

Before you start

  • Make sure you have permissions to create VPCs, IAM roles, and IAM policies in AWS.

  • Make sure you have either the Clusters editor, Transfer editor, or a higher role in DoubleCloud. These roles permit you to create a VPC.

Step 1. Prepare to create a stack

In the DoubleCloud console, go to the VPC page .

  1. Click Configure BYOC.

  2. In the popup window, perform the following actions:

    1. Select an AWS region.

    2. (Optional) Get familiar with the default CloudFormation stack template located in our public S3 bucket .

    3. Click Launch in AWS.

    The AWS console will open with some pre-filled stack parameters. Log in and specify other parameters there.

Step 2. Create a stack in AWS

The stack creation process has four steps. In this scenario, we show the way to create a stack based on our template:

Step 2.1. Specify the template

  1. Under Prerequisite - Prepare template, keep the Template is ready selection.

  2. In the Specify template section, ensure that Amazon S3 URL is selected.

  3. Make sure that the Amazon S3 URL has the correct link to our S3 bucket:
  4. Click Next to proceed to the second step.

Step 2.2. Specify stack details

  1. Enter your stack name in the Stack name box.

  2. Specify a CIDR block for your VPC in the Parameters section.

  3. Click Next to proceed.

Step 2.3. Configure stack options

  1. In the Tags section, specify tags for your stack if you need to.

  2. Specify an IAM role in the Permissions section.

    This role will define how CloudFormation can create, modify, or delete resources in the stack. If you don't choose a role, CloudFormation uses permissions based on the account under which you logged in.

    The drop-down menu provides two possible options for this:

    • iamRoleName: allows you to select a role from a list of roles you created before with the AWS IAM service.

    • iamRoleArn: allows you to provide a unique role identifier using Amazon Resource Names (ARNs).

  3. Select the Stack failure options:

    • Roll back all stack resources: in case of stack provisioning failure, it rolls back all resources to the last known stable state.

    • Preserve successfully provisioned resources: in case of stack provisioning failure, it preserves the state of successfully provisioned resources and rolls back only the resources that don't have the last known stable state. Resources not provisioned will be deleted.

  4. Configure Advanced options:

    1. Specify Stack policy in the JSON format. This policy defines the resources that you want to protect from unintentional updates during a stack update. You can select one of the following options to provide a policy:
    • No stack policy to let all the resources update during the stack update.

    • Enter stack policy directly in console.

    • Upload a file with a specified policy.

    For more information on policies, see AWS: prevent updates to stack resources .

    1. Specify the Rollback configuration for your resources (optional).

      • Monitoring time

        Specify as an integer number. This setting defines the number of minutes after the operation completes that CloudFormation should monitor the alarms specified below.

      • CloudWatch alarm

        Specify an Amazon Resource Name (ARN) for an alarm in the CloudWatch service and click Add CloudWatch alarm ARN.

    2. Set Notification options.

    3. Specify Stack creation options.

      • Set the Timeout.

        The timeout defines the maximum period that a stack creation process can take. If this period is exceeded, the service will cancel the stack creation. Specify the timeout as an integer number.

      • Select the Termination protection type:

        • Disabled: any account with access to your stack can delete it.

        • Enabled: the stack can't be deleted. Change this setting's value when you update the stack to allow the stack deletion.

  5. Click Next to proceed to the last step.

Step 2.4. Review

  1. Inspect all the settings from previous steps carefully.

  2. If all the settings are correct, select I acknowledge that AWS CloudFormation might create IAM resources with custom names under Capabilities.

  3. Click Create stack and wait several minutes until your stack's status changes from CREATE_IN_PROGRESS to CREATE_COMPLETE.

  4. On the stacks overview page , click your newly created stack name.

  5. On the stack's page, go to the Outputs tab.

  6. Copy the creation output in the Value column. It looks as follows:

    Screenshot of the stack creation output

    You will need this CloudFormation output to paste it in the DoubleCloud console in the next step.

Step 3. Copy the CloudFormation output and add the external network

  1. Switch back to the DoubleCloud console and paste the CloudFormation output under Copy and paste the output information.

  2. Enter the name of your network.

  3. Check the Private network box to block all the inbound connections to the network from the Internet. This capability renders all the infrastructure within the network isolated from the outside, leaving VPC peering on the infrastructure side the only option to connect and rendering the DoubleCloud Visualization service unable to access the data within.

    Allowlists notice

    Keep in mind that the allowlists configured for a specific cluster will affect its availability via a VPC when the Public network feature is enabled and the accessibility from the outside Internet when it's disabled.

  4. Click Add network.


After the network is created, it will be displayed on the VPC overview page under the Networks tab.

You can select this network in the Networking settings section when you create a cluster:

select an external network when creating a cluster

If you want to connect your resources located in this network to external resources, use peering connections.

What's next

See also