AWS

XTDB provides modular support for AWS environments, including a prebuilt Docker image, integrations for S3 storage and CloudWatch metrics, and configuration options for deploying onto AWS infrastructure.

Note	For more information on setting up an XTDB cluster on AWS, see the "Getting Started with AWS" guide.

Required infrastructure

In order to run an AWS based XTDB cluster, the following infrastructure is required:

• An S3 bucket for remote storage.

• A Kafka cluster for transaction logs/file notifications.

  • Within AWS, you can use the Amazon Managed Streaming for Apache Kafka (MSK) service.

  • For more information on setting up Kafka for usage with XTDB, see the Kafka configuration docs.

• IAM policies which grant XTDB permission to the S3 bucket and Kafka cluster.

• XTDB nodes configured to communicate with the Kafka cluster and S3 bucket.

xtdb-aws Docker Image

The xtdb-aws image is optimized for running XTDB in AWS environments, and is deployed on every release to XTDB.

xtdb/xtdb-aws:2.0.0-beta4

By default, it will use S3 for storage and Kafka for transaction logs, including dependencies for both.

Configuration

The following environment variables are used to configure the xtdb-aws image:

Variable	Description
KAFKA_BOOTSTRAP_SERVERS	Kafka bootstrap server containing the XTDB topics.
XTDB_TX_TOPIC	Kafka topic to be used as the transaction log.
XTDB_FILES_TOPIC	Kafka topic to be used for node file notifications.
XTDB_S3_BUCKET	Name of the S3 bucket used for remote storage.
XTDB_LOGGING_LEVEL	Sets the root logging level for the node - defaults to INFO. See "Increasing the Log Level" for more information.
XTDB_NODE_ID	Persistent node id for labelling Prometheus metrics.

Using a Custom Node Configuration

For advanced usage, XTDB allows the above YAML configuration to be overridden to customize the running node’s system/modules.

In order to override the default configuration:

1. Mount a custom YAML configuration file to the container.

2. Override the COMMAND of the docker container to use the custom configuration file, ie:

   CMD ["-f", "/path/to/custom-config.yaml"]

S3 Storage

Amazon S3 can be used as a shared object-store for XTDB’s remote storage module.

Infrastructure Requirements

Note	We provide a parameterized CloudFormation stack to help set up everything that you need. The stack accepts the (globally unique) name of an S3 bucket as an input - this will be created, and referenced in associated resources - to be used in your XTDB configuration.

To use S3 as the object store, the following infrastructure is required:

1. An S3 bucket.

2. IAM policies which grant XTDB permission to the S3 bucket:

   Statement:
   - Effect: Allow
     Action:
       - 's3:GetObject'
       - 's3:PutObject'
       - 's3:DeleteObject'
       - 's3:ListBucket'
       - 's3:AbortMultipartUpload'
       - 's3:ListBucketMultipartUploads'
     Resource:
       - !Ref S3BucketArn
       - !Join [ '', [ !Ref S3BucketArn, '/*'] ]

Authentication

XTDB uses AWS SDK for Authentication, relying on the default AWS credential provider chain. See the AWS documentation for setup instructions.

Configuration

To use the S3 module, include the following in your node configuration:

storage: !Remote
  objectStore: !S3
    ## -- required

    ## The name of the S3 bucket to use for the object store
    ## (Can be set as an !Env value)
    bucket: "my-s3-bucket"

    ## -- optional

    ## A file path to prefix all of your files with
    ## - for example, if "foo" is provided, all XTDB files will be located under a "foo" sub-directory
    ## (Can be set as an !Env value)
    # prefix: my-xtdb-node

    ## Basic credentials for AWS.
    ## If not provided, will default to AWS's standard credential resolution.
    ## see: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html
    # credentials:
    #   accessKey: "..."
    #   secretKey: "..."

    ## Endpoint URI
    ## If not provided, will default to the standard S3 endpoint for the resolved region.
    # endpoint: "https://..."

  localDiskCache: /var/cache/xtdb/object-store

If configured as an in-process node, you can also specify an S3Configurator instance - this is used to modify the requests sent to S3.

CloudWatch Monitoring

XTDB supports reporting metrics to AWS Cloudwatch for performance and health monitoring.

Configuration

To report XTDB node metrics to CloudWatch, include the following in your node configuration:

modules:
  - !CloudWatch

Authentication is handled via the AWS SDK, using the default AWS credential provider chain. See the AWS documentation for setup instructions.

The associated credentials must have permissions to write metrics to a pre-configured CloudWatch namespace.

---