AWS Preparation

This article mainly introduces the AWS operations involved in creating a BYOC type warehouse, including creating an IAM user and authorizing it, creating a VPC and subnet, and understanding resource orchestration and resource stacks.

Prepare an IAM user and authorize it

Before creating a BYOC warehouse, you need to prepare an AWS IAM user with relevant permissions.

During the BYOC deployment, the page will redirect to AWS. You need to use this user to log in to the AWS management console and create a resource stack in CloudFormation.

If you already have an AWS user with the Administrator role, you can skip creating a policy and an IAM user.

Otherwise, please send this document to your AWS administrator and ask the administrator to create an IAM user for you and authorize it according to this document.

The administrator accesses the AWS Identity and Access Management(IAM) (opens in a new tab) console and performs the following operations:

Create a policy

When creating a VeloDB Cloud BYOC type warehouse, you need to execute the resource stack template through the resource orchestration service (CloudFormation), which will create cloud resources such as EC2, VPC, S3, or perform related operations, so a series of IAM permissions are required.

Click Access Management > Policies on the left to enter the permission policy management page and click Create Policy

Switch to JSON mode, clear the original text box, copy the following script, and enter the text box. For detailed permission descriptions, see the Permission Description of Resource Stack Template Dependencies section below.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/resource-created-by": [
                        "selectdb"
                    ]
                }
            },
            "Action": [
                "ec2:TerminateInstances",
                "ec2:StopInstances",
                "ec2:StartInstances",
                "ec2:RebootInstances",
                "ec2:ModifyInstanceAttribute",
                "ec2:DescribeSecurityGroupRules",
                "ec2:AuthorizeSecurityGroupIngress",
                "ec2:RevokeSecurityGroupIngress",
                "ec2:AuthorizeSecurityGroupEgress",
                "ec2:RevokeSecurityGroupEgress",
                "ec2:DeleteSecurityGroup",
                "ec2:GetEbsEncryptionByDefault",
                "ec2:GetEbsDefaultKmsKeyId"
            ],
            "Resource": [
                "arn:aws:ec2:*:*:*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "ec2:DescribeVpcs",
                "ec2:DescribeSubnets",
                "ec2:DescribeAccountAttributes",
                "ec2:DescribeAddresses",
                "ec2:DescribeInternetGateways",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeInstanceTypes",
                "ec2:DescribeVolumes",
                "ec2:ModifyVolume",
                "ec2:DescribeImages",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeInstances",
                "ec2:RunInstances",
                "ec2:CreateSecurityGroup",
                "ec2:DescribeTags",
                "ec2:CreateTags",
                "ec2:DeleteTags",
                "ec2:*VpcEndpoint*",
                "compute-optimizer:GetEnrollmentStatus",
                "elasticloadbalancing:*",
                "s3:CreateBucket"
            ],
            "Resource": [
                "*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "s3:Get*",
                "s3:List*",
                "s3:Put*",
                "s3:Delete*"
            ],
            "Resource": [
                "arn:aws:s3:::velodb-bucket-*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "sts:GetCallerIdentity",
                "sts:AssumeRole",
                "iam:GetUser",
                "iam:TagUser",
                "iam:CreateUser",
                "iam:DeleteUser",
                "iam:ListAccessKeys",
                "iam:CreateAccessKey",
                "iam:DeleteAccessKey",
                "iam:GetRole",
                "iam:TagRole",
                "iam:ListRoles",
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:CreatePolicy",
                "iam:GetUserPolicy",
                "iam:PutUserPolicy",
                "iam:GetRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteUserPolicy",
                "iam:DeleteRolePolicy",
                "iam:GetInstanceProfile",
                "iam:CreateInstanceProfile",
                "iam:AddRoleToInstanceProfile",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:DeleteInstanceProfile"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": [
                        "ec2.amazonaws.com",
                        "lambda.amazonaws.com"
                    ]
                }
            },
            "Action": [
                "iam:PassRole"
            ],
            "Resource": "arn:aws:iam::*:role/velodb-*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "cloudformation:*"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "lambda:GetFunction",
                "lambda:CreateFunction",
                "lambda:DeleteFunction",
                "lambda:InvokeFunction",
                "lambda:TagResource"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "iam:CreateServiceLinkedRole"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "iam:AWSServiceName": "elasticloadbalancing.amazonaws.com"
                }
            },
            "Effect": "Allow"
        }
    ]
}

Note: For detailed permission description, please see the Permission Description of Resource Stack Template Dependencies section below.

Click Next, enter a name, and click OK to complete the creation of the permission policy.

Create an IAM user and authorize it

Notice: If you already have an IAM user, you can skip the creation step and authorize it directly.

Click Access Management > User on the left, enter the User Management page, click Create User, enter relevant information, and click Next.

Select the policy created in the above steps, click Next, click Create User, and complete the creation.

Create an IAM user group and authorize (optional)

If there are multiple people in the enterprise using VeloDB Cloud, you can create an IAM user group, add relevant people to the user group, and authorize them uniformly.

Click Access Management > User Groups on the left to enter the User Group Management page, click Create group, enter User group name, select the User name and Policy name to be added, and click Create user group to complete the creation.

Prepare a VPC and subnet

Before creating a BYOC type warehouse, you need to use the above IAM user to create a VPC and subnet in advance. The following are the specific operations.

Notice: If a VPC or subnet that meets the region, availability zone, and subnet requirements exists and you want to deploy the BYOC warehouse in this VPC, skip the following steps to create a virtual private cloud VPC or subnet.

Additional subnet requirements

Because the deployment and management of VeloDB services requires Internet access to AWS's EC2 ELB S3 service (and other services in the future), so we currently support two types of subnets:

1. Private Subnet with external network access (Recommended)
The routing table associated with the subnet contains the 0.0.0.0/0 route to the public NAT gateway. This is the recommended subnet type. In this case, all created machines will access the external network through the public IP address of the shared NAT gateway, which is more secure. It is worth noting that if you choose a private subnet, then we assume that your company intranet and the VPC network are interoperable, otherwise you will not be able to access the WebUI

2. Public Subnet (Not recommended)
The routing table associated with the subnet contains 0.0.0.0/0 routes to the IGW gateway. If you choose a public network subnet, then we will assign a public IP address to all subsequent machines by default, but this is not recommended.

When the resource stack is created by CloudFormation, ensure that the IGW or NAT is in the normal state and the routing table is correctly configured. For subnets that do not meet the above two conditions, we will directly report an error during CloudFormation build and block subsequent execution.

The following is the classic network architecture diagram provided by AWS. Subnet 4 is a private subnet with external network access, subnet 1 and subnet 2 are public network subnets, these three subnets meet the requirements, subnet 3 will fail to be deployed.

Create VPC

Open the Amazon Web Services VPC (opens in a new tab) console and switch to the region where you want to deploy the BYOC warehouse.

Click Create VPC to enter the VPC creation page.

Select VPC only, enter the name, input IPv4 CDR, click Create VPC to complete the creation.

Create subnet

Click Subnets > Create subnet on the left to enter the subnet creation page.

We recommend creating two subnets (note that the subnet availability zone ids need to be aligned), one as a public subnet and one as a private subnet, and eventually we will deploy the VeloDB service on the private subnet.

Note: The regions and availability zones currently supported are：

Cloud Platform	Region Name	Region ID	Availability Zone ID
AWS	US East (N. Virginia)	us-east-1	use1-az2
AWS	US West (Oregon)	us-west-2	usw2-az1
AWS	Europe (Ireland)	eu-west-1	euw1-az1
AWS	Asia Pacific (Singapore)	ap-southeast-1	apse1-az1
AWS	Asia Pacific (Hong Kong)	ap-east-1	ape1-az1

