Package org.elasticsearch.xpack.esql.datasources.spi

Class FileDataSourceConfiguration

java.lang.Object

org.elasticsearch.xpack.esql.datasources.spi.DataSourceConfiguration

org.elasticsearch.xpack.esql.datasources.spi.FileDataSourceConfiguration

public abstract class FileDataSourceConfiguration
extends DataSourceConfiguration

Base configuration for file-based external sources (S3, GCS, Azure). Handles the auth mode and the cross-field rules that bind it to the credential fields.

auth is an explicit mode switch with these canonical values:

• auto (the default when auth is omitted) — resolve the mode from the fields present: federated authentication settings → federated_identity, a stored secret → static_credentials (the auth value itself stays auto and is not rewritten). A credential-less auto config is unresolvable and is rejected at create time by validate(org.elasticsearch.common.ValidationException) — not deferred to the storage provider. Never resolves to anonymous or managed_identity — those are opt-in only.
• anonymous — public / unauthenticated access (no credentials).
• static_credentials — a stored long-lived secret.
• federated_identity — issuer-minted OIDC federation (federated settings such as a role ARN + audience).
• managed_identity — the node's ambient cloud identity (instance profile / IMDS / metadata server); gated by a cluster setting.

Backwards compatibility: the former value names none and workload_identity are still accepted, canonicalized to anonymous and managed_identity on parse (so a stored configuration and every later read hold the canonical value), and each use emits a deprecation warning. See normalize(Map) and DEPRECATED_AUTH_ALIASES.

Credential-conflict detection is automatic — any field marked secret or federated auth that has a value set is treated as an authentication setting, and the two kinds cannot be combined.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	FileDataSourceConfiguration.AuthMode	The resolved credential-selection mode a provider builds a mechanism for.

Field Summary

Fields

Modifier and Type	Field	Description
protected static final DataSourceConfigDefinition	AUTH
static final String	MANAGED_IDENTITY_DISABLED_MESSAGE	Error shown when auth=managed_identity is requested while the cluster setting is disabled.

Fields inherited from class org.elasticsearch.xpack.esql.datasources.spi.DataSourceConfiguration

DEPRECATED_AUTH_LOG_KEY_PREFIX, DEPRECATED_AUTH_MESSAGE

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	FileDataSourceConfiguration(Map<String,Object> raw, Map<String,DataSourceConfigDefinition> fieldDefs)
protected	FileDataSourceConfiguration(Map<String,Object> raw, Map<String,DataSourceConfigDefinition> fieldDefs, Set<String> preexistingSecretKeys)	Like FileDataSourceConfiguration(Map, Map), but for a PUT-as-update; see DataSourceConfiguration(Map, Map, Set).

Method Summary

Modifier and Type	Method	Description
String	auth()
abstract boolean	hasCredentials()	Returns true when the configuration carries a complete static credential.
boolean	isAnonymous()
boolean	isFederatedIdentity()	Returns true when auth=federated_identity is explicitly set.
boolean	isManagedIdentity()	Returns true when auth=managed_identity is set, directing the provider to use the node's ambient credentials.
static boolean	isManagedIdentityAuth(Object authValue)	Returns true when the raw auth value selects managed-identity.
boolean	isStaticCredentials()	Returns true when auth=static_credentials is explicitly set.
protected void	normalize(Map<String,Object> parsed)	Subclass hook to canonicalize parsed values before they are frozen — e.g.
FileDataSourceConfiguration.AuthMode	resolveAuthMode()	The resolved mode, for providers to switch on.
FileDataSourceConfiguration.AuthMode	resolveAuthModeOrNull()	Resolves the credential-selection mode.
abstract String	unresolvedAuthMessage()	Per-CSP message naming the credential fields that would make an auto config resolvable.
protected final void	validate(ValidationException errors)	Cross-field validation.
protected void	validateCredentials(ValidationException errors)	Subclass hook for datasource-specific credential validation.

Methods inherited from class org.elasticsearch.xpack.esql.datasources.spi.DataSourceConfiguration

buildRawMap, equals, filterAndConstruct, filterKnown, get, hasAnyExplicitSecretValue, hasAnySecretValue, hasFederatedAuth, hashCode, hasStoredSecret, toMap, toStoredSettings

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Details

AUTH

protected static final DataSourceConfigDefinition AUTH

MANAGED_IDENTITY_DISABLED_MESSAGE

public static final String MANAGED_IDENTITY_DISABLED_MESSAGE

Error shown when auth=managed_identity is requested while the cluster setting is disabled. Shared between the CRUD validator (FileDataSourceValidator.validateDatasource(java.util.Map<java.lang.String, java.lang.Object>)) and the inline-WITH gate in StorageProviderRegistry so both paths report the same message.

See Also:

• Constant Field Values

Constructor Details

FileDataSourceConfiguration

protected FileDataSourceConfiguration(Map<String,Object> raw,
 Map<String,DataSourceConfigDefinition> fieldDefs)

FileDataSourceConfiguration

protected FileDataSourceConfiguration(Map<String,Object> raw,
 Map<String,DataSourceConfigDefinition> fieldDefs,
 Set<String> preexistingSecretKeys)

Like FileDataSourceConfiguration(Map, Map), but for a PUT-as-update; see DataSourceConfiguration(Map, Map, Set).

Method Details

normalize

protected void normalize(Map<String,Object> parsed)

Description copied from class: DataSourceConfiguration

Subclass hook to canonicalize parsed values before they are frozen — e.g. mapping a deprecated enum alias to its current value so the stored configuration (and every later read) holds the canonical form. Runs after unknown-field rejection and case-insensitive lowering, before DataSourceConfiguration.validate(org.elasticsearch.common.ValidationException). The default is a no-op. Like DataSourceConfiguration.validate(org.elasticsearch.common.ValidationException), this is a virtual call during construction, so overrides must touch only the supplied map and static data, never instance fields.

Overrides:

normalize in class DataSourceConfiguration

validate

protected final void validate(ValidationException errors)

Description copied from class: DataSourceConfiguration

Cross-field validation. Accumulate errors into the provided exception.

Specified by:

validate in class DataSourceConfiguration

validateCredentials

protected void validateCredentials(ValidationException errors)

Subclass hook for datasource-specific credential validation.

hasCredentials

public abstract boolean hasCredentials()

Returns true when the configuration carries a complete static credential. The exact required field combination is CSP-specific (e.g. S3 access_key+secret_key; Azure connection_string or account+key/sas_token). Used by validate(org.elasticsearch.common.ValidationException) to enforce auth=static_credentials completeness and by the providers to select the static-credential path.

auth

public String auth()

isAnonymous

public boolean isAnonymous()

isStaticCredentials

public boolean isStaticCredentials()

Returns true when auth=static_credentials is explicitly set.

isFederatedIdentity

public boolean isFederatedIdentity()

Returns true when auth=federated_identity is explicitly set.

isManagedIdentity

public boolean isManagedIdentity()

Returns true when auth=managed_identity is set, directing the provider to use the node's ambient credentials.

resolveAuthModeOrNull

public FileDataSourceConfiguration.AuthMode resolveAuthModeOrNull()

Resolves the credential-selection mode. An explicit auth value maps straight to its mode — no field inference. Only auto/omitted infers the mode from the fields present, which is the single inference site in the datasource stack. Returns null only for an unresolvable auto config (no complete credential and no federated settings); validate(org.elasticsearch.common.ValidationException) rejects that at create time, so any validated config always resolves to a non-null mode.

resolveAuthMode

public FileDataSourceConfiguration.AuthMode resolveAuthMode()

The resolved mode, for providers to switch on. Throws for the unresolvable-auto case, which is unreachable for a config that passed validate(org.elasticsearch.common.ValidationException) (defense-in-depth).

unresolvedAuthMessage

public abstract String unresolvedAuthMessage()

Per-CSP message naming the credential fields that would make an auto config resolvable. Used by validate(org.elasticsearch.common.ValidationException) for the create-time rejection and by resolveAuthMode()'s defensive throw.

isManagedIdentityAuth

public static boolean isManagedIdentityAuth(Object authValue)

Returns true when the raw auth value selects managed-identity. Shared so the inline-WITH gate in StorageProviderRegistry (which inspects an unparsed config map) and isManagedIdentity() agree on what counts as auth=managed_identity instead of each re-implementing the comparison. Accepts the deprecated workload_identity alias too, because the inline-WITH gate sees the raw value before it has been canonicalized.