PricingTechnologyDocumentation
Login
HomePricingTechnologyDocumentationLoginSignup

AWS S3

Introduction

An S3 remote stores CloudBD disks inside an AWS S3 bucket. S3 remotes use regional AWS resources and belong to the same AWS region as their S3 bucket (chosen during bucket creation). To use CloudBD disks in multiple AWS regions a separate S3 remote is required for each AWS region.

AWS Resources

The following AWS resources are used by a CloudBD S3 remote:

  • S3 Remote Bucket (regional)

    Storage for CloudBD data.

  • S3 Remote Policy

    IAM policy that grants read and write access to the remote's S3 bucket.

  • S3 VPC Endpoint

    Optimizes VPC routing for increased performance between EC2 instances and S3. This endpoint should be added to all VPCs that use CloudBD.

Auth Types

CloudBD uses IAM credentials to authenticate requests between EC2 instances and S3 remotes. An S3 remote config file containing the auth is placed in the /etc/cloudbd/remotes.d/ directory on EC2 instances.

The following auth types are supported:

  • EC2 Metadata Auth (Recommended)

    IAM Role Based Auth

    An IAM role that has the S3 remote policy is attached to the instance using an IAM instance profile. CloudBD uses the IAM credentials that AWS automatically creates and provides to the instance through the instance's metadata.

  • IAM User Auth

    IAM User Based Auth

    CloudBD uses an IAM user's credentials. The S3 remote IAM Policy is attached to an IAM user and the user's access_key_id and secret_access_key are placed inside the remote config file.

Limitations

  • There is no limit to how many CloudBD disks a single S3 remote can hold.
  • EC2 instances using an S3 remote must be located in the same AWS region as the remote.
  • A CloudBD disk can only be attached to a single EC2 instance at a time. Attaching a CloudBD disk to multiple EC2 instances simultaneously can corrupt the disk.

Setup Guides

An S3 remote can be created by following one of these guides:

CloudFormation Setup Guide

CloudBD S3 remotes and disks can be created directly from CloudFormation templates. EC2 instances configured with cfn-init can install the CloudBD disk driver, deploy your credentials.json, and attach CloudBD disks during stack creation. Complete example templates for all supported Linux distros are available at the CloudBD CloudFormation github page.

The CloudFormation setup guide includes:

  • Creating an S3 Remote Stack (steps 1-2)
  • Integrating with your Existing VPC and EC2 Templates (steps 3-7)

1. Upload your CloudBD Credentials

Your CloudBD credentials.json file is required by CloudFormation to create and attach CloudBD disks. Store your credentials.json in an AWS SSM 'SecureString' parameter to allow CloudFormation to securely deploy it to your EC2 instances.

CloudFormation does not support creating SSM 'SecureString' parameters directly using a template. This step must be completed manually using either the AWS Management Console or the AWS CLI. Once created, your CloudBD credentials SSM parameter can be shared across all of your S3 remote stacks in any AWS region.

AWS Management Console Steps:

  1. Go to Services -> Systems Manager -> Parameter Store -> Create Parameter
  2. Enter param name '/cloudbd/credentials.json'
  3. Use 'Standard' tier
  4. Use 'SecureString' type
  5. Use the default KMS key ('alias/aws/ssm') or select a customer managed KMS Key to use for parameter encryption
  6. Copy your CloudBD account credentials (see Credentials for more info) into the Value field
  7. Select 'Create parameter'

Links:

2. Create an S3 Remote Stack

The S3 remote template creates the S3 remote bucket, IAM policy, and CloudFormation custom resource lambda that manages CloudBD disks. CloudBD provides a publicly available S3 URL for this template in supported AWS regions at:

https://cfn-templates.cloudbd.io.s3.amazonaws.com/remote.yml

The latest version of the remote template is also available at the CloudBD CloudFormation GitHub project.

