This is an automated email from the ASF dual-hosted git repository.
laskoviymishka pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git
The following commit(s) were added to refs/heads/main by this push:
new 5d377f16b docs(io): document ADLS managed identity property divergence
(#2024)
5d377f16b is described below
commit 5d377f16bc3a5da0abd59a80204e73698bde7af2
Author: Revanth <[email protected]>
AuthorDate: Wed Sep 23 16:27:33 2026 -0500
docs(io): document ADLS managed identity property divergence (#2024)
* docs(io): document ADLS managed identity property divergence
* docs(io): clarify ADLS authentication precedence and property
* docs(io): clarify ADLS auth precedence and cross-client property
differences
---
io/config.go | 28 +++++++++++++++++++++++++++-
website/src/configuration.md | 31 ++++++++++++++++++++++---------
2 files changed, 49 insertions(+), 10 deletions(-)
diff --git a/io/config.go b/io/config.go
index 35189c15b..39a6602d3 100644
--- a/io/config.go
+++ b/io/config.go
@@ -54,11 +54,37 @@ const (
ADLSConnectionStringPrefix = "adls.connection-string."
ADLSSharedKeyAccountName = "adls.auth.shared-key.account.name"
ADLSSharedKeyAccountKey = "adls.auth.shared-key.account.key"
- ADLSClientID = "adls.client-id"
ADLSEndpoint = "adls.endpoint"
ADLSProtocol = "adls.protocol"
+
+ // ADLSManagedIdentityEnabled uses ManagedIdentityCredential directly
when set
+ // to "true", rather than the broader DefaultAzureCredential chain,
which already
+ // tries managed identity among its other sources. Pair it with
ADLSClientID to
+ // select a user-assigned managed identity; on its own it uses the
system-assigned
+ // managed identity.
+ //
+ // It is evaluated only after shared-key credentials, a SAS-token
property for
+ // the target hostname, and a connection-string property for the target
account
+ // name, all of which take precedence over it; if any of them is
configured,
+ // this flag has no effect.
+ //
+ // This property is specific to this implementation. Neither the Java
nor the
+ // PyIceberg implementation defines an equivalent property, so catalog
properties
+ // that set it will not carry over to them.
ADLSManagedIdentityEnabled = "adls.auth.managed-identity.enabled"
+ // ADLSClientID selects a user-assigned managed identity by client ID.
It only
+ // takes effect when ADLSManagedIdentityEnabled is "true"; on its own
it is ignored.
+ //
+ // PyIceberg recognizes the same "adls.client-id" key but uses it for
service
+ // principal authentication, alongside "adls.client-secret" and
"adls.tenant-id",
+ // which it requires to be set together; see
+ // https://py.iceberg.apache.org/configuration/#azure-data-lake. This
+ // implementation defines neither of those, so the key is only ever
read as a
+ // user-assigned managed identity ID here. Java's AzureProperties
defines no
+ // "adls.client-id" at all.
+ ADLSClientID = "adls.client-id"
+
// Not in use yet
// ADLSReadBlockSize = "adls.read.block-size-bytes"
// ADLSWriteBlockSize = "adls.write.block-size-bytes"
diff --git a/website/src/configuration.md b/website/src/configuration.md
index 87a7f08be..f722901f2 100644
--- a/website/src/configuration.md
+++ b/website/src/configuration.md
@@ -204,12 +204,25 @@ Tuning properties:
### Azure Data Lake Storage / Blob
-Authentication is selected based on the property keys present
(`io/gocloud/azure/azure.go`):
-
-1. Shared key: both `adls.auth.shared-key.account.name` and
`adls.auth.shared-key.account.key` set.
-2. Per-host SAS token: `adls.sas-token.<hostname>` (prefix-matched against the
storage account host).
-3. Per-host connection string: `adls.connection-string.<hostname>`.
-4. Managed identity: `adls.auth.managed-identity.enabled` set to a truthy
value.
+Authentication is selected in the following order
(`io/gocloud/azure/azure.go`); the first applicable option wins, and if none of
1-4 apply the default credential chain (5) is used:
+
+1. Shared key: a nonempty `adls.auth.shared-key.account.name` selects this
path and requires a nonempty `adls.auth.shared-key.account.key`.
+2. Per-host SAS token: `adls.sas-token.<hostname>`, where `<hostname>` exactly
matches the storage account hostname (for example,
`myaccount.dfs.core.windows.net`).
+3. Per-account connection string: `adls.connection-string.<account-name>` (for
example, `adls.connection-string.myaccount`).
+4. Managed identity: `adls.auth.managed-identity.enabled` set to exactly
`"true"` selects this path and uses `ManagedIdentityCredential` directly. Set
`adls.client-id` to select a user-assigned managed identity; otherwise, the
system-assigned managed identity is used.
+5. Default credential chain: `DefaultAzureCredential`, which includes managed
identity among its credential sources.
+
+> **Note on cross-client parity.** The two properties in step 4 diverge from
the
+> other clients. `adls.auth.managed-identity.enabled` is Go-specific: neither
+> Iceberg Java nor PyIceberg defines a property that forces
+> `ManagedIdentityCredential`, so catalog properties that set it do not carry
+> over. `adls.client-id` collides in name only — PyIceberg reads it as a
service
+> principal client ID used together with `adls.client-secret` and
+> `adls.tenant-id`, neither of which iceberg-go defines (see the
+> [PyIceberg ADLS
configuration](https://py.iceberg.apache.org/configuration/#azure-data-lake)),
+> while Java's `AzureProperties` defines no `adls.client-id` at all. Here it is
+> only ever read as a user-assigned managed identity ID, and only when step 4
is
+> selected.
Tuning properties:
@@ -218,11 +231,11 @@ Tuning properties:
| `adls.auth.shared-key.account.name` (`io.ADLSSharedKeyAccountName`) |
Account name. |
| `adls.auth.shared-key.account.key` (`io.ADLSSharedKeyAccountKey`) | Account
key. |
| `adls.sas-token.<host>` (prefix `io.ADLSSasTokenPrefix`) | Per-host SAS
token. |
-| `adls.connection-string.<host>` (prefix `io.ADLSConnectionStringPrefix`) |
Per-host connection string. |
-| `adls.client-id` (`io.ADLSClientID`) | Client/application ID for AAD auth. |
+| `adls.connection-string.<account-name>` (prefix
`io.ADLSConnectionStringPrefix`) | Per-account connection string. |
+| `adls.client-id` (`io.ADLSClientID`) | Client ID of a user-assigned managed
identity. Used only when the explicit managed-identity authentication path is
selected. |
| `adls.endpoint` (`io.ADLSEndpoint`) | Storage domain (e.g.
`blob.core.windows.net`). |
| `adls.protocol` (`io.ADLSProtocol`) | `http` or `https`. |
-| `adls.auth.managed-identity.enabled` (`io.ADLSManagedIdentityEnabled`) |
Enable Azure Managed Identity auth. |
+| `adls.auth.managed-identity.enabled` (`io.ADLSManagedIdentityEnabled`) | Set
to exactly `"true"` to use `ManagedIdentityCredential` directly, subject to the
precedence above. |
## Environment variables