Create an IGW and NAT, configure route table

Create an IGW and attach it to the VPC

Add a route to IGW in the route table of the public network subnet

Create a NAT on the public network subnet

Create a new route table for private subnet and add routes to NAT

Associate this new route table to private subnet

The final network topology should look like the following

Learn about Resource Orchestration and Resource Stack

Note: You don't need to do anything in this chapter. If you want to learn more about how it works, you can continue reading.

When a user creates a BYOC type warehouse, the Agent will be automatically deployed with the help of the cloud vendor's resource orchestration service to complete the private connection between the Agent and the VeloDB Cloud platform, and then the Agent will be responsible for the deployment and management of the BYOC warehouse.

Resource Orchestration Template Description

The resource orchestration template provided by VeloDB runs under your cloud account, and the template code is visible and auditable, and will not operate on your data and other environments in the VPC. You can get the resource orchestration template provided by VeloDB through the following link:

https://selectdb-cloud-online.s3.us-west-1.amazonaws.com/public/aws-byoc.yaml

When you execute the above resource template through AWS CloudFormation, it will automatically create and deploy the Agent. Then the Agent will establish a private connection with VeloDB Cloud and complete the warehouse initialization process.

After the resource orchestration script is executed, you can enter the corresponding warehouse from the VeloDB Cloud platform and start creating a computing cluster for data analysis just like using a normal warehouse.

How to view resource stack information

You can view all resources created through the CloudFormation interface's Resources tab, and view specific resources by resource name:

EC2
- Name: VeloDBAgent (EC2)
- Purpose: Used to deploy Agent, Prometheus, FluentBit and other programs
VPC Endpoint
- Name: VeloDBEndpoint (VPC Endpoint):
- Purpose: Establishes private network connection with VeloDB Manage service to pull control instructions and enable one-way push of monitoring and logs
S3 Bucket
- Name: VeloDBBucket (S3 Bucket)
- Purpose: Used to store data warehouse data
SecurityGroup
- Name: VeloDBSecurityGroupForEndpoint, VeloDBSecurityGroup (VPC SecurityGroup)
- Purpose: One is bound to the endpoint and only allows access to certain ports, such as 2222,8666,8888,9090. One is bound to the all EC2 instances launched by VeloDB, and restricts traffic through security group rules (allows all traffic from the same security group to access all ports, traffic from the same subnet to access port 5000, and allows all outbound traffic)
IAM User / IAM Role
- Names:
  - VeloDBUser (IAM User), VeloDBAkSk (IAM User AkSk), VeloDBUserPolicy (IAM User Policy)
  - VeloDBControlPlaneRole (IAM Role), VeloDBControlPlaneRolePolicy (IAM Role Policy)
  - VeloDBDataAccessRole (IAM Role), VeloDBDataAccessRolePolicy (IAM Role Policy)
- Purposes:
  - The created sub-user has minimum permissions required by Agent, and all subsequent control operations will use this sub-user's identity (All sub-user information will only be used within user's VPC and will not be leaked)
  - Bound to EC2 instances to obtain temporary Token for authentication, which is more secure than using permanent AkSk. One for control plane use (bound to Agent), one for kernel side use (bound to MS/FE/BE)
Lambda Function
- Names:
  - CustomFunction* (Lambda Function logic)
  - CustomResourceRole (temporary role for executing Lambda Function)
- Purpose: Lambda Function is used to implement logic that is available in Python SDK but not in CF templates. For this template, it mainly includes:
  1. Get lowercase S3 bucket name, as Amazon S3 does not allow uppercase letters in bucket names
  2. Get the information of the user-selected subnet, such as subnet type and cidr-block
  3. If there is no S3 gateway endpoint within the VPC, a new one will be automatically created, thus enabling the traffic of S3 buckets to be routed within the VPC instead of through the public Internet.

Permissions description of resource stack template dependencies

