Integrate with Azure Blob Storage

This page explains how to authorize a Zilliz Cloud Azure BYOC-I project to access an external Azure Blob Storage container. You register a Microsoft Entra application, establish a federated trust with the BYOC-I AKS workload, and grant the application data access to the target container.

📘Notes

The integration uses an AKS OIDC federated credential. Copy the issuer URL, Kubernetes namespace, and service account name generated by Zilliz Cloud. Do not create or enter a client secret.

Access flow

Before you start

Ensure that:

• Your Azure BYOC-I data plane is running.

• You have Organization Owner or Project Admin access to the Zilliz Cloud project.

• You can register an application and add federated credentials in the target Microsoft Entra tenant.

• You can create Azure role assignments at the target storage scope.

• The storage account is in the same Azure Region as the BYOC-I data plane that will use the integration.

📘Notes

A storage integration is Region-specific. If your project has data planes in multiple Regions, configure a separate storage account or container integration for each Region.

Step 1: Start the integration in Zilliz Cloud

1

Log in to the Zilliz Cloud console.

2

Open your Azure BYOC-I project and select Integrations in the left navigation.

3

Under Azure Blob Storage, click + Integration.

4

Enter a unique Integration Name and, optionally, an Integration Description.

5

Click Next.

Step 2: Specify the external storage account and container

1

In Region, select the Region of the BYOC-I data plane that will access the container.

2

Open Storage accounts in the Azure portal.

3

Select an existing storage account in the same Region, or create one.

4

Under Data storage > Containers, select an existing container or create one.

5

Return to Zilliz Cloud and enter the exact Storage Account Name and Container Name. Do not enter a Blob endpoint URL or path.

6

Click Next.

Step 3: Register an application and add a federated credential

1

Open Microsoft Entra ID > App registrations in the Azure portal and click + New registration.

2

Enter a recognizable name for the integration. A redirect URI is not required.

3

Copy the Application (client) ID and Directory (tenant) ID, and enter them in Zilliz Cloud.

4

In the application, select Certificates & secrets > Federated credentials > + Add credential.

5

For Federated credential scenario, select Kubernetes accessing Azure resources.

6

Copy the following values from Zilliz Cloud. Keep the audience set to api://AzureADTokenExchange.

Azure field	Value from Zilliz Cloud
Cluster issuer URL	<CLUSTER_ISSUER_URL>
Namespace	<NAMESPACE>
Service account name	<SERVICE_ACCOUNT_NAME>

plaintext

Issuer
<CLUSTER_ISSUER_URL>

Subject
system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT_NAME>

Audience
api://AzureADTokenExchange

7

Enter a name for the federated credential and click Add.

📘Notes

A different issuer URL, namespace, service account name, tenant ID, client ID, or audience prevents Microsoft Entra from exchanging the workload token.

Step 4: Grant the application access to Blob Storage

1

In the Azure portal, open the target container and select Access Control (IAM).

2

Click + Add > Add role assignment.

3

On the Role tab, select Job function roles, search for Storage Blob Data Contributor, and click Next.

4

On the Members tab, choose User, group, or service principal. Select the application registered in step 3.

5

Click Review + assign.

Setting	Required value
Role	Storage Blob Data Contributor
Member	The Microsoft Entra application created for this integration
Scope	The target Blob Storage container, following the current Zilliz Cloud console flow

Step 5: Validate and add the integration

1

Return to Zilliz Cloud and click Validate Integration.

2

If you created the role assignment recently, allow time for Azure RBAC propagation and retry validation.

3

When the status changes to Successful, click Add. The Azure Blob Storage integration is now available to supported workflows in the same Zilliz Cloud project and Region.

📘Notes

To verify workload identity and write access, validation uploads a zero-byte object named .zilliz-verify-access to the target container.

Security recommendations

• Create a dedicated Microsoft Entra application and federated credential for this integration.

• Do not create a client secret or certificate. The integration uses AKS OIDC workload identity.

• Grant Storage Blob Data Contributor at the narrowest scope supported by the current integration flow.

• Keep anonymous Blob access disabled.

• If Azure Policy, a resource lock, a storage firewall, private endpoints, or a customer-managed key applies, verify that the BYOC-I data plane can still reach and use the container.

Troubleshooting

Validation result	Likely cause	What to check
AADSTS70021 or no matching federated identity record	The issuer, subject, or audience does not match the AKS service account token.	Copy the issuer URL, namespace, and service account name again from Zilliz Cloud. Confirm the audience is api://AzureADTokenExchange.
AuthorizationPermissionMismatch or HTTP 403	The role is missing, scoped incorrectly, or Azure RBAC has not propagated.	Confirm Storage Blob Data Contributor is assigned to the application's service principal at the target storage scope.
Container not found	The storage account or container name is incorrect.	Enter names only, without https://, .blob.core.windows.net, or a blob path.
Authentication succeeds but storage is unreachable	A storage firewall, private endpoint, DNS configuration, or network policy blocks access.	Verify connectivity from the selected BYOC-I data plane to the storage account endpoint.