Azure

XTDB provides modular support for Azure environments, including a prebuilt Docker image, integrations with Azure Blob Storage, Application Insights monitoring and configuration options for deploying onto Azure infrastructure.

Note	For more details on getting started with Azure, see the "Getting Started with Azure" guide.

Required infrastructure

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

An Azure Storage Account, containing a Storage Account Container.
A User Assigned Managed Identity for authentication with Azure services.
A Kafka cluster for the message log.
- For more information on setting up Kafka for usage with XTDB, see the Kafka configuration docs.
XTDB nodes configured to communicate with the Kafka cluster and Azure Storage Account/Container.
(On Kubernetes) A Federated Identity Credential setup for the desired Kubernetes Namespace/Service account to give access to the User Assigned Managed Identity.

Terraform Templates

To set up a basic version of the required infrastructure, we provide a set of Terraform templates specifically designed for Azure.

These can be fetched from the XTDB repository using the following command:

terraform init -from-module github.com/xtdb/xtdb.git//azure/terraform

Resources

By default, running the templates will deploy the following infrastructure:

XTDB Resource Group and User Assigned Managed Identity
Azure Storage Account (with a container for object storage)
- Configured with associated resources using the Azure/avm-res-storage-storageaccount Terraform module.
- Adds required permissions to the User Assigned Managed Identity.
AKS Cluster
- Configured with associated resources using the Azure/aks Terraform module.

Configuration

In order to customize the deployment, we provide a number of pre-defined variables within the terraform.tfvars file. These variables can be modified to tailor the infrastructure to your specific needs.

The following variables are required to be set:

storage_account_name: The (globally unique) name of the Azure storage account used by XTDB.

For more advanced usage, the Terraform templates themselves can be modified to suit your specific requirements.

`xtdb-azure` Helm Charts

For setting up a production-ready XTDB cluster on Azure, we provide a Helm chart built specifically for Azure environments.

Pre-requisites

To enable XTDB nodes to access an Azure storage account securely, a Kubernetes Service Account (KSA) must be set up and linked to a User Assigned Managed Identity using Workload Identity Federation.

Setting Up the Kubernetes Service Account:

Create the Kubernetes Service Account in the target namespace:

kubectl create serviceaccount xtdb-service-account --namespace xtdb-deployment

Binding the IAM Service Account

Fetch the name of the User Assigned Managed Identity (user_assigned_managed_identity_name) and the OIDC issuer URL of the AKS cluster (oidc_issuer_url). Create the federated identity using the az CLI:

az identity federated-credential create \
  --name "xtdb-federated-identity" \
  --resource-group "xtdb-resource-group" \
  --subject "system:serviceaccount:xtdb-deployment:xtdb-service-account" \
  --audience "api://AzureADTokenExchange" \
  --identity-name "<user_assigned_managed_identity_name>" \
  --issuer "<oidc_issuer_url>"

The subject name must include the namespace and Kubernetes ServiceAccount name.

Annotating the Kubernetes Service Account

Fetch the client ID of the User Assigned Managed Identity (user_assigned_managed_identity_client_id). Annotate the Kubernetes Service Account to establish the link between the KSA and the User Assigned Managed Identity:

kubectl annotate serviceaccount xtdb-service-account \
  --namespace xtdb-deployment \
  azure.workload.identity/client-id="<user_assigned_managed_identity_client_id>"

Installation

The Helm chart can be installed directly from the Github Container Registry releases.

This will use the default configuration for the deployment, setting any required values as needed:

helm install xtdb-azure oci://ghcr.io/xtdb/helm-xtdb-azure \
  --version 2.0.0-snapshot \
  --namespace xtdb-deployment \
  --set xtdbConfig.serviceAccount="xtdb-service-account" \
  --set xtdbConfig.storageContainerName=<storage_account_container> \
  --set xtdbConfig.storageAccountName=<storage_account_name> \
  --set xtdbConfig.userManagedIdentityClientId=<user_managed_identity_client_id>

We provide a number of parameters for configuring numerous parts of the deployment, see the values.yaml file or call helm show values:

helm show values oci://ghcr.io/xtdb/helm-xtdb-azure \
  --version 2.0.0-snapshot

Resources

By default, the following resources are deployed by the Helm chart:

A StatefulSet containing a configurable number of XTDB nodes, using the xtdb-azure docker image
A PersistentVolumeClaim for each member of the StatefulSet (default size of 50 GiB, default storage class of managed-csi).
A LoadBalancer Kubernetes service to expose the XTDB cluster to the internet.
A ClusterIP service for exposing the Prometheus metrics from the nodes.

Pulling the Chart Locally

The chart can also be pulled from the Github Container Registry, allowing further configuration of the templates within:

helm pull oci://ghcr.io/xtdb/helm-xtdb-azure \
  --version 2.0.0-snapshot \
  --untar

`xtdb-azure` Docker Image

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

By default, it will use Azure Blob Storage for object storage and Kafka for the message log, including dependencies for both.

Configuration

The following environment variables configure the xtdb-azure image:

Variable Description

Variable	Description
`KAFKA_BOOTSTRAP_SERVERS`	Kafka bootstrap server containing the XTDB topics.
`XTDB_LOG_TOPIC`	Kafka topic to be used as the XTDB log.
`XTDB_AZURE_STORAGE_ACCOUNT`	Name of the Azure Storage Account.
`XTDB_AZURE_STORAGE_CONTAINER`	Name of the Azure Storage Container.
`XTDB_AZURE_USER_MANAGED_IDENTITY_CLIENT_ID`	Azure Client ID for the User Assigned Managed Identity used for authentication.
`XTDB_LOCAL_DISK_CACHE`	Path to the local disk cache for object storage.
`XTDB_NODE_ID`	Persistent node id for labelling Prometheus metrics.