AWS Management Console Steps:

  1. Go to Services -> CloudFormation -> Create stack

  2. Select 'Template is ready'

  3. Specify the regional S3 URL for the remote template:

    https://cfn-templates.cloudbd.io.s3.amazonaws.com/remote.yml

  4. Enter a stack name

  5. Enter parameters:

    • Select the AWS region that contains your CloudBD credentials SSM parameter.
    • Enter the name of the SSM parameter that contains your CloudBD credentials.json (default: '/cloudbd/credentials.json').
    • If you selected a customer managed KMS Key for encrypting your CloudBD credentials SSM parameter, enter the Key ID, otherwise leave the CredentialsCustomKeyId parameter blank.
    • Select to enable or disable server-side encryption.

  6. Select Next -> Configure any stack options such as tags -> Select Next

  7. Review and accept the required IAM capabilities

  8. Select Create stack

Template Details:

The following is a summary of the parameters, resources, and outputs of the S3 remote stack template.

Parameters

  • CredentialsRegion - AWS Region of the SSM Parameter Store that contains your CloudBD credentials.
  • CredentialsParamName - Name of the SSM Parameter that contains your CloudBD credentials
  • CredentialsCustomKeyId - Customer managed KMS Key ID used to encrypt your CloudBD credentials. Leave this parameter empty if you are using the default AWS SSM encryption key 'alias/aws/ssm'.
  • ServerSideEncryption - Enable or disable server-side encryption on the remote bucket.

Resources

  • CloudBDS3RemoteBucket - Storage for CloudBD disks.
  • CloudBDS3RemotePolicy - IAM policy that grants access to the S3 remote bucket and to your CloudBD credentials SSM parameter.
  • CloudBDDiskLambdaRole - IAM role that provides the CloudBDDiskLambda access to the CloudBD credentials and S3 remote. Also grants access to write to CloudWatch to log disk creation/deletion requests.
  • CloudBDDiskLambda - Lambda function that handles creation/deletion requests of CloudBD disks from CloudFormation. Source code for the lambda is available at the CloudBD CloudFormation github page.

Outputs

All outputs use the export name format: ${AWS::StackName}:<OUTPUT>

  • CloudBDS3RemoteBucket - Name of the S3 remote bucket.
  • CloudBDS3RemotePolicy - Arn of the IAM policy that grants access to the S3 remote bucket and CloudBD credentials.
  • CloudBDDiskLambda - Arn of the CloudFormation custom resource lambda that creates CloudBD disks on this S3 remote.
  • CloudBDS3RemoteConf - CloudBD S3 remote config file. Deploy to your EC2 instances to attach this S3 remote.
  • GetCloudBDCredentials - AWS CLI helper command to retrieve CloudBD credentials. Used by cfn-init scripts to securely deploy the CloudBD credentials to your EC2 instances. The instance's IAM profile/role requires the CloudBDCredentialsPolicy attached.

3. Integrate with Existing Templates

Your S3 remote is now ready to store CloudBD disks. The remainder of this CloudFormation setup guide will detail how to integrate your newly created S3 remote stack with your existing CloudFormation templates.

Some of the remaining steps require access to the S3 remote stack's outputs. In our example templates we use the template parameter 'CloudBDS3RemoteStack' to specify the S3 remote stack name and the Fn::ImportValue intrinsic to access the stack's outputs.

Parameters:
  CloudBDS3RemoteStack:
    Description: CloudBD S3 remote stack name
    Type: String
"Parameters": {
  "CloudBDS3RemoteStack": {
    "Description": "CloudBD S3 remote stack name",
    "Type": "String"
  }
}

4. Add the S3 VPC Endpoint

AWS provides a dedicated high throughput network between EC2 instances and S3 at no additional cost. To use this network add an S3 VPC gateway endpoint to your VPC templates and update your VPC stacks. For the best CloudBD disk performance you should add the S3 endpoint to all VPCs that will use CloudBD disks.

Example S3 VPC Endpoint:

Resources:
  VpcS3Endpoint:
    Type: AWS::EC2::VPCEndpoint
    Properties:
      VpcId: !Ref ExampleVpc
      RouteTableIds:
      - !Ref ExampleVpcRouteTable
      ServiceName: !Sub 'com.amazonaws.${AWS::Region}.s3'
"Resources": {
  "VpcS3Endpoint": {
    "Type": "AWS::EC2::VPCEndpoint",
    "Properties": {
      "VpcId": { "Ref": "ExampleVpc" },
      "RouteTableIds": [
        { "Ref": "ExampleVpcRouteTable" }
      ],
      "ServiceName": { "Fn::Sub": "com.amazonaws.${AWS::Region}.s3" }
    }
  }
}

5. Add an IAM Instance Profile

EC2 instances can assume an IAM role by being assigned an instance profile.

  • If your EC2 instance is already using an IAM instance profile:

    1. Add the S3 remote stack's CloudBDS3RemotePolicy to the list of managed policy arns on the instance profile's role.

  • If your EC2 instance is NOT already using an IAM instance profile, in your template:

    1. Create a new IAM role that can be assumed by the EC2 service and add the CloudBDS3RemotePolicy to the role's ManagedPolicyArns list.
    2. Create a new IAM instance profile and add the new IAM role to the instance profile's Roles list.
    3. Attach the instance profile to your EC2 instances.

Example IAM Role and Instance Profile:

Resources:
  ExampleInstanceRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
        - Effect: "Allow"
          Principal:
            Service: "ec2.amazonaws.com"
          Action: "sts:AssumeRole"
      ManagedPolicyArns:
      - Fn::ImportValue: !Sub '${CloudBDS3RemoteStack}:CloudBDS3RemotePolicy'

  ExampleInstanceProfile:
    Type: AWS::IAM::InstanceProfile
    Properties:
      Roles: [ !Ref ExampleInstanceRole ]
"Resources": {
  "ExampleInstanceRole": {
    "Type": "AWS::IAM::Role",
    "Properties": {
      "AssumeRolePolicyDocument": {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Principle": { "Service": "ec2.amazonaws.com" },
            "Action": "sts::AssumeRole"
          }
        ]
      },
      "ManagedPolicyArns": [
        {
          "Fn::ImportValue": {
            "Fn::Sub": "${CloudBDS3RemoteStack}:CloudBDS3RemotePolicy"
          }
        }
      ]
    }
  },
  "ExampleInstanceProfile": {
    "Type": "AWS::IAM::InstanceProfile",
    "Properties": {
      "Roles": [ { "Ref": "ExampleInstanceRole" } ]
    }
  }
}

Example EC2 Instance with Attached Instance Profile:

Resources: 
  ExampleInstance:
    Type: AWS::EC2::Instance
      Properties:
        ...
        IamInstanceProfile: !Ref ExampleInstanceProfile
        ...
"Resources": {
  "ExampleInstance": {
    "Type": "AWS::EC2::Instance",
    "Properties": {
      ...
      "IamInstanceProfile": { "Ref": "ExampleInstanceProfile" },
      ...
    }
  }
}

6. Add CloudBD Disks

Add CloudBD disks to your templates using the custom resource lambda exported from the remote stack. Set the disk's 'Name' and 'Size' properties. CloudBD disk names must be unique on the S3 remote. The 'Size' parameter accepts the same units as the CloudBD CLI create disk command (minimum disk size: 8GiB, max disk size: 16 PiB, recommended max disk size when using an Ext4 filesystem: 128 TiB).

Example CloudBD Disk:

Resources:
  CloudBDExampleDisk:
    Type: Custom::CloudBDDisk
    Properties:
      ServiceToken:
        Fn::ImportValue: !Sub '${CloudBDS3RemoteStack}:CloudBDDiskLambda'
      Name: !Sub '${AWS::StackName}_CloudBDExampleDisk'
      Size: 128G
"Resources": {
  "CloudBDExampleDisk": {
    "Type": "Custom::CloudBDDisk",
    "Properties": {
      "ServiceToken": {
        "Fn::ImportValue": { "Fn::Sub": "${CloudBDS3RemoteStack}:CloudBDDiskLambda" }
      },
      "Name": { "Fn::Sub": "${AWS::StackName}_CloudBDExampleDisk" },
      "Size": "128G"
    }
  }
}

7. Attach CloudBD Disk to an EC2 Instance

CloudFormation can install the CloudBD driver and attach CloudBD disks to your EC2 instances using AWS cfn-init. Cfn-init is a tool for handling configuration of an EC2 instance during stack creation. Each Linux distro has its own method of installing cfn-init and CloudBD. See complete example templates for all CloudBD supported Linux distros on the CloudBD CloudFormation GitHub project page.

Please note when copying from example templates that the CloudFormation logical ID of the CloudBD Disk ('CloudBDExampleDisk') and the EC2 Instance ('ExampleInstance') is used in several locations within the UserData and AWS::CloudFormation::Metadata. When integrating CloudBD disks with your CloudFormation templates be sure to change these values to your resources' logical IDs.

  1. Add cfn-init to your EC2 instance's UserData property (Linux distro specific).

    Example from the Ubuntu 18.04/Bionic template:

    Resources:
  ExampleInstance:
    Type: AWS::EC2::Instance
    Properties:
      ...
      UserData:
        Fn::Base64:
          !Sub |
            #!/bin/bash -x
            export DEBIAN_FRONTEND=noninteractive

            # The regional <region>.ec2.archive.ubuntu.com sources frequently
            # are not responsive or very very slow causing instances to time-out
            # so let's not use them.
            sed -i 's/http:.*\.ec2\.archive\.ubuntu\.com\/ubuntu\//mirror:\/\/mirrors\.ubuntu\.com\/mirrors\.txt/' /etc/apt/sources.list

            # upgrade packages
            apt -y update
            apt -y upgrade

            # install python pip and cfn bootstrap package
            apt install -y --no-install-recommends python-pip python-setuptools python-wheel
            pip install https://s3.amazonaws.com/cloudformation-examples/aws-cfn-bootstrap-latest.tar.gz

            # perform AWS::CloudFormation::Init tasks
            RESOURCE='ExampleInstance'
            /usr/local/bin/cfn-init -v \
                --region ${AWS::Region} \
                --stack ${AWS::StackName} \
                --resource ${!RESOURCE}

            # reboot if needed and signal completion to CloudFormation
            RET=$?
            if [ "$RET" -eq "0" ] && [ -e /var/run/reboot-required ]; then
              cat << EOF > /etc/cron.d/cfn-signal
            SHELL=/bin/bash
            PATH=/sbin:/bin:/usr/sbin:/usr/bin
            MAILTO=root
            HOME=/
            @reboot root { /usr/local/bin/cfn-signal -e ${!RET} --region ${AWS::Region} --stack ${AWS::StackName} --resource ${!RESOURCE}; rm /etc/cron.d/cfn-signal; } > /dev/null
            EOF
              reboot
            else
              /usr/local/bin/cfn-signal -e ${!RET} \
                  --region ${AWS::Region} \
                  --stack ${AWS::StackName} \
                  --resource ${!RESOURCE}
            fi

  2. Configure AWS::CloudFormation::Init metadata to install CloudBD, deploy credentials, attach S3 remote/disks, and create a filesystem.

    Example from the Ubuntu 18.04/Bionic template:

    Resources:
  ExampleInstance:
    Type: AWS::EC2::Instance
    Properties:
      ...
    Metadata:
      AWS::CloudFormation::Init:
        configSets:
          default:
          - CloudBD
        CloudBD:
          files:
            /etc/apt/sources.list.d/cloudbd.list:
              source: 'https://repo.cloudbd.io/bionic/cloudbd.list'
              mode: "000644"
              owner: "root"
              group: "root"
            /usr/share/keyrings/cloudbd-keyring.gpg:
              source: https://repo.cloudbd.io/cloudbd-keyring.gpg
              mode: "000644"
              owner: "root"
              group: "root"
          commands:
            01-install-packages:
              # Install the CloudBD driver and CLI
              command: !Sub |
                set -xe
                apt -y update
                apt -y install cbd-client
            02-deploy-credentials:
              # Deploy your CloudBD account credentials
              test: '! [ -e /etc/cloudbd/credentials.json ]'
              command: !Sub
              - |
                set -xe

                # ensure python pip is installed
                apt install -y --no-install-recommends python-pip python-setuptools python-wheel

                # install the AWS CLI
                pip install awscli

                # Use the GetCloudBDCredentials helper from the remote stack
                ${GetCloudBDCredentials} > /etc/cloudbd/credentials.json

                # Set the proper security permissions/ownership on the credentials file
                chown root:cloudbd /etc/cloudbd/credentials.json
                chmod 640 /etc/cloudbd/credentials.json
              - GetCloudBDCredentials:
                  Fn::ImportValue: !Sub '${CloudBDS3RemoteStack}:GetCloudBDCredentials'
            03-attach-S3-remote:
              # Attach the S3 remote to the instance
              test: '! [ -e /etc/cloudbd/remotes.d/remote.conf ]'
              command: !Sub
              - |
                set -xe
                /bin/echo -E "${CloudBDS3RemoteConf}" > /etc/cloudbd/remotes.d/remote.conf
              - CloudBDS3RemoteConf:
                  Fn::ImportValue: !Sub '${CloudBDS3RemoteStack}:CloudBDS3RemoteConf'
            04-attach-disk:
              # Attach CloudBDExampleDisk to the instance
              test: !Sub '! [ -b /dev/mapper/remote:${CloudBDExampleDisk.Name} ]'
              command: !Sub
              - |
                set -xe

                # Ensure that the remote disk exists
                cloudbd info "remote:${CloudBDExampleDisk.Name}"

                # If the disk is not already listed within the cbdtab, add it
                # Each CloudBD disk attached to the instance requires a unique nbd number (0-15)
                if ! grep -E -q "[[:space:]]remote:${CloudBDExampleDisk.Name}([[:space:]#]|\$)" /etc/cloudbd/cbdtab; then
                  /bin/echo -E "nbd0  remote:${CloudBDExampleDisk.Name} ${DriverMode},${DriverOptions}" >> /etc/cloudbd/cbdtab
                fi

                # Start the disk
                cbddisks_start "remote:${CloudBDExampleDisk.Name}"
              - DriverMode: 'defaults'
                DriverOptions: ''
            05-format-filesystem:
              # Create a filesystem on the CloudBD disk and mount at '/mnt'
              test: '! /bin/mountpoint -q /mnt'
              command: !Sub |
                set -xe
                DEVICE="/dev/mapper/remote:${CloudBDExampleDisk.Name}"
                MOUNT="/mnt"

                # fstab requires any spaces in the mountpoint to be encoded
                FSTAB_ENCODED_MOUNT="$(/bin/echo ${!MOUNT} | sed -e 's/[[:space:]]/\\040/g')"

                # Ensure the CloudBD disk is attached before formatting
                [ -b "${!DEVICE}" ]

                # Check that the disk is not already formatted and create a filesystem with the recommended settings
                if ! blkid "${!DEVICE}" | grep -q -e 'UUID' -e 'TYPE' -e 'PARTUUID'; then
                  mkfs.ext4 -b 4096 -T largefile \
                      -E stride=512,stripe_width=512,lazy_itable_init=0,lazy_journal_init=0,packed_meta_blocks=1 \
                      "${!DEVICE}"
                fi

                # If the disk is not already listed in the fstab, add it
                if ! grep -q "${!DEVICE}[[:space:]]" /etc/fstab; then
                  /bin/echo -E "${!DEVICE}      ${!FSTAB_ENCODED_MOUNT} ext4    _netdev,discard" >> /etc/fstab
                fi

                # Create the mountpoint and mount the disk
                mkdir -p "${!MOUNT}"
                mount "${!DEVICE}"

AWS Management Console Setup Guide

CloudBD S3 remotes can be created manually using the AWS Management Console.

When using CloudBD on AWS we recommend using CloudFormation instead of manually creating remotes as CloudFormation can automate installing the disk driver, deploying your credentials.json, and attaching your disks to your instances.

1. Create the S3 Remote Bucket

  1. Go to Services -> S3 -> Create Bucket
  2. Enter bucket name and region (<BUCKETNAME> and <REGION>)
  3. Use default configure options
  4. Use default permissions with all block public access settings enabled

CloudBD does not support buckets with Object Versioning, Object Lock, or Cross-Region Replication enabled.

Links:

2. Create the S3 Remote IAM Policy

  1. Go to Services -> IAM -> Policies -> Create policy

  2. Select the JSON editor tab and enter the following policy replacing <BUCKETNAME> with the S3 bucket name created above.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowListBucket",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::<BUCKETNAME>"
        },
        {
            "Sid": "AllowHeadBucket",
            "Effect": "Allow",
            "Action": "s3:HeadBucket",
            "Resource": "*"
        },
        {
            "Sid": "AllowCloudbdObjectOps",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::<BUCKETNAME>/cloudbd/*"
        }
    ]
}

  3. Select Review policy

  4. Enter a policy name (e.g., cloudbd-<BUCKETNAME>)

  5. Select Create policy

Links:

3. Create an IAM Role and Instance Profile

EC2 instances can assume an IAM role by being assigned an instance profile. In the AWS Management Console, when creating an IAM role AWS automatically creates an IAM instance profile for the role.

  • If your EC2 instance is already using an IAM role:

    1. Go to Services -> IAM -> Roles
    2. Select the role used by your instance
    3. Select Attach policies
    4. Select the CloudBD role for the S3 remote
    5. Select Attach policy

  • If your EC2 instance is NOT already using an IAM role:

    1. Go to Services -> IAM -> Roles -> Create role
    2. Select type of trusted entity: AWS service
    3. Choose the service that will use this role: EC2
    4. Select Next: Permissions
    5. Select the S3 remote IAM policy previously created
    6. Select Next: Tags -> (Optional) Enter any tags for this role -> Select Next: Review
    7. Enter a Role name (e.g., cloudbd-<BUCKETNAME>)
    8. Select Create role

Links:

4. Create S3 VPC Endpoints

AWS provides a dedicated high throughput network from EC2 instances to S3 over a VPC gateway endpoint. For the best CloudBD disk performance you should add the S3 endpoint to each VPC that will use CloudBD disks.

  1. Select your region
  2. Go to Services -> VPC -> Endpoints -> Create Endpoint
  3. Select Service category: AWS services
  4. Select Service name: com.amazonaws.<REGION>.s3 type Gateway (replacing <REGION> with the S3 bucket region created above)
  5. Select your VPC
  6. Select all route table ids
  7. Select Policy: Full Access

Links:

5. Configure EC2 Instances

  1. Attach the IAM Role to your EC2 instances

    • When launching new EC2 instances, on the configure instance details page, IAM role -> select the S3 remote IAM role
    • For updating existing EC2 instances, select the EC2 instance -> Actions -> Instance Settings -> Attach/Replace IAM Role -> select the IAM role that includes the S3 remote policy

  2. Install the CloudBD software

    When deploying your remote config file use the following config (replacing <\REGION> and <BUCKETNAME> with your remote's values).

    type = aws_ec2_metadata
region = <REGION>
bucket = <BUCKETNAME>

6. Enable Server-Side Encryption (optional)

CloudBD supports S3 buckets with default encryption enabled. When server side encryption is desired, SSE-S3 is recommended because it does not have per request charges associated with its use. SSE-KMS is NOT recommended with CloudBD disks due to its per request pricing structure. While CloudBD disks are in use they generate many S3 requests. Using SSE-KMS with CloudBD disks will quickly become a significant additional AWS cost and is not recommended.

  1. Select your region
  2. Go to Services -> S3
  3. Select your S3 remote bucket
  4. Select the Properties tab
  5. Select the Default encryption box
  6. Select AES-256
  7. Select Save

Links:

AWS CLI Setup Guide

CloudBD S3 remotes can be created manually using the AWS CLI.

When using CloudBD on AWS we recommend using CloudFormation instead of manually creating remotes as CloudFormation can automate installing the disk driver, deploying your credentials.json, and attaching your disks to your instances.

In the following steps replace <BUCKETNAME> and <REGION> with your values. See the AWS Regions and Endpoints guide for a list of S3 region names for each AWS region.

1. Make the S3 Remote Bucket

  1. Create Bucket

    • If using the US East N. Virigina (us-east-1) region

      aws s3api create-bucket \
    --bucket <BUCKETNAME> \
    --region us-east-1

    • If using any other AWS region

      aws s3api create-bucket \
    --bucket <BUCKETNAME> \
    --region <REGION> \
    --create-bucket-configuration LocationConstraint=<REGION>

  2. Block public access to the bucket (recommended)

    # Requires aws-cli version 1.16.56 or higher
aws s3api put-public-access-block \
    --bucket <BUCKETNAME> \
    --region <REGION> \
    --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

CloudBD does not support buckets with Object Versioning, Object Lock, or Cross-Region Replication enabled.

Links:

2. Make the S3 Remote IAM Policy

  1. Create Policy

    BUCKETNAME="<BUCKETNAME>"  # Replace <BUCKETNAME> with your S3 bucket
aws iam create-policy \
    --policy-name "cloudbd-$BUCKETNAME" \
    --policy-document "{
        \"Version\": \"2012-10-17\",
        \"Statement\": [
            {
                \"Sid\": \"AllowListBucket\",
                \"Effect\": \"Allow\",
                \"Action\": \"s3:ListBucket\",
                \"Resource\": \"arn:aws:s3:::$BUCKETNAME\"
            },
            {
                \"Sid\": \"AllowHeadBucket\",
                \"Effect\": \"Allow\",
                \"Action\": \"s3:HeadBucket\",
                \"Resource\": \"*\"
            },
            {
                \"Sid\": \"AllowCloudbdObjectOps\",
                \"Effect\": \"Allow\",
                \"Action\": [
                    \"s3:PutObject\",
                    \"s3:GetObject\",
                    \"s3:DeleteObject\"
                ],
                \"Resource\": \"arn:aws:s3:::$BUCKETNAME/cloudbd/*\"
            }
        ]
    }"

The output from the create policy command includes the arn of the new policy required by the next step.

Links:

3. Make an IAM Role and Instance Profile

EC2 instances can assume an IAM role by being assigned an instance profile.

  1. Set BUCKETNAME and POLICYARN

    # Replace <BUCKETNAME> with your S3 bucket name
BUCKETNAME="<BUCKETNAME>"

# Replace <POLICYARN> with the arn of the S3 remote IAM policy
POLICYARN="<POLICYARN>"

  2. Create a new IAM service role for EC2

    aws iam create-role \
    --role-name "cloudbd-$BUCKETNAME" \
    --assume-role-policy-document "{
        \"Version\": \"2012-10-17\",
        \"Statement\": [
            {
                \"Effect\": \"Allow\",
                \"Principal\": { \"Service\": \"ec2.amazonaws.com\"},
                \"Action\": \"sts:AssumeRole\"
            }
        ]
    }"

  3. Attach S3 remote IAM policy to the role

    aws iam attach-role-policy \
    --role-name "cloudbd-$BUCKETNAME" \
    --policy-arn "$POLICYARN"

  4. Create a new IAM instance profile for the role

    aws iam create-instance-profile \
    --instance-profile-name "cloudbd-$BUCKETNAME"

  5. Attach the IAM service role to the instance profile

    aws iam add-role-to-instance-profile \
    --instance-profile-name "cloudbd-$BUCKETNAME" \
    --role-name "cloudbd-$BUCKETNAME"

Links:

4. Make S3 VPC Endpoints

AWS provides a dedicated high throughput network from EC2 instances to S3 over a VPC gateway endpoint. For the best CloudBD disk performance you should add the S3 endpoint to each VPC that will use CloudBD disks.

  1. Set REGION

    REGION="<REGION>"  # Replace with your AWS region

  2. Get the S3 VPC service endpoint name for the region (typically 'com.amazonaws.<REGION>.s3')

    aws ec2 describe-vpc-endpoint-services \
    --region "$REGION" \
    --filters "Name=service-name,Values=*.s3" \
    --query "ServiceNames[*]" \
    --output text

SERVICE="<SERVICENAME>"  # Replace with the S3 service name

  3. Describe VPCs in the region

    # Describe all VPCs in the region
aws ec2 describe-vpcs --region "$REGION"

  4. For each VPC that will use CloudBD disks found in the previous step:

    1. Describe VPC route tables for the VPC

      VPCID="<VPC ID>"  # Set to a VPC ID that will have CloudBD disks
aws ec2 describe-route-tables \
    --region "$REGION" \
    --filters "Name=vpc-id,Values=$VPCID"

    2. Create the S3 VPC endpoint adding it to the appropriate route tables(s) for your network layout

      aws ec2 create-vpc-endpoint \
    --region "$REGION" \
    --vpc-id "$VPCID" \
    --service-name "$SERVICE" \
    --route-table-ids <ROUTE_TABLE_ID> [ROUTE_TABLE_ID]...

Links:

5. Put Server-Side Encryption (optional)

CloudBD supports S3 buckets with default encryption enabled. When server side encryption is desired, SSE-S3 is recommended because it does not have per request charges associated with its use. SSE-KMS is NOT recommended with CloudBD disks due to its per request pricing structure. While CloudBD disks are in use they generate many S3 requests. Using SSE-KMS with CloudBD disks will quickly become a significant additional AWS cost and is not recommended.

Replace <BUCKET> and <REGION> with your CloudBD S3 remote bucket name and AWS region.

REGION="<REGION>"  # Replace with your S3 remote's region
BUCKET="<BUCKET>"  # Replace with your S3 remote's bucket name

aws s3api put-bucket-encryption \
    --region "$REGION" \
    --bucket "$BUCKET" \
    --server-side-encryption-configuration '{
      "Rules": [{
          "ApplyServerSideEncryptionByDefault": {
              "SSEAlgorithm": "AES256"
          }
      }]
    }'

Links:

Remote Config

An S3 remote config file is required to attach the S3 remote to your EC2 instances. Remote config files are placed in the /etc/cloudbd/remotes.d/ directory. Config files must end in ".conf" and use basic INI format of key = value. The remote config filename without the ".conf" extension is used as the name for the remote by the CloudBD CLI and cbdtab.

$ # example of a connected remote
$ ls /etc/cloudbd/remotes.d/
myremote1.conf

$ # CloudBD CLI command to list configured remotes
$ cloudbd list
myremote1

EC2 Metadata Auth Config File

Role Based Auth

CloudBD uses the IAM credentials AWS provides to the instance through the instance metadata. The S3 remote IAM policy is attached to an IAM role and the role is attached to the EC2 instance.

Example

  • /etc/cloudbd/remotes.d/remote.conf

    type = aws_ec2_metadata
region = us-east-1
bucket = data1.example.com

Required Fields

  • Type - The auth type of the S3 remote.

    type = aws_ec2_metadata

  • Region - The AWS region of the S3 remote. See the AWS Regions and Endpoints guide for a list of S3 region names for each AWS region.

    region = <us-east-1 | us-east-2 | us-west-1 | us-west-2 | ca-central-1 | ... >

  • Bucket - The name of the S3 remote bucket.

    bucket = <Your bucket name>

Optional Fields

  • Protocol - Use http or https when communicating with S3.

    CloudBD will default to using 'http' if not set. Using the http protocol is less CPU intensive but requires trust of the local network. The https protocol is more secure because it encrypts all network data but requires more CPU overhead when reading and writing to the CloudBD disks.

    protocol = <http | https>

IAM User Auth Config File

User Based Auth

CloudBD uses the IAM credentials specified in the remote config file. The S3 remote IAM policy is attached to an IAM user.

Example

  • /etc/cloudbd/remotes.d/remote.conf

    type = aws_iam_user
region = us-east-2
bucket = data2.example.com
access_key_id = AKIAIOSFODNN7EXAMPLE
secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY

Required Fields

  • Type - The auth type of the S3 remote.

    type = aws_iam_user

  • Region - The AWS region of the S3 remote. See the AWS Regions and Endpoints guide for a list of S3 region names for each AWS region.

    region = <us-east-1 | us-east-2 | us-west-1 | us-west-2 | ca-central-1 | ... >

  • Bucket - The name of the S3 remote bucket.

    bucket = <Your bucket name>

  • Access Key ID - The IAM access key id of an IAM user with the S3 remote IAM policy.

    access_key_id = <IAM access key id>

  • Secret Access Key - The IAM secret access key created with Accss Key ID.

    secret_access_key = <IAM secret access key>

Optional Fields

  • Protocol - Use http or https when communicating with S3.

    CloudBD will default to using 'http' if not set. Using the http protocol is less CPU intensive but requires trust of the local network. The https protocol is more secure because it encrypts all network data but requires more CPU overhead when reading and writing to the CloudBD disks.

    protocol = <http | https>
← AWS QuickstartGoogle Cloud Storage →
HomePricingTechnologyDocumentation
LoginSignup
Cookie PolicyPrivacy PolicyTerms and Conditions


© 2020, CloudBD LLC. All rights reserved.

Amazon Web Services, Amazon S3, EC2 and the Amazon Web Services logo are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries. Ubuntu and the Ubuntu Circle of Friends logo are registered trademarks of Canonical Ltd. Google, Google Cloud Storage and the Google Cloud Platform logo are registered trademarks of Google LLC. Linux ® is the registered trademark of Linus Torvalds in the U.S. and other countries. OpenStack is either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries.