Back to source list
Official
Premium
S3
The CloudQuery S3 source plugin reads parquet files and loads them into any supported CloudQuery destination (e.g. PostgreSQL, BigQuery, Snowflake, and more)
Publisher
cloudquery
Latest version
v1.8.5
Type
Source
Platforms
Date Published
Overview #
The CloudQuery S3 source plugin reads parquet files and loads them into any supported CloudQuery destination (e.g. PostgreSQL, BigQuery, Snowflake, and more). The S3 source plugin assumes that all unique prefixes in the S3 bucket are unique tables, and for those objects in the root of the bucket, the table name is the name of the object. For example if you have the following objects in your s3 bucket:
s3://<bucket>/datafile_0.parquet
s3://<bucket>/datafile_1.parquet
s3://<bucket>/data/2024/datafile_1.parquet
s3://<bucket>/data/2024/02/14/14/15/datafile_3.parquet
s3://<bucket>/data/2024/02/14/14/15/datafile_4.parquetCloudQuery will sync the following tables:
datafile_0.parquet --> datafile_0
datafile_1.parquet --> datafile_1
data/2024/datafile_1.parquet --> data_2024
data/2024/02/14/14/15/datafile_3.parquet --> data_2024_02_14_14_15
data/2024/02/14/14/15/datafile_4.parquet --> data_2024_02_14_14_15Authentication #
The plugin needs to be authenticated with your account(s) in order to read from your S3 bucket.
The plugin requires
s3:GetObject and s3:ListBucket permissions on the bucket and objects that you are trying to sync.There are multiple ways to authenticate with AWS, and the plugin respects the AWS credential provider chain. This means that CloudQuery will follow the following priorities when attempting to authenticate:
- The
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKENenvironment variables. - The
credentialsandconfigfiles in~/.aws(thecredentialsfile takes priority). - You can also use
aws ssoto authenticate cloudquery - you can read more about it here. - IAM roles for AWS compute resources (including EC2 instances, Fargate and ECS containers).
Environment Variables #
CloudQuery can use the credentials from the
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables (AWS_SESSION_TOKEN can be optional for some accounts).
For information on obtaining credentials, see the AWS guide.To export the environment variables (On Linux/Mac - similar for Windows):
export AWS_ACCESS_KEY_ID='{Your AWS Access Key ID}'
export AWS_SECRET_ACCESS_KEY='{Your AWS secret access key}'
export AWS_SESSION_TOKEN='{Your AWS session token}'Shared Configuration files #
The plugin can use credentials from your
credentials and config files in the .aws directory in your home folder.
The contents of these files are practically interchangeable, but CloudQuery will prioritize credentials in the credentials file.For information about obtaining credentials, see the
AWS guide.
Here are example contents for a
credentials file:[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEYYou can also specify credentials for a different profile, and instruct CloudQuery to use the credentials from this profile instead of the default one.
For example:
[myprofile]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEYThen, you can either export the
AWS_PROFILE environment variable (On Linux/Mac, similar for Windows):export AWS_PROFILE=myprofileÂ
IAM Roles for AWS Compute Resources #
The plugin can use IAM roles for AWS compute resources (including EC2 instances, Fargate and ECS containers).
If you configured your AWS compute resources with IAM, the plugin will use these roles automatically.
For more information on configuring IAM, see the AWS docs here and here.
User Credentials with MFA #
In order to leverage IAM User credentials with MFA, the STS "get-session-token" command may be used with the IAM User's long-term security credentials (Access Key and Secret Access Key). For more information, see here.
aws sts get-session-token --serial-number <YOUR_MFA_SERIAL_NUMBER> --token-code <YOUR_MFA_TOKEN_CODE> --duration-seconds 3600Then export the temporary credentials to your environment variables.
export AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
export AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
export AWS_SESSION_TOKEN=<YOUR_SESSION_TOKEN>Incremental Syncing #
The S3 plugin supports incremental syncing. This means that only new files will be fetched from S3 and loaded into your destination. This is done by keeping track of the time of the last sync and comparing it against the last modified date of each file to only fetch new files. This assumes that S3 files are immutable.
To enable this,
backend_options must be set in the spec (as shown below). This is documented in the Managing Incremental Tables section.Configuration #
kind: source
spec:
name: s3
path: cloudquery/s3
registry: cloudquery
version: "v1.8.5"
tables: ["*"]
destinations: ["postgresql"]
backend_options:
table_name: "cq_state_s3"
connection: "@@plugins.postgresql.connection"
# Learn more about the configuration options at https://cql.ink/s3_source
spec:
# TODO: Update it with the actual spec
bucket: "<BUCKET_NAME>"
region: "<REGION>"
# Optional parameters
# path_prefix: ""
# rows_per_record: 500
# concurrency: 50S3 spec #
This is the (nested) spec used by the S3 source plugin.
bucket(string) (required)The name of the S3 bucket that will be synced.region(string) (required)The AWS region of the S3 bucket.local_profile(string) (optional) (default: will use current credentials)Local profile to use to authenticate this account with. Please note this should be set to the name of the profile.For example, with the following credentials file:[default] aws_access_key_id=xxxx aws_secret_access_key=xxxx [user1] aws_access_key_id=xxxx aws_secret_access_key=xxxxlocal_profileshould be set to eitherdefaultoruser1.path_prefix(string) (optional) (default:"")The path prefix that will limit the files to sync.filetype(string) (optional) (default:parquet)Type of file that will be synced. Currently onlyparquetis supported.rows_per_record(integer) (optional) (default:500)Amount of rows to be packed into a single Apache Arrow record to be sent over the wire during sync.concurrency(integer) (optional) (default:50)Number of objects to sync in parallel. Negative values mean no limit.