KAFKA_BOOTSTRAP_SERVERS

Kafka bootstrap server containing the XTDB topics.

XTDB_LOG_TOPIC

Kafka topic to be used as the XTDB log.

XTDB_AZURE_STORAGE_ACCOUNT

Name of the Azure Storage Account.

XTDB_AZURE_STORAGE_CONTAINER

Name of the Azure Storage Container.

XTDB_AZURE_USER_MANAGED_IDENTITY_CLIENT_ID

Azure Client ID for the User Assigned Managed Identity used for authentication.

XTDB_LOCAL_DISK_CACHE

Path to the local disk cache for object storage.

XTDB_NODE_ID

Persistent node id for labelling Prometheus metrics.

You can also set the XTDB log level using environment variables.

Using the "private auth" Configuration File

For setups requiring private/authenticated Kafka instances, we provide the "private auth" configuration file.

To switch from the default configuration above to the authenticated Kafka configuration, update the COMMAND of the docker container as follows:

CMD ["-f", "azure_config_private_auth.yaml"]

In addition to the standard environment variables, the following environment variables are required for private/authenticated Kafka.

Variable Description

Variable	Description
`KAFKA_SASL_MECHANISM`	SASL mechanism to use for Kafka authentication (e.g., `PLAIN`).
`KAFKA_SECURITY_PROTOCOL`	Security protocol for Kafka (e.g., `SASL_SSL`).
`KAFKA_SASL_JAAS_CONFIG`	JAAS configuration for Kafka SASL authentication, (e.g. `org.apache.kafka.common.security.plain.PlainLoginModule required username="user" password="password";`).
`XTDB_AZURE_STORAGE_ACCOUNT_ENDPOINT`	The full endpoint of the storage account which has the storage container.

KAFKA_SASL_MECHANISM

SASL mechanism to use for Kafka authentication (e.g., PLAIN).

KAFKA_SECURITY_PROTOCOL

Security protocol for Kafka (e.g., SASL_SSL).

KAFKA_SASL_JAAS_CONFIG

JAAS configuration for Kafka SASL authentication, (e.g. org.apache.kafka.common.security.plain.PlainLoginModule required username="user" password="password";).

XTDB_AZURE_STORAGE_ACCOUNT_ENDPOINT

The full endpoint of the storage account which has the storage container.

Note	We would strongly recommend users mount the `KAFKA_SASL_JAAS_CONFIG` env as a secret on the container.

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:

Mount a custom YAML configuration file to the container.
Override the COMMAND of the docker container to use the custom configuration file, ie:
```
CMD ["-f", "/path/to/custom-config.yaml"]
```

Azure Blob Storage

Azure Blob Storage can be used as a shared object-store for XTDB’s remote storage module.

Infrastructure Requirements

To use Azure Blob Storage as the object store, the following infrastructure is required:

An Azure Storage Account, containing a Storage Account Container.
Appropriate permissions for the storage account:

{
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/blobServices/containers/write",
        "Microsoft.Storage/storageAccounts/blobServices/containers/delete",
        "Microsoft.Storage/storageAccounts/blobServices/containers/read"
      ],
      "notActions": [],
      "dataActions": [
        "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read",
        "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write",
        "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete",
        "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action",
        "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/move/action"
      ],
      "notDataActions": []
    }
  ]
}

Authentication

XTDB uses the Azure SDK for authentication, relying on the DefaultAzureCredential. This supports multiple authentication methods, including Managed Identity. For more details, refer to the Azure Documentation.

Configuration

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

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

    # --- At least one of storageAccount or storageAccountEndpoint is required

    # The name of the storage account which has the storage container
    # (Can be set as an !Env value)
    storageAccount: storage-account

    # The full endpoint of the storage account which has the storage container
    # (Can be set as an !Env value)
    # storageAccountEndpoint: https://storage-account.privatelink.blob.core.windows.net

    # The name of the blob storage container to be used as the object store
    # (Can be set as an !Env value)
    container: xtdb-container

    # -- 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
    #
    # Azure Client ID of a User Assigned Managed Identity -
    # required when using them for authentication to Azure Services ie, inside of an Azure App Container.
    # (Can be set as an !Env value)
    # userManagedIdentityClientId: user-managed-identity-client-id

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

Application Insights Monitoring

XTDB supports reporting metrics to Azure Application Insights for performance and health monitoring.

Configuration

To enable Application Insights monitoring, include the following in your node configuration:

modules:
  - !AzureMonitor
    # -- required
    connectionString: !Env XTDB_AZURE_APP_INSIGHTS_CONNECTION_STRING

Azure

Required infrastructure

Terraform Templates

Resources

Configuration

xtdb-azure Helm Charts

Pre-requisites

Setting Up the Kubernetes Service Account:

Binding the IAM Service Account

Annotating the Kubernetes Service Account

Installation

Resources

Pulling the Chart Locally

xtdb-azure Docker Image

Configuration

Using the "private auth" Configuration File

Using a Custom Node Configuration

Azure Blob Storage

Infrastructure Requirements

Authentication

Configuration

Application Insights Monitoring

Configuration

`xtdb-azure` Helm Charts

`xtdb-azure` Docker Image