< Rocky> I am using a workload identity in my Azure deployme StarRocks #questions-and-troubleshooting

<@U0A71G31CDV> I am using a workload identity in m...

Guillaume Bienkowski

06/22/2026, 1:31 PM

@Rocky I am using a workload identity in my Azure deployment, all pods have the appropriate AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE and AZURE_AUTHORITY_HOST env variables. How can I setup a storage volume with this so that it uses the blob storage I have (AZBLOB)? If not possible, please advise on how to do so with ADLS2 (but I'd rather use Blob)

Rocky

06/22/2026, 1:32 PM

To set up a storage volume using Azure Workload Identity (federated tokens), the most reliable and officially supported method is using ADLS2 (available from StarRocks version 3.5.10). While you prefer AZBLOB, current StarRocks documentation only explicitly lists Managed Identity (VM-level) and Service Principal (secret-based) for the

AZBLOB

storage volume type. There is no documented

token_file

property for

AZBLOB

to consume the federated token injected into your pods. Recommended Configuration (ADLS2) For pods carrying the

AZURE_FEDERATED_TOKEN_FILE

and other identity variables, use the following

CREATE STORAGE VOLUME

syntax. Note that the

ADLS2

type uses the

abfss://

protocol.

Copy code

sql
CREATE STORAGE VOLUME my_azure_volume
TYPE = ADLS2
LOCATIONS = ("abfss://<container>@<storage_account>.<http://dfs.core.windows.net/<path>/%22|dfs.core.windows.net/<path>/">)
PROPERTIES (
    "enabled" = "true",
    "azure.adls2.endpoint" = "https://<storage_account>.<http://dfs.core.windows.net|dfs.core.windows.net>",
    "azure.adls2.oauth2_tenant_id" = "<your_tenant_id>", -- from AZURE_TENANT_ID
    "azure.adls2.oauth2_client_id" = "<your_client_id>", -- from AZURE_CLIENT_ID
    "azure.adls2.oauth2_token_file" = "/var/run/secrets/azure/tokens/azure-identity-token" -- from AZURE_FEDERATED_TOKEN_FILE
);

Regarding AZBLOB If you must use

AZBLOB

(flat namespace), StarRocks supports Managed Identity (VM-level) starting from version 3.4.4. Because StarRocks uses the Azure Native SDK (when

azure_use_native_sdk = true

, which is the default), it may theoretically pick up your pod-level environment variables if you use the following properties, but this is not explicitly documented as "Workload Identity" support for the

AZBLOB

type:

Copy code

sql
CREATE STORAGE VOLUME my_blob_volume
TYPE = AZBLOB
LOCATIONS = ("azblob://<container>/<path>/")
PROPERTIES (
    "enabled" = "true",
    "azure.blob.endpoint" = "https://<storage_account>.<http://blob.core.windows.net|blob.core.windows.net>",
    "azure.blob.oauth2_use_managed_identity" = "true",
    "azure.blob.oauth2_client_id" = "<your_client_id>"
);

Warning: In many cases, the

AZBLOB

implementation (using the

wasbs

protocol) defaults to checking the Node/VM identity (IMDS) and may ignore the pod-level federated token unless a specific

token_file

property is provided (which only exists for

ADLS2

currently). Key Requirements * StarRocks Version: Ensure you are on v3.5.10 or later for the

azure.adls2.oauth2_token_file

property. * FE Configuration: Ensure

azure_use_native_sdk

is set to

true

(default in 3.4.4+) in your

fe.conf

. * Azure Side: The User-Assigned Managed Identity (UAMI) must have the Storage Blob Data Contributor role on the storage account. References • administration/management/FE_configuration.md • sql-reference/sql-functions/table-functions/files.md • integrations/authenticate_to_azure_storage.md

Guillaume Bienkowski

06/22/2026, 1:53 PM

@Rocky I was able to create a storage volume like this;

Copy code

CREATE STORAGE VOLUME wi
TYPE = AZBLOB
LOCATIONS = ("<azblob://starrocks-testwi/data>")
PROPERTIES (
 "enabled" = "true",
 "azure.blob.endpoint" = "<https://xxx.privatelink.blob.core.windows.net>",
 "azure.blob.oauth2_use_managed_identity" = "true",
 "azure.blob.oauth2_client_id" = "xxx"
);

And it worked, but now I cannot `SHOW STORAGE VOLUMES`: > ERROR 1064 (HY000): Getting analyzing error. Detail message: Storage params is not valid {"azure.blob.endpoint":"https://xx.blob.core.windows.net"}.

Rocky

06/22/2026, 1:53 PM

CREATE STORAGE VOLUME

appeared to work (returned

Query OK

) but

SHOW STORAGE VOLUMES

returns an empty set or an error, there are a few likely causes related to cluster configuration and how StarRocks handles Azure Blob Storage properties. 1. Check your
run_mode
(Shared-Data vs. Shared-Nothing) Storage Volumes are primarily designed for Shared-Data (cloud-native) clusters. * If you are in Shared-Data mode:

SHOW STORAGE VOLUMES

should show the volume you just created. * If you are in Shared-Nothing mode: While the SQL syntax for

CREATE STORAGE VOLUME

might be accepted by the parser, the feature is not fully supported for data persistence in shared-nothing clusters. In some versions,

SHOW

may return an empty set if the cluster is not initialized in

shared_data

mode. _ _Verification:* Run

ADMIN SHOW FRONTEND CONFIG LIKE 'run_mode';

. It must be

shared_data

. 2. Property Name Mismatch for AZBLOB The properties you used (

azure.blob.oauth2_use_managed_identity

and

azure.blob.oauth2_client_id

) are likely not being recognized for the

AZBLOB

type. In StarRocks, Azure property prefixes are strict: _

AZBLOB

type uses the prefix

azure.blob._

ADLS2

type uses the prefix

azure.adls2._

While the Azure Native SDK (v3.4.4+) supports Managed Identity, the official property keys for Federated Identity (Workload Identity) are currently only documented and validated for the ADLS2 type. For

AZBLOB

, StarRocks generally expects a

shared_key

sas_token

. If you used "Workload Identity" property names that the

AZBLOB

handler doesn't recognize, the

CREATE

statement might have succeeded without actually persisting a valid configuration. 3. Recommendations To fix this and ensure the volume is visible and functional with your identity setup: Option A: Use ADLS2 (Recommended for Workload Identity) This is the only type with an explicit

oauth2_token_file

property to support the Federated Token injected by Kubernetes.

Copy code

sql
CREATE STORAGE VOLUME wi_adls
TYPE = ADLS2
LOCATIONS = ("abfss://<container>@<account>.<http://dfs.core.windows.net/data%22|dfs.core.windows.net/data">)
PROPERTIES (
    "enabled" = "true",
    "azure.adls2.endpoint" = "https://<account>.<http://dfs.core.windows.net|dfs.core.windows.net>",
    "azure.adls2.oauth2_use_managed_identity" = "true",
    "azure.adls2.oauth2_tenant_id" = "xxx", -- from AZURE_TENANT_ID
    "azure.adls2.oauth2_client_id" = "xxx", -- from AZURE_CLIENT_ID
    "azure.adls2.oauth2_token_file" = "/var/run/secrets/azure/tokens/azure-identity-token" -- from AZURE_FEDERATED_TOKEN_FILE
);

Option B: Force Native SDK for AZBLOB If you must use

AZBLOB

, ensure your

fe.conf

has

azure_use_native_sdk = true

(default in 3.4.4+). However, without the

token_file

property, it may default to the VM's Managed Identity rather than the Pod's Workload Identity. 4. Troubleshooting Steps 1. Check FE Logs: Look at

fe.log

and

fe.warn.log

immediately after running the

CREATE

and

SHOW

commands. It will often show a "Property not supported" or "Storage volume not found" error that explains the empty result. 2. Verify Leader: Ensure you are connected to the Leader FE node, as metadata for storage volumes is managed there. 3. Check Version: Ensure you are on at least v3.1 (for Storage Volumes) and ideally v3.4.4+ for Azure Native SDK support. For the specific

token_file

property, v3.5.10 is recommended. References • faq/Sql_faq.md • table_design/table_types/aggregate_table.md • table_design/table_types/primary_key_table.md • table_design/table_types/table_types.md

Rocky

06/22/2026, 1:53 PM

• best_practices/query_tuning/schema_tuning.md

Rocky

06/22/2026, 1:54 PM

The error

Storage params is not valid

during

SHOW STORAGE VOLUMES

and the failure to see your volume are caused by two main issues: a syntax error in your original command and the specific way StarRocks handles Workload Identity for Azure. 1. Fix the Syntax Error (The "Angle Brackets") The immediate reason for the

ERROR 1064 (HY000)

is that you included literal angle brackets (

and

) in your SQL string values (e.g.,

"<https://...>"

). In StarRocks documentation,

<text>

is a placeholder. If you include those characters in the actual SQL, the system fails to validate the endpoint URL when you try to list or describe the volumes. To fix this: You must drop the corrupted volume and recreate it without the brackets:

Copy code

sql
DROP STORAGE VOLUME wi;

2. Setting up Workload Identity (ADLS2 vs. AZBLOB) While you preferred AZBLOB, StarRocks officially introduced support for Azure Workload Identity (federated tokens) starting from version 3.5.10, and it is currently only documented and validated for the ADLS2 storage volume type. For the pod-level environment variables you have (

AZURE_FEDERATED_TOKEN_FILE

, etc.) to work correctly, you should use the

ADLS2

type. Recommended Configuration (ADLS2) Use the following syntax (reusing your existing Client ID and Tenant ID):

Copy code

sql
CREATE STORAGE VOLUME azure_wi
TYPE = ADLS2
LOCATIONS = ("<abfss://starrocks-testwi@xxx.dfs.core.windows.net/data/>")
PROPERTIES (
    "enabled" = "true",
    "azure.adls2.endpoint" = "<https://xxx.dfs.core.windows.net>",
    "azure.adls2.oauth2_tenant_id" = "your_tenant_id",
    "azure.adls2.oauth2_client_id" = "your_client_id",
    -- Point to the token file injected by the Azure Workload Identity webhook
    "azure.adls2.oauth2_token_file" = "/var/run/secrets/azure/tokens/azure-identity-token"
);

Can I use AZBLOB? Currently, the

AZBLOB

type in StarRocks storage volumes supports Managed Identity (VM-level) and Service Principal (Secret-based), but it does not have a documented property for the

oauth2_token_file

required by Workload Identity. If you use

TYPE = AZBLOB

with

azure.blob.oauth2_use_managed_identity = true

, StarRocks will attempt to use the VM's Managed Identity via the Instance Metadata Service (IMDS), which may not match the specific permissions assigned to your Pod's Workload Identity. Summary of Requirements * Version: You must be on StarRocks v3.5.10 or later for the

oauth2_token_file

property. * Protocol: Use

abfss://

and the

.<http://dfs.core.windows.net|dfs.core.windows.net>

endpoint for ADLS2. * Permissions: Ensure your Managed Identity has the Storage Blob Data Contributor role on the storage account. References • sql-reference/sql-statements/table_bucket_part_index/SELECT.md • table_design/table_types/aggregate_table.md • using_starrocks/sorted_aggregate.md • using_starrocks/caching/query_cache.md

3 Views

Open in Slack

Previous Next