Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(opensearch): support OpenSearch 3.x, validate engine versions, real ES 7.10 OSS image (#1025)

Shubham Srivastava89d405316da3
diff --git a/docs/services/opensearch.md b/docs/services/opensearch.md
index 73c70a8fc3..5900599e90 100644
--- a/docs/services/opensearch.md
+++ b/docs/services/opensearch.md
@@ -14,7 +14,9 @@ Domain metadata is stored in-process. No Docker containers are started. Domains
### Real mode (`mock: false`, default)
-Floci starts an **OpenSearch** (`opensearchproject/opensearch:2`) Docker container per domain. The container is exposed on a host port from the configured range (`9400–9499`). Once `/_cluster/health` returns `green` or `yellow`, the domain transitions to `Created: true` and the `Endpoint` field is populated with the container's address.
+Floci starts an **OpenSearch** Docker container per domain, choosing the image based on the requested `EngineVersion` (e.g. `OpenSearch_3.6` → `opensearchproject/opensearch:3.6.0`, `Elasticsearch_7.10` → `docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2`). The container is exposed on a host port from the configured range (`9400–9499`). Once `/_cluster/health` returns `green` or `yellow`, the domain transitions to `Created: true` and the `Endpoint` field is populated with the container's address.
+
+OpenSearch 2.12+ requires an initial admin password even when the security plugin is disabled; Floci sets `OPENSEARCH_INITIAL_ADMIN_PASSWORD=FlociAdmin1!` automatically for those versions. The security plugin itself stays disabled.
!!! note "Docker socket required"
Real mode starts Docker containers. Mount the Docker socket and set the Docker network so containers can reach each other. For private registry authentication and other Docker settings see [Docker Configuration](../configuration/docker.md).
@@ -83,7 +85,7 @@ services:
|---|---|---|
| `FLOCI_SERVICES_OPENSEARCH_ENABLED` | `true` | Enable/disable the service |
| `FLOCI_SERVICES_OPENSEARCH_MOCK` | `false` | `true` = metadata only (no Docker) |
-| `FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE` | `opensearchproject/opensearch:2` | Docker image for real mode |
+| `FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE` | *(unset)* | Optional fixed image used for every domain regardless of `EngineVersion`. Useful for private registry mirrors. When unset, images resolve per-version from the built-in version map. |
| `FLOCI_SERVICES_OPENSEARCH_PROXY_BASE_PORT` | `9400` | Port range start for real mode |
| `FLOCI_SERVICES_OPENSEARCH_PROXY_MAX_PORT` | `9499` | Port range end for real mode |
| `FLOCI_SERVICES_OPENSEARCH_KEEP_RUNNING_ON_SHUTDOWN` | `false` | Leave containers running after Floci stops |
@@ -110,8 +112,9 @@ services:
- **Domain ID format:** `{accountId}/{domainName}`
- **`Created` flag:** `true` immediately in mock mode; set to `true` by the readiness poller in real mode once `/_cluster/health` reports `green` or `yellow`.
- **`Processing` flag:** `false` immediately in mock mode; `true` until the container is ready in real mode.
-- **Engine version default:** `OpenSearch_2.11`
-- **Supported engine versions:** `OpenSearch_2.13`, `OpenSearch_2.11`, `OpenSearch_2.9`, `OpenSearch_2.7`, `OpenSearch_2.5`, `OpenSearch_2.3`, `OpenSearch_1.3`, `OpenSearch_1.2`, `Elasticsearch_7.10`, `Elasticsearch_7.9`, `Elasticsearch_7.8`
+- **Engine version default:** `OpenSearch_2.19`
+- **Supported engine versions:** `OpenSearch_3.6`, `OpenSearch_3.5`, `OpenSearch_3.4`, `OpenSearch_3.3`, `OpenSearch_3.2`, `OpenSearch_3.1`, `OpenSearch_3.0`, `OpenSearch_2.19`, `OpenSearch_2.17`, `OpenSearch_2.15`, `OpenSearch_2.13`, `OpenSearch_2.11`, `OpenSearch_2.9`, `OpenSearch_2.7`, `OpenSearch_2.5`, `OpenSearch_2.3`, `OpenSearch_1.3`, `OpenSearch_1.2`, `Elasticsearch_7.10`, `Elasticsearch_7.9`, `Elasticsearch_7.8`
+- **Version validation:** `CreateDomain`, `UpdateDomainConfig`, and `UpgradeDomain` reject unknown engine versions with `ValidationException`. `UpgradeDomain` also rejects targets that aren't reachable from the current version per AWS's documented upgrade matrix.
- **Cluster defaults:** `m5.large.search`, 1 instance, EBS enabled with 10 GiB `gp2` volume.
- **Container storage:** each domain gets a named Docker volume (`floci-opensearch-{volumeId}`) created automatically. In memory mode the volume is removed on domain delete; in persistent modes it is retained unless `FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETE=true`.
diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
index 57d4b9e4c3..a2933258bd 100644
--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
@@ -639,8 +639,14 @@ public interface EmulatorConfig {
@WithDefault("false")
boolean mock();
- @WithDefault("opensearchproject/opensearch:2")
- String defaultImage();
+ /**
+ * Optional fixed image used for every domain regardless of the
+ * requested {@code EngineVersion}. Useful for operators running a
+ * private registry mirror or pinning a specific patch tag. When unset
+ * (the common case), images resolve from
+ * {@code OpenSearchVersions.imageFor(...)} per the requested version.
+ */
+ Optional<String> defaultImage();
@WithDefault("9400")
int proxyBasePort();
diff --git a/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchController.java b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchController.java
index 9ee56937e8..2564b5aa0a 100644
--- a/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchController.java
+++ b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchController.java
@@ -31,17 +31,18 @@ public class OpenSearchController {
private static final Logger LOG = Logger.getLogger(OpenSearchController.class);
- private static final List<String> SUPPORTED_VERSIONS = List.of(
- "OpenSearch_2.13", "OpenSearch_2.11", "OpenSearch_2.9", "OpenSearch_2.7",
- "OpenSearch_2.5", "OpenSearch_2.3", "OpenSearch_1.3", "OpenSearch_1.2",
- "Elasticsearch_7.10", "Elasticsearch_7.9", "Elasticsearch_7.8"
- );
-
private static final List<String> INSTANCE_TYPES = List.of(
"t3.small.search", "t3.medium.search",
"m5.large.search", "m5.xlarge.search", "m5.2xlarge.search",
+ "m6g.large.search", "m6g.xlarge.search", "m6g.2xlarge.search",
+ "m7g.large.search", "m7g.xlarge.search", "m7g.2xlarge.search",
"r5.large.search", "r5.xlarge.search", "r5.2xlarge.search",
- "c5.large.search", "c5.xlarge.search", "c5.2xlarge.search"
+ "r6g.large.search", "r6g.xlarge.search", "r6g.2xlarge.search",
+ "r7g.large.search", "r7g.xlarge.search", "r7g.2xlarge.search",
+ "c5.large.search", "c5.xlarge.search", "c5.2xlarge.search",
+ "c6g.large.search", "c6g.xlarge.search", "c6g.2xlarge.search",
+ "c7g.large.search", "c7g.xlarge.search", "c7g.2xlarge.search",
+ "or1.medium.search", "or1.large.search", "or1.xlarge.search", "or1.2xlarge.search"
);
private final OpenSearchService service;
@@ -266,7 +267,7 @@ public class OpenSearchController {
public Response listVersions(@Context HttpHeaders headers) {
ObjectNode response = objectMapper.createObjectNode();
ArrayNode versions = response.putArray("Versions");
- SUPPORTED_VERSIONS.forEach(versions::add);
+ OpenSearchVersions.supportedVersions().forEach(versions::add);
return Response.ok(response).build();
}
@@ -277,12 +278,25 @@ public class OpenSearchController {
ObjectNode response = objectMapper.createObjectNode();
ArrayNode compatibleVersions = response.putArray("CompatibleVersions");
- ObjectNode entry = objectMapper.createObjectNode();
- entry.put("SourceVersion", "OpenSearch_2.9");
- ArrayNode targets = entry.putArray("TargetVersions");
- targets.add("OpenSearch_2.11");
- targets.add("OpenSearch_2.13");
- compatibleVersions.add(entry);
+ // When domainName is set, narrow the response to that domain's source
+ // version — matches AWS's GetCompatibleVersions behavior. Otherwise
+ // return the full matrix so SDK clients can render upgrade pickers.
+ if (domainName != null && !domainName.isBlank()) {
+ String sourceVersion = service.describeDomain(domainName).getEngineVersion();
+ ObjectNode entry = objectMapper.createObjectNode();
+ entry.put("SourceVersion", sourceVersion);
+ ArrayNode targets = entry.putArray("TargetVersions");
+ OpenSearchVersions.compatibleTargets(sourceVersion).forEach(targets::add);
+ compatibleVersions.add(entry);
+ } else {
+ OpenSearchVersions.compatibilityMatrix().forEach((source, targetList) -> {
+ ObjectNode entry = objectMapper.createObjectNode();
+ entry.put("SourceVersion", source);
+ ArrayNode targets = entry.putArray("TargetVersions");
+ targetList.forEach(targets::add);
+ compatibleVersions.add(entry);
+ });
+ }
return Response.ok(response).build();
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchDomainManager.java b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchDomainManager.java
index d2cb99f36b..72f1d8676e 100644
--- a/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchDomainManager.java
+++ b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchDomainManager.java
@@ -47,11 +47,11 @@ public class OpenSearchDomainManager {
}
public void startDomain(Domain domain) {
- String image = config.services().opensearch().defaultImage();
+ String image = resolveImage(domain.getEngineVersion());
String containerName = "floci-opensearch-" + domain.getDomainName();
- LOG.infov("Starting OpenSearch container for domain: {0} using image {1}",
- domain.getDomainName(), image);
+ LOG.infov("Starting OpenSearch container for domain: {0} (version={1}, image={2})",
+ domain.getDomainName(), domain.getEngineVersion(), image);
int hostPort = portAllocator.allocate(
config.services().opensearch().proxyBasePort(),
@@ -62,11 +62,12 @@ public class OpenSearchDomainManager {
ContainerBuilder.Builder specBuilder = containerBuilder.newContainer(image)
.withName(containerName)
.withEnv("discovery.type", "single-node")
- .withEnv("DISABLE_SECURITY_PLUGIN", "true")
.withPortBinding(OPENSEARCH_PORT, hostPort)
.withDockerNetwork(config.services().dockerNetwork())
.withLogRotation();
+ applyEngineEnv(specBuilder, domain.getEngineVersion());
+
if (ContainerStorageHelper.isNamedVolumeMode(config)) {
ContainerStorageHelper.applyStorage(specBuilder, lifecycleManager,
"opensearch", domain.getVolumeId(), domain.getDomainName(),
@@ -135,4 +136,51 @@ public class OpenSearchDomainManager {
ContainerStorageHelper.removeStorage(config, lifecycleManager,
"opensearch", domain.getVolumeId(), domain.getDomainName());
}
+
+ private String resolveImage(String engineVersion) {
+ return OpenSearchVersions.resolveImage(
+ config.services().opensearch().defaultImage(), engineVersion);
+ }
+
+ /**
+ * Engine env that differs between OpenSearch lines and Elasticsearch. Both
+ * the security-plugin disable flag and the v2.12+ initial admin password
+ * are baked here rather than the call site so the {@link #startDomain}
+ * builder chain stays linear.
+ */
+ private void applyEngineEnv(ContainerBuilder.Builder specBuilder, String engineVersion) {
+ if (engineVersion != null && engineVersion.startsWith("Elasticsearch")) {
+ // The OSS distribution of Elasticsearch ships without x-pack, so
+ // any xpack.* setting is rejected as unknown and the node refuses
+ // to boot. The default OSS build has no security plugin to disable
+ // — leave the env empty and let the image use its bare defaults.
+ return;
+ }
+ specBuilder.withEnv("DISABLE_SECURITY_PLUGIN", "true");
+ // OpenSearch 2.12+ refuses to start without an initial admin password
+ // even when the security plugin is disabled (the bootstrap check fires
+ // before plugin config). Provide a fixed value — the security plugin
+ // is off so this isn't a real credential.
+ if (requiresInitialAdminPassword(engineVersion)) {
+ specBuilder.withEnv("OPENSEARCH_INITIAL_ADMIN_PASSWORD", "FlociAdmin1!");
+ }
+ }
+
+ private boolean requiresInitialAdminPassword(String engineVersion) {
+ if (engineVersion == null || !engineVersion.startsWith("OpenSearch_")) {
+ return false;
+ }
+ String numeric = engineVersion.substring("OpenSearch_".length());
+ int dot = numeric.indexOf('.');
+ if (dot < 0) {
+ return false;
+ }
+ try {
+ int major = Integer.parseInt(numeric.substring(0, dot));
+ int minor = Integer.parseInt(numeric.substring(dot + 1));
+ return major > 2 || (major == 2 && minor >= 12);
+ } catch (NumberFormatException e) {
+ return false;
+ }
+ }
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchService.java b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchService.java
index cc8ca85542..265ad4f4e0 100644
--- a/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchService.java
+++ b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchService.java
@@ -30,7 +30,7 @@ public class OpenSearchService {
private static final Logger LOG = Logger.getLogger(OpenSearchService.class);
- private static final String DEFAULT_ENGINE_VERSION = "OpenSearch_2.11";
+ private static final String DEFAULT_ENGINE_VERSION = OpenSearchVersions.DEFAULT_VERSION;
private final StorageBackend<String, Domain> domainStore;
private final EmulatorConfig config;
@@ -76,6 +76,7 @@ public class OpenSearchService {
public Domain createDomain(String domainName, String engineVersion, ClusterConfig clusterConfig,
EbsOptions ebsOptions, Map<String, String> tags, String region) {
validateDomainName(domainName);
+ OpenSearchVersions.validate(engineVersion);
if (domainStore.get(domainName).isPresent()) {
throw new AwsException("ResourceAlreadyExistsException",
@@ -143,6 +144,7 @@ public class OpenSearchService {
ClusterConfig clusterConfig, EbsOptions ebsOptions,
String region) {
Domain domain = describeDomain(domainName);
+ OpenSearchVersions.validate(engineVersion);
if (engineVersion != null && !engineVersion.isBlank()) {
domain.setEngineVersion(engineVersion);
@@ -203,10 +205,13 @@ public class OpenSearchService {
public Domain upgradeDomain(String domainName, String targetVersion) {
Domain domain = describeDomain(domainName);
- if (targetVersion != null && !targetVersion.isBlank()) {
- domain.setEngineVersion(targetVersion);
- domainStore.put(domainName, domain);
+ if (targetVersion == null || targetVersion.isBlank()) {
+ throw new AwsException("ValidationException",
+ "TargetVersion is required for UpgradeDomain.", 400);
}
+ OpenSearchVersions.validateUpgrade(domain.getEngineVersion(), targetVersion);
+ domain.setEngineVersion(targetVersion);
+ domainStore.put(domainName, domain);
return domain;
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchVersions.java b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchVersions.java
new file mode 100644
index 0000000000..7f16128c5f
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/opensearch/OpenSearchVersions.java
@@ -0,0 +1,170 @@
+package io.github.hectorvent.floci.services.opensearch;
+
+import io.github.hectorvent.floci.core.common.AwsException;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * Catalog of OpenSearch / Elasticsearch engine versions Floci can advertise on
+ * {@code ListVersions} and validate against on {@code CreateDomain} /
+ * {@code UpdateDomainConfig} / {@code UpgradeDomain}.
+ *
+ * <p>Each entry maps an AWS-shaped engine version (e.g. {@code OpenSearch_3.0})
+ * to the Docker image tag that {@link OpenSearchDomainManager} pulls when the
+ * service runs in real-container mode. Without this map, every domain would
+ * boot whatever {@code opensearchproject/opensearch:2} resolved to at pull
+ * time, regardless of the user-requested {@code EngineVersion} — a footgun for
+ * anyone testing version-specific behavior (mapping changes between OS 2 and
+ * 3, plugin compatibility, removed APIs, etc.).
+ *
+ * <p>The Elasticsearch 7.10 entry deliberately points at the last
+ * Apache-2-licensed image ({@code elasticsearch-oss:7.10.2}). Newer
+ * Elasticsearch releases ship under the Elastic License v2 / SSPL and are
+ * intentionally out of scope.
+ */
+public final class OpenSearchVersions {
+
+ /**
+ * Default engine version when {@code CreateDomain} omits {@code EngineVersion}.
+ * Tracks the latest 2.x LTS-style line that's broadly compatible with
+ * Elasticsearch 7.10 client SDKs (the most common reason users still use
+ * Floci's OpenSearch surface).
+ */
+ public static final String DEFAULT_VERSION = "OpenSearch_2.19";
+
+ private static final Map<String, String> VERSION_TO_IMAGE = new LinkedHashMap<>();
+ private static final Map<String, List<String>> COMPAT_MATRIX = new LinkedHashMap<>();
+
+ static {
+ // OpenSearch 3.x line — pinned to a concrete image tag rather than the
+ // floating "3" alias so test runs are reproducible.
+ VERSION_TO_IMAGE.put("OpenSearch_3.6", "opensearchproject/opensearch:3.6.0");
+ VERSION_TO_IMAGE.put("OpenSearch_3.5", "opensearchproject/opensearch:3.5.0");
+ VERSION_TO_IMAGE.put("OpenSearch_3.4", "opensearchproject/opensearch:3.4.0");
+ VERSION_TO_IMAGE.put("OpenSearch_3.3", "opensearchproject/opensearch:3.3.2");
+ VERSION_TO_IMAGE.put("OpenSearch_3.2", "opensearchproject/opensearch:3.2.0");
+ VERSION_TO_IMAGE.put("OpenSearch_3.1", "opensearchproject/opensearch:3.1.0");
+ VERSION_TO_IMAGE.put("OpenSearch_3.0", "opensearchproject/opensearch:3.0.0");
+
+ // OpenSearch 2.x — keep the historical entries Floci already accepted,
+ // bump the head to 2.19.5 (current latest 2.x as of 2026-05).
+ VERSION_TO_IMAGE.put("OpenSearch_2.19", "opensearchproject/opensearch:2.19.5");
+ VERSION_TO_IMAGE.put("OpenSearch_2.17", "opensearchproject/opensearch:2.17.1");
+ VERSION_TO_IMAGE.put("OpenSearch_2.15", "opensearchproject/opensearch:2.15.0");
+ VERSION_TO_IMAGE.put("OpenSearch_2.13", "opensearchproject/opensearch:2.13.0");
+ VERSION_TO_IMAGE.put("OpenSearch_2.11", "opensearchproject/opensearch:2.11.1");
+ VERSION_TO_IMAGE.put("OpenSearch_2.9", "opensearchproject/opensearch:2.9.0");
+ VERSION_TO_IMAGE.put("OpenSearch_2.7", "opensearchproject/opensearch:2.7.0");
+ VERSION_TO_IMAGE.put("OpenSearch_2.5", "opensearchproject/opensearch:2.5.0");
+ VERSION_TO_IMAGE.put("OpenSearch_2.3", "opensearchproject/opensearch:2.3.0");
+
+ // OpenSearch 1.x — kept for legacy upgrade paths (1.x → 2.x).
+ VERSION_TO_IMAGE.put("OpenSearch_1.3", "opensearchproject/opensearch:1.3.20");
+ VERSION_TO_IMAGE.put("OpenSearch_1.2", "opensearchproject/opensearch:1.2.4");
+
+ // Elasticsearch 7.x — last Apache-2 OSS line. Image is on Elastic's
+ // registry, not Docker Hub; image string includes the host so the
+ // Docker daemon doesn't try to resolve it under {@code library/}.
+ VERSION_TO_IMAGE.put("Elasticsearch_7.10", "docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2");
+ VERSION_TO_IMAGE.put("Elasticsearch_7.9", "docker.elastic.co/elasticsearch/elasticsearch-oss:7.9.3");
+ VERSION_TO_IMAGE.put("Elasticsearch_7.8", "docker.elastic.co/elasticsearch/elasticsearch-oss:7.8.1");
+
+ // Compatibility matrix — mirrors AWS OpenSearch's allowed in-place
+ // upgrade hops. Source versions that are still on the supported list
+ // but that AWS no longer lets you upgrade out of are intentionally
+ // omitted.
+ //
+ // Per AWS's version-migration guide, OpenSearch 1.3 / 2.x domains must
+ // first upgrade to OpenSearch_2.19 before they can hop to the 3.x
+ // line, so non-2.19 2.x sources do NOT list any 3.x targets directly.
+ // https://docs.aws.amazon.com/opensearch-service/latest/developerguide/version-migration.html
+ COMPAT_MATRIX.put("Elasticsearch_7.10", List.of("OpenSearch_1.3", "OpenSearch_2.19"));
+ COMPAT_MATRIX.put("OpenSearch_1.3", List.of("OpenSearch_2.19", "OpenSearch_2.17", "OpenSearch_2.15", "OpenSearch_2.13"));
+ COMPAT_MATRIX.put("OpenSearch_2.19", List.of("OpenSearch_3.0", "OpenSearch_3.1", "OpenSearch_3.6"));
+ COMPAT_MATRIX.put("OpenSearch_2.17", List.of("OpenSearch_2.19"));
+ COMPAT_MATRIX.put("OpenSearch_2.15", List.of("OpenSearch_2.19"));
+ COMPAT_MATRIX.put("OpenSearch_2.13", List.of("OpenSearch_2.19"));
+ COMPAT_MATRIX.put("OpenSearch_2.11", List.of("OpenSearch_2.13", "OpenSearch_2.19"));
+ COMPAT_MATRIX.put("OpenSearch_2.9", List.of("OpenSearch_2.11", "OpenSearch_2.13"));
+ COMPAT_MATRIX.put("OpenSearch_3.0", List.of("OpenSearch_3.1", "OpenSearch_3.6"));
+ COMPAT_MATRIX.put("OpenSearch_3.1", List.of("OpenSearch_3.2", "OpenSearch_3.6"));
+ }
+
+ private OpenSearchVersions() {
+ }
+
+ /** Versions advertised on {@code ListVersions}, newest-first. */
+ public static List<String> supportedVersions() {
+ return List.copyOf(VERSION_TO_IMAGE.keySet());
+ }
+
+ /**
+ * Pick the image for a domain, honoring an optional operator-supplied
+ * override that applies to every domain regardless of
+ * {@code engineVersion} (private registry mirror, pinned patch). When the
+ * override is absent we delegate to {@link #imageFor(String)}.
+ */
+ public static String resolveImage(Optional<String> override, String engineVersion) {
+ return override.orElseGet(() -> imageFor(engineVersion));
+ }
+
+ /**
+ * Docker image to pull for {@code engineVersion}. Falls back to the
+ * default-version image only when {@code engineVersion} is null/blank;
+ * unknown versions throw — call {@link #validate(String)} first.
+ */
+ public static String imageFor(String engineVersion) {
+ if (engineVersion == null || engineVersion.isBlank()) {
+ return VERSION_TO_IMAGE.get(DEFAULT_VERSION);
+ }
+ String image = VERSION_TO_IMAGE.get(engineVersion);
+ if (image == null) {
+ throw new AwsException("ValidationException",
+ "Unsupported EngineVersion: " + engineVersion, 400);
+ }
+ return image;
+ }
+
+ /** Targets reachable from {@code sourceVersion}, empty if no upgrade path is defined. */
+ public static List<String> compatibleTargets(String sourceVersion) {
+ return COMPAT_MATRIX.getOrDefault(sourceVersion, List.of());
+ }
+
+ /** Every {@code (source, targets)} pair in the matrix, in declaration order. */
+ public static Map<String, List<String>> compatibilityMatrix() {
+ return Map.copyOf(COMPAT_MATRIX);
+ }
+
+ /**
+ * Throws {@code ValidationException} when {@code engineVersion} is set but
+ * not in the supported list. A null/blank value is allowed — callers that
+ * accept an omitted {@code EngineVersion} fall back to {@link #DEFAULT_VERSION}.
+ */
+ public static void validate(String engineVersion) {
+ if (engineVersion == null || engineVersion.isBlank()) {
+ return;
+ }
+ if (!VERSION_TO_IMAGE.containsKey(engineVersion)) {
+ throw new AwsException("ValidationException",
+ "Unsupported EngineVersion: " + engineVersion
+ + ". Supported: " + VERSION_TO_IMAGE.keySet(), 400);
+ }
+ }
+
+ /**
+ * Throws {@code ValidationException} when {@code targetVersion} is not in
+ * the supported list, or not a documented upgrade target from {@code sourceVersion}.
+ */
+ public static void validateUpgrade(String sourceVersion, String targetVersion) {
+ validate(targetVersion);
+ List<String> allowed = compatibleTargets(sourceVersion);
+ if (!allowed.contains(targetVersion)) {
+ throw new AwsException("ValidationException",
+ "Cannot upgrade from " + sourceVersion + " to " + targetVersion
+ + ". Allowed targets: " + allowed, 400);
+ }
+ }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/opensearch/model/Domain.java b/src/main/java/io/github/hectorvent/floci/services/opensearch/model/Domain.java
index 6ed510ae97..836842a649 100644
--- a/src/main/java/io/github/hectorvent/floci/services/opensearch/model/Domain.java
+++ b/src/main/java/io/github/hectorvent/floci/services/opensearch/model/Domain.java
@@ -24,7 +24,7 @@ public class Domain {
private String arn;
@JsonProperty("EngineVersion")
- private String engineVersion = "OpenSearch_2.11";
+ private String engineVersion;
@JsonProperty("Processing")
private boolean processing = false;
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 6b1f018cd2..e79dab78bf 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -215,7 +215,10 @@ floci:
opensearch:
enabled: true
mock: false
- default-image: "opensearchproject/opensearch:2"
+ # default-image: optional override; uncomment to lock every domain to a
+ # single image (e.g. private registry mirror). When unset, the image is
+ # picked from OpenSearchVersions.imageFor(EngineVersion).
+ # default-image: "registry.example.com/opensearch:2.19.5"
proxy-base-port: 9400
proxy-max-port: 9499
keep-running-on-shutdown: false
diff --git a/src/test/java/io/github/hectorvent/floci/services/opensearch/OpenSearchIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/opensearch/OpenSearchIntegrationTest.java
index a59b3fbe3a..d975f36cd3 100644
--- a/src/test/java/io/github/hectorvent/floci/services/opensearch/OpenSearchIntegrationTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/opensearch/OpenSearchIntegrationTest.java
@@ -50,6 +50,19 @@ class OpenSearchIntegrationTest {
.statusCode(409);
}
+ @Test
+ @Order(2)
+ void createDomainRejectsUnknownEngineVersion() {
+ given()
+ .contentType("application/json")
+ .header("Authorization", AUTH_HEADER)
+ .body("{\"DomainName\":\"bogus-version-domain\",\"EngineVersion\":\"OpenSearch_99.0\"}")
+ .when()
+ .post("/2021-01-01/opensearch/domain")
+ .then()
+ .statusCode(400);
+ }
+
@Test
@Order(3)
void describeDomain() {
@@ -214,7 +227,10 @@ class OpenSearchIntegrationTest {
.then()
.statusCode(200)
.body("Versions", not(empty()))
- .body("Versions", hasItem("OpenSearch_2.11"));
+ .body("Versions", hasItem("OpenSearch_3.6"))
+ .body("Versions", hasItem("OpenSearch_2.19"))
+ .body("Versions", hasItem("OpenSearch_2.11"))
+ .body("Versions", hasItem("Elasticsearch_7.10"));
}
@Test
@@ -226,7 +242,25 @@ class OpenSearchIntegrationTest {
.get("/2021-01-01/opensearch/compatibleVersions")
.then()
.statusCode(200)
- .body("CompatibleVersions", not(empty()));
+ .body("CompatibleVersions", not(empty()))
+ .body("CompatibleVersions.SourceVersion", hasItem("OpenSearch_2.19"));
+ }
+
+ @Test
+ @Order(14)
+ void getCompatibleVersionsForDomain() {
+ // domainName-scoped query should only return the source/target row for
+ // the named domain, not the full matrix.
+ given()
+ .header("Authorization", AUTH_HEADER)
+ .queryParam("domainName", DOMAIN_NAME)
+ .when()
+ .get("/2021-01-01/opensearch/compatibleVersions")
+ .then()
+ .statusCode(200)
+ .body("CompatibleVersions", hasSize(1))
+ .body("CompatibleVersions[0].SourceVersion", equalTo("OpenSearch_2.11"))
+ .body("CompatibleVersions[0].TargetVersions", hasItem("OpenSearch_2.13"));
}
@Test
@@ -343,6 +377,19 @@ class OpenSearchIntegrationTest {
.body("TargetVersion", equalTo("OpenSearch_2.13"));
}
+ @Test
+ @Order(23)
+ void upgradeDomainRejectsUnsupportedTarget() {
+ given()
+ .contentType("application/json")
+ .header("Authorization", AUTH_HEADER)
+ .body("{\"DomainName\":\"" + DOMAIN_NAME + "\",\"TargetVersion\":\"OpenSearch_99.0\"}")
+ .when()
+ .post("/2021-01-01/opensearch/upgradeDomain")
+ .then()
+ .statusCode(400);
+ }
+
@Test
@Order(24)
void cancelDomainConfigChange() {
diff --git a/src/test/java/io/github/hectorvent/floci/services/opensearch/OpenSearchVersionsTest.java b/src/test/java/io/github/hectorvent/floci/services/opensearch/OpenSearchVersionsTest.java
new file mode 100644
index 0000000000..a060e1ae9c
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/opensearch/OpenSearchVersionsTest.java
@@ -0,0 +1,154 @@
+package io.github.hectorvent.floci.services.opensearch;
+
+import io.github.hectorvent.floci.core.common.AwsException;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Optional;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.empty;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.hasItem;
+import static org.hamcrest.Matchers.hasItems;
+import static org.hamcrest.Matchers.lessThan;
+import static org.hamcrest.Matchers.startsWith;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/**
+ * Pure-unit assertions on the version catalog. No Quarkus boot needed.
+ */
+class OpenSearchVersionsTest {
+
+ @Test
+ void supportedVersionsIncludesOpenSearch3xAnd2xLatest() {
+ assertThat(OpenSearchVersions.supportedVersions(),
+ hasItems("OpenSearch_3.6", "OpenSearch_3.0",
+ "OpenSearch_2.19", "Elasticsearch_7.10"));
+ }
+
+ @Test
+ void supportedVersionsListsNewestOpenSearch3xFirst() {
+ // Newest-first is what AWS's ListVersions returns; SDK clients render
+ // dropdowns in this order, so a regression here would be user-visible.
+ List<String> versions = OpenSearchVersions.supportedVersions();
+ int os36 = versions.indexOf("OpenSearch_3.6");
+ int os213 = versions.indexOf("OpenSearch_2.13");
+ int es710 = versions.indexOf("Elasticsearch_7.10");
+ assertThat(os36, lessThan(os213));
+ assertThat(os213, lessThan(es710));
+ }
+
+ @Test
+ void imageForResolvesOpenSearch3x() {
+ assertThat(OpenSearchVersions.imageFor("OpenSearch_3.6"),
+ equalTo("opensearchproject/opensearch:3.6.0"));
+ }
+
+ @Test
+ void imageForResolvesElasticsearch7xToElasticRegistry() {
+ // ES OSS images live on docker.elastic.co, not Docker Hub. The host
+ // prefix has to be in the image string or the daemon resolves under
+ // library/ and the pull 404s.
+ assertThat(OpenSearchVersions.imageFor("Elasticsearch_7.10"),
+ startsWith("docker.elastic.co/elasticsearch/elasticsearch-oss:"));
+ }
+
+ @Test
+ void imageForReturnsDefaultWhenEngineVersionOmitted() {
+ String defaultImage = OpenSearchVersions.imageFor(OpenSearchVersions.DEFAULT_VERSION);
+ assertEquals(defaultImage, OpenSearchVersions.imageFor(null));
+ assertEquals(defaultImage, OpenSearchVersions.imageFor(""));
+ }
+
+ @Test
+ void imageForRejectsUnknownVersion() {
+ AwsException e = assertThrows(AwsException.class,
+ () -> OpenSearchVersions.imageFor("OpenSearch_99.0"));
+ assertEquals("ValidationException", e.getErrorCode());
+ }
+
+ @Test
+ void validateAllowsBlankAndKnownVersions() {
+ assertDoesNotThrow(() -> OpenSearchVersions.validate(null));
+ assertDoesNotThrow(() -> OpenSearchVersions.validate(""));
+ assertDoesNotThrow(() -> OpenSearchVersions.validate("OpenSearch_3.0"));
+ assertDoesNotThrow(() -> OpenSearchVersions.validate("Elasticsearch_7.10"));
+ }
+
+ @Test
+ void validateRejectsTypos() {
+ assertThrows(AwsException.class, () -> OpenSearchVersions.validate("Opensearch_2.19"));
+ assertThrows(AwsException.class, () -> OpenSearchVersions.validate("OpenSearch2.19"));
+ }
+
+ @Test
+ void compatibleTargetsCovers2xTo3xUpgrade() {
+ // 2.19 is the documented bridge into the 3.x line — without this, AWS
+ // SDK clients can't render an upgrade picker that reaches 3.x at all.
+ assertThat(OpenSearchVersions.compatibleTargets("OpenSearch_2.19"),
+ hasItem("OpenSearch_3.0"));
+ }
+
+ @Test
+ void compatibleTargetsEmptyForUnknownSource() {
+ assertThat(OpenSearchVersions.compatibleTargets("OpenSearch_99.0"), empty());
+ }
+
+ @Test
+ void validateUpgradeRejectsSkipPath() {
+ // 2.13 has no direct hop to 3.6 in the matrix; force users through the
+ // intermediate 2.19 → 3.x bridge so we don't pretend AWS allows
+ // unsupported upgrade jumps.
+ assertThrows(AwsException.class,
+ () -> OpenSearchVersions.validateUpgrade("OpenSearch_2.13", "OpenSearch_3.6"));
+ }
+
+ @Test
+ void validateUpgradeRejects2xTo3xWithoutGoingThroughLatest2x() {
+ // AWS docs require 1.3 / 2.x domains to upgrade to 2.19 before going
+ // to 3.x. 2.13 / 2.15 / 2.17 → 3.0 must be rejected.
+ assertThrows(AwsException.class,
+ () -> OpenSearchVersions.validateUpgrade("OpenSearch_2.13", "OpenSearch_3.0"));
+ assertThrows(AwsException.class,
+ () -> OpenSearchVersions.validateUpgrade("OpenSearch_2.15", "OpenSearch_3.0"));
+ assertThrows(AwsException.class,
+ () -> OpenSearchVersions.validateUpgrade("OpenSearch_2.17", "OpenSearch_3.0"));
+ }
+
+ @Test
+ void validateUpgradeAcceptsDocumentedHop() {
+ assertDoesNotThrow(() -> OpenSearchVersions.validateUpgrade("OpenSearch_2.11", "OpenSearch_2.13"));
+ assertDoesNotThrow(() -> OpenSearchVersions.validateUpgrade("OpenSearch_2.19", "OpenSearch_3.0"));
+ assertDoesNotThrow(() -> OpenSearchVersions.validateUpgrade("Elasticsearch_7.10", "OpenSearch_2.19"));
+ }
+
+ @Test
+ void validateUpgradeRejectsUnknownTarget() {
+ assertThrows(AwsException.class,
+ () -> OpenSearchVersions.validateUpgrade("OpenSearch_2.19", "OpenSearch_99.0"));
+ }
+
+ @Test
+ void resolveImageHonorsOperatorOverrideAcrossEngineVersions() {
+ // Override locks every domain to the supplied image regardless of
+ // requested EngineVersion — private registry mirror use case.
+ String override = "registry.example.com/opensearch:2.19.5";
+ assertThat(OpenSearchVersions.resolveImage(Optional.of(override), "OpenSearch_3.6"),
+ equalTo(override));
+ assertThat(OpenSearchVersions.resolveImage(Optional.of(override), "Elasticsearch_7.10"),
+ equalTo(override));
+ assertThat(OpenSearchVersions.resolveImage(Optional.of(override), null),
+ equalTo(override));
+ }
+
+ @Test
+ void resolveImageFallsBackToVersionMapWhenOverrideUnset() {
+ assertThat(OpenSearchVersions.resolveImage(Optional.empty(), "OpenSearch_3.6"),
+ equalTo("opensearchproject/opensearch:3.6.0"));
+ assertThat(OpenSearchVersions.resolveImage(Optional.empty(), "Elasticsearch_7.10"),
+ startsWith("docker.elastic.co/elasticsearch/elasticsearch-oss:"));
+ }
+}
diff --git a/src/test/resources/application.yml b/src/test/resources/application.yml
index 57fbda68ab..612cb6eb72 100644
--- a/src/test/resources/application.yml
+++ b/src/test/resources/application.yml
@@ -139,7 +139,6 @@ floci:
opensearch:
enabled: true
mock: true
- default-image: "opensearchproject/opensearch:2"
proxy-base-port: 9400
proxy-max-port: 9499
ec2: