Binary Store component specs
The supported binary stores that interface with Dapr
The following table lists the components supported by the Binary Store building block. For instructions on using the building block, see the Binary Store how-to guide.
| Component | Component type | Status | Description |
|---|
| In-memory | binarystore.in-memory | Alpha | Volatile store for local development and testing. |
| AWS S3 | binarystore.aws.s3 | Alpha | Amazon S3 and S3-compatible object storage. |
| Azure Blob Storage | binarystore.azure.blobstorage | Alpha | Azure Blob Storage containers. |
| Azure Data Lake Storage Gen2 | binarystore.azure.datalake | Alpha | Azure Data Lake Storage Gen2 filesystems. |
| Google Cloud Storage | binarystore.gcp.bucket | Alpha | Google Cloud Storage buckets. |
| OCI Object Storage | binarystore.oci.objectstorage | Alpha | Oracle Cloud Infrastructure Object Storage buckets. |
The Binary Store API is currently alpha. See the component certification lifecycle for details about component status.
1 - AWS S3
Configuration for the AWS S3 and S3-compatible Binary Store component
The AWS S3 Binary Store stores files as objects in an Amazon S3 bucket. It can also connect to S3-compatible services such as MinIO, Ceph, or Cloudflare R2. The component is alpha and uses Dapr’s built-in AWS authentication profile.
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: s3-files
spec:
type: binarystore.aws.s3
version: v1
metadata:
- name: bucket
value: "binary-files"
- name: prefix
value: "uploads"
Configure AWS credentials for the sidecar through the AWS authentication profile and your AWS environment or workload identity. Avoid putting access keys directly in the component manifest.
| Field | Required | Details | Example |
|---|
bucket | Y | Name of the S3 bucket. The component needs s3:PutObject and s3:DeleteObject; it also needs s3:GetObject for retrieval and delete existence checks. To report a missing object as not found during deletion, grant s3:ListBucket as well. Without the permissions needed for the existence check, deletion may report success without determining whether the object existed. | "binary-files" |
prefix | N | Prefix prepended to each file name. If configured, it must not start with /. | "uploads" |
partSize | N | Multipart upload part size, specified as a byte count or byte-size string. Defaults to 16Mi; must be between 5 MiB and 5 GiB. S3 limits uploads to 10,000 parts; larger parts can increase the maximum upload size (up to 50 TB) but use more memory per in-flight upload. | "64Mi" |
endpoint | N | Custom endpoint for an S3-compatible service or emulator. Do not set this for production Amazon S3. | "http://localhost:9000" |
forcePathStyle | N | Defaults to false (virtual-hosted style). Set to true to use path-style requests; many S3-compatible services require it. | "true" |
disableSSL | N | Defaults to false. Allows connecting to a non-HTTPS endpoint. | "true" |
insecureSSL | N | Defaults to false. Accepts self-signed or invalid certificates for HTTPS endpoints. This weakens transport security. | "true" |
Size values can be provided as a string containing the number of bytes (for example, "16777216") or as a size with a unit such as "16Mi".
Warning
When creating a file without overwrite enabled, the component relies on the endpoint honoring conditional writes (If-None-Match). AWS S3 supports this behavior, but some S3-compatible providers may ignore the condition and overwrite an existing object. Verify that your provider supports conditional writes before relying on this behavior to protect existing data.2 - Azure Blob Storage
Configuration for the Azure Blob Storage Binary Store component
The Azure Blob Storage Binary Store stores each file as a blob in the configured container. The component is alpha.
The following example authenticates with a connection string:
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: azure-files
spec:
type: binarystore.azure.blobstorage
version: v1
metadata:
- name: connectionString
value: "<AZURE_STORAGE_CONNECTION_STRING>"
- name: containerName
value: "binary-files"
Warning
The example shows a connection string as a plain value. Use a
Dapr secret store to keep credentials out of component manifests.
Authentication
The component supports three authentication methods:
- Connection string: provide
connectionString. - Account key: provide
accountName and accountKey. - Microsoft Entra ID: provide
accountName and configure credentials for the sidecar’s environment. Supported credential types include workload identity, managed identity, client secret, and certificate. See Authenticating to Azure.
| Field | Required | Details | Example |
|---|
connectionString | Y for connection-string authentication | Azure Blob Storage connection string. | "DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=<key>;EndpointSuffix=core.windows.net" |
accountName | Y for account-key and Entra ID authentication | Storage account name. | "mystorageaccount" |
accountKey | Y for account-key authentication | Base64-encoded primary or secondary storage account key. | "<base64-encoded-key>" |
containerName | Y | Name of the Blob Storage container to use. | "binary-files" |
publicAccessLevel | N | Access level for data in the container: none, blob, or container. Defaults to none. | "none" |
prefix | N | Prefix prepended to each file name. If configured, it must not start with /. | "uploads" |
partSize | N | Upload block size, specified as a byte count or byte-size string. Defaults to 16Mi; must be between 1 byte and 4000 MiB. Block blobs are limited to 50,000 blocks; larger blocks increase the maximum upload size but use more memory per in-flight upload. | "64Mi" |
endpoint | N | Custom endpoint URL, for example an Azurite emulator or a custom storage domain. | "http://127.0.0.1:10000" |
retryCount | N | Maximum number of HTTP retries for transient failures. Defaults to 3. | "5" |
disableEntityManagement | N | Defaults to false. When true, the component does not try to create the container during initialization; pre-create it and grant the identity read/write access. | "true" |
Size values can be provided as a string containing the number of bytes (for example, "16777216") or as a size with a unit such as "16Mi".
Keep publicAccessLevel set to its default unless public access is specifically required.
3 - Azure Data Lake Storage Gen2
Configuration for the Azure Data Lake Storage Gen2 Binary Store component
The Azure Data Lake Storage Gen2 Binary Store stores each file in the configured filesystem. The component is alpha.
The following example authenticates with a connection string:
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: data-lake-files
spec:
type: binarystore.azure.datalake
version: v1
metadata:
- name: connectionString
value: "<AZURE_STORAGE_CONNECTION_STRING>"
- name: fileSystemName
value: "binary-files"
Warning
The example shows a connection string as a plain value. Use a
Dapr secret store to keep credentials out of component manifests.
Authentication
The component supports three authentication methods:
- Connection string: provide
connectionString. - Account key: provide
accountName and accountKey. - Microsoft Entra ID: provide
accountName and configure credentials for the sidecar’s environment. Supported credential types include workload identity, managed identity, client secret, and certificate. See Authenticating to Azure.
| Field | Required | Details | Example |
|---|
connectionString | Y for connection-string authentication | Azure Storage connection string. | "DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=<key>;EndpointSuffix=core.windows.net" |
accountName | Y for account-key and Entra ID authentication | Storage account name. | "mystorageaccount" |
accountKey | Y for account-key authentication | Base64-encoded primary or secondary storage account key. | "<base64-encoded-key>" |
fileSystemName | Y | Name of the Data Lake Storage Gen2 filesystem to use. | "binary-files" |
prefix | N | Prefix prepended to each file name. If configured, it must not start with /. | "uploads" |
partSize | N | Upload chunk size, specified as a byte count or byte-size string. Defaults to 16Mi; must be between 1 byte and 4000 MiB. Larger chunks reduce request overhead but use more memory per in-flight upload. The maximum file size remains 5 TB. | "64Mi" |
retryCount | N | Maximum number of HTTP retries for transient failures. Defaults to 3. | "5" |
endpoint | N | Custom endpoint URL. | "https://mystorageaccount.dfs.core.windows.net" |
disableEntityManagement | N | Defaults to false. When true, the component does not try to create the filesystem during initialization; pre-create it and grant the identity read/write access. | "true" |
Size values can be provided as a string containing the number of bytes (for example, "16777216") or as a size with a unit such as "16Mi".
4 - Google Cloud Storage Bucket
Configuration for the Google Cloud Storage Binary Store component
The Google Cloud Storage Binary Store stores each file as an object in the configured bucket. The component is alpha and uses Dapr’s built-in GCP authentication profile.
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: gcp-files
spec:
type: binarystore.gcp.bucket
version: v1
metadata:
- name: bucket
value: "binary-files"
- name: prefix
value: "uploads"
Configure credentials for the sidecar using Google Cloud’s Application Default Credentials or an appropriate workload identity. Do not store service account keys directly in the component manifest.
| Field | Required | Details | Example |
|---|
bucket | Y | Name of the Google Cloud Storage bucket to use. | "binary-files" |
prefix | N | Prefix prepended to each file name. If configured, it must not start with /. | "uploads" |
partSize | N | Resumable upload chunk size, specified as a byte count or byte-size string. Defaults to 16Mi and must be a positive multiple of 256 KiB. Larger chunks reduce request overhead but use more memory per in-flight upload. The maximum object size remains 5 TiB. | "64Mi" |
Size values can be provided as a string containing the number of bytes (for example, "16777216") or as a size with a unit such as "16Mi".
5 - In-memory
Configuration for the in-memory Binary Store component
The in-memory Binary Store keeps files in the Dapr sidecar process. It is useful for local development, tests, and demos, but it is not durable: data is not written to disk, is lost when the process stops, and is not shared between sidecar instances.
Create a component of type binarystore.in-memory:
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: local-files
spec:
type: binarystore.in-memory
version: v1
metadata:
- name: prefix
value: "uploads"
- name: maxSize
value: "8Mi"
- name: maxTotalSize
value: "1Gi"
For example, an application request for report.pdf is stored under the component’s uploads prefix. The prefix is optional.
| Field | Required | Details | Example |
|---|
prefix | N | Optional prefix prepended to each file name in the store. If configured, it must not start with /. | "uploads" |
maxSize | N | Maximum size of a single file, specified as a byte count or byte-size string. Defaults to 4Mi; uploads larger than the limit are rejected. Must be greater than zero. | "8Mi" |
maxTotalSize | N | Maximum combined size of stored files and in-flight uploads, specified as a byte count or byte-size string. Defaults to 512Mi; uploads that exceed the limit are rejected. Replacing a file temporarily requires capacity for both the old and new content. Must be greater than zero. | "1Gi" |
Size values can be provided as a string containing the number of bytes (for example, "16777216") or as a size with a unit such as "16Mi".
6 - OCI Object Storage
Configuration for the OCI Object Storage Binary Store component
The OCI Object Storage Binary Store stores each file as an object in the configured bucket. The component is alpha.
The following example authenticates using an OCI configuration file:
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: oci-files
spec:
type: binarystore.oci.objectstorage
version: v1
metadata:
- name: configFileAuthentication
value: "true"
- name: configFilePath
value: "/home/app/.oci/config"
- name: configFileProfile
value: "DEFAULT"
- name: bucketName
value: "binary-files"
- name: compartmentOCID
value: "<COMPARTMENT_OCID>"
- name: namespace
value: "<OBJECT_STORAGE_NAMESPACE>"
The configuration file must be available at the specified path inside the sidecar’s environment. Protect credentials in the file using your deployment’s secret-management practices.
Authentication
The component supports three authentication methods:
- API key: provide
region, userOCID, fingerPrint, privateKey, and tenancyOCID. - Instance principal: set
instancePrincipalAuthentication to "true" and grant the compute instance’s dynamic group the required Object Storage permissions. - Configuration file: set
configFileAuthentication to "true" and provide configFilePath. Optionally select a profile with configFileProfile.
Only configure one authentication method for a component. For details, see the OCI documentation for instance principals and SDK configuration files.
| Field | Required | Details | Example |
|---|
bucketName | Y | Name of the OCI Object Storage bucket. | "binary-files" |
compartmentOCID | Y | OCID of the compartment containing the bucket. | "ocid1.compartment.oc1..example" |
namespace | N | OCI Object Storage namespace. If omitted, the component resolves it from the tenancy. | "my-namespace" |
prefix | N | Prefix prepended to each file name. If configured, it must not start with /. | "uploads" |
partSize | N | Multipart upload part size, specified as a byte count or byte-size string. Defaults to 16Mi; must be between 10 MiB and 50 GiB. OCI limits uploads to 10,000 parts; larger parts can increase the maximum upload size (up to 10 TiB) but use more memory per in-flight upload. | "64Mi" |
region | Y for API key authentication | OCI region where the bucket is located. | "us-ashburn-1" |
userOCID | Y for API key authentication | OCID of the OCI user. | "ocid1.user.oc1..example" |
fingerPrint | Y for API key authentication | Fingerprint of the API key. | "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" |
privateKey | Y for API key authentication | Private key for API authentication. Treat this value as a secret. | "<PRIVATE_KEY>" |
tenancyOCID | Y for API key authentication | OCID of the tenancy. | "ocid1.tenancy.oc1..example" |
instancePrincipalAuthentication | Y when using instance principal | Set to "true" to use instance principal authentication. Defaults to "false". | "true" |
configFileAuthentication | Y when using a configuration file | Set to "true" to use configuration file authentication. Defaults to "false". | "true" |
configFilePath | Y when using a configuration file | Absolute path to the OCI configuration file. | "/home/app/.oci/config" |
configFileProfile | N | Optional profile name in the configuration file. The metadata default is empty; use "DEFAULT" to select that profile explicitly. | "DEFAULT" |
Size values can be provided as a string containing the number of bytes (for example, "16777216") or as a size with a unit such as "16Mi".