When executing a resource stack template through the resource orchestration service (CloudFormation) under your cloud account, cloud resources such as EC2, VPC, S3, etc. will be created or related operations will be performed, so a series of IAM permissions are required. Before formal execution, please ensure that the user executing this template has the corresponding permissions, otherwise the template execution may fail.

Note The execution process of the resource stack template is completely carried out under your cloud account, and the created resources also belong to your cloud account. VeloDB will not obtain your cloud account information, nor can it use the corresponding IAM permissions of the account.

The following are the permissions required based on the resources and operations defined in the template:

Permission summary:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/resource-created-by": [
                        "selectdb"
                    ]
                }
            },
            "Action": [
                "ec2:TerminateInstances",
                "ec2:StopInstances",
                "ec2:StartInstances",
                "ec2:RebootInstances",
                "ec2:ModifyInstanceAttribute",
                "ec2:DescribeSecurityGroupRules",
                "ec2:AuthorizeSecurityGroupIngress",
                "ec2:RevokeSecurityGroupIngress",
                "ec2:AuthorizeSecurityGroupEgress",
                "ec2:RevokeSecurityGroupEgress",
                "ec2:DeleteSecurityGroup",
                "ec2:GetEbsEncryptionByDefault",
                "ec2:GetEbsDefaultKmsKeyId"
            ],
            "Resource": [
                "arn:aws:ec2:*:*:*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "ec2:DescribeVpcs",
                "ec2:DescribeSubnets",
                "ec2:DescribeAccountAttributes",
                "ec2:DescribeAddresses",
                "ec2:DescribeInternetGateways",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeInstanceTypes",
                "ec2:DescribeVolumes",
                "ec2:ModifyVolume",
                "ec2:DescribeImages",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeInstances",
                "ec2:RunInstances",
                "ec2:CreateSecurityGroup",
                "ec2:DescribeTags",
                "ec2:CreateTags",
                "ec2:DeleteTags",
                "ec2:*VpcEndpoint*",
                "compute-optimizer:GetEnrollmentStatus",
                "elasticloadbalancing:*",
                "s3:CreateBucket"
            ],
            "Resource": [
                "*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "s3:Get*",
                "s3:List*",
                "s3:Put*",
                "s3:Delete*"
            ],
            "Resource": [
                "arn:aws:s3:::velodb-bucket-*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "sts:GetCallerIdentity",
                "sts:AssumeRole",
                "iam:GetUser",
                "iam:TagUser",
                "iam:CreateUser",
                "iam:DeleteUser",
                "iam:ListAccessKeys",
                "iam:CreateAccessKey",
                "iam:DeleteAccessKey",
                "iam:GetRole",
                "iam:TagRole",
                "iam:ListRoles",
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:CreatePolicy",
                "iam:GetUserPolicy",
                "iam:PutUserPolicy",
                "iam:GetRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteUserPolicy",
                "iam:DeleteRolePolicy",
                "iam:GetInstanceProfile",
                "iam:CreateInstanceProfile",
                "iam:AddRoleToInstanceProfile",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:DeleteInstanceProfile"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": [
                        "ec2.amazonaws.com",
                        "lambda.amazonaws.com"
                    ]
                }
            },
            "Action": [
                "iam:PassRole"
            ],
            "Resource": "arn:aws:iam::*:role/velodb-*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "cloudformation:*"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "lambda:GetFunction",
                "lambda:CreateFunction",
                "lambda:DeleteFunction",
                "lambda:InvokeFunction",
                "lambda:TagResource"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "iam:CreateServiceLinkedRole"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "iam:AWSServiceName": "elasticloadbalancing.amazonaws.com"
                }
            },
            "Effect": "Allow"
        }
    ]
}

The specific permissions are divided as follows:

EC2 & VPC permissions:

Manage EC2 and security groups

{
    "Condition": {
        "StringEquals": {
            "aws:ResourceTag/resource-created-by": [
                "selectdb"
            ]
        }
    },
    "Action": [
        "ec2:TerminateInstances",
        "ec2:StopInstances",
        "ec2:StartInstances",
        "ec2:RebootInstances",
        "ec2:ModifyInstanceAttribute",
        "ec2:DescribeSecurityGroupRules",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupEgress",
        "ec2:DeleteSecurityGroup",
        "ec2:GetEbsEncryptionByDefault",
        "ec2:GetEbsDefaultKmsKeyId"
    ],
    "Resource": [
        "arn:aws:ec2:*:*:*"
    ],
    "Effect": "Allow"
}

Get VPC related resource information

{
    "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeAccountAttributes",
        "ec2:DescribeAddresses",
        "ec2:DescribeInternetGateways",
        "ec2:DescribeInstances",
        "ec2:DescribeAvailabilityZones",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeVolumes",
        "ec2:ModifyVolume",
        "ec2:DescribeImages",
        "ec2:RunInstances",
        "ec2:CreateSecurityGroup",
        "ec2:DescribeTags",
        "ec2:CreateTags",
        "ec2:DeleteTags",
        "compute-optimizer:GetEnrollmentStatus",
    ],
    "Resource": "*",
    "Effect": "Allow"
},

ELB permissions:
- Manage Elastic Load Balancer (ELB) resources
```
elasticloadbalancing:*
```

S3 permissions:

Manage S3 buckets and perform read/write operations on buckets and their contents (for specific buckets)

{
    "Action": [
        "s3:CreateBucket"
    ],
    "Resource": [
        "*"
    ],
    "Effect": "Allow"
},
{
    "Action": [
        "s3:Get*",
        "s3:List*",
        "s3:Put*",
        "s3:Delete*"
    ],
    "Resource": [
        "arn:aws:s3:::velodb-bucket-*"
    ],
    "Effect": "Allow"
},

IAM & STS & Lambda permissions:

IAM and STS services

{
    "Action": [
        "sts:GetCallerIdentity",
        "sts:AssumeRole",
        "iam:GetUser",
        "iam:TagUser",
        "iam:CreateUser",
        "iam:DeleteUser",
        "iam:ListAccessKeys",
        "iam:CreateAccessKey",
        "iam:DeleteAccessKey",
        "iam:GetRole",
        "iam:TagRole",
        "iam:ListRoles",
        "iam:CreateRole",
        "iam:DeleteRole",
        "iam:CreatePolicy",
        "iam:GetUserPolicy",
        "iam:PutUserPolicy",
        "iam:GetRolePolicy",
        "iam:PutRolePolicy",
        "iam:DeleteUserPolicy",
        "iam:DeleteRolePolicy",
        "iam:GetInstanceProfile",
        "iam:CreateInstanceProfile",
        "iam:AddRoleToInstanceProfile",
        "iam:RemoveRoleFromInstanceProfile",
        "iam:DeleteInstanceProfile"
    ],
    "Resource": "*",
    "Effect": "Allow"
},

Lambda service:

{
    "Action": [
        "lambda:GetFunction",
        "lambda:CreateFunction",
        "lambda:DeleteFunction",
        "lambda:InvokeFunction",
        "lambda:TagResource"
    ],
    "Resource": "*",
    "Effect": "Allow"
},

ELB service-associated role related:

{
    "Action": [
        "iam:CreateServiceLinkedRole"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "iam:AWSServiceName": "elasticloadbalancing.amazonaws.com"
        }
    },
    "Effect": "Allow"
}

CloudFormation permissions:

{
    "Action": [
        "cloudformation:*"
    ],
    "Resource": "*",
    "Effect": "Allow"
},

Permissions of sub-users created by resource stack templates

After the resource stack template is executed for the first time, a sub-user will be created for subsequent management of data warehouse related components in your VPC. The following is a description of the permissions of the sub-user.

Note The created sub-user belongs to your cloud account and is only used in your VPC and will not be leaked.