Composable Index Templates, Component Templates, Priorities, Simulation, and Environment Promotion

Learning outcomes

Hand-created AtlasMart indices drift: one developer changes replica count in test, another pastes a mapping into production, and a third creates an index before the intended template exists. Composable templates turn mappings/settings/aliases into named deployment artifacts, but only if precedence and overlap are deterministic.

1. Separate reusable components from selection policy

PUT _component_template/atlasmart-products-mappings-v1
{
  "version": 1,
  "_meta": {"owner":"search-platform", "schema":"atlasmart-products", "generation":1},
  "template": {
    "mappings": {
      "dynamic": "strict",
      "properties": {
        "product_id": {"type":"keyword"},
        "name": {"type":"text", "fields":{"keyword":{"type":"keyword","ignore_above":256}}},
        "category": {"type":"keyword"},
        "price": {"type":"scaled_float", "scaling_factor":100},
        "available": {"type":"boolean"},
        "updated_at": {"type":"date"}
      }
    }
  }
}

PUT _component_template/atlasmart-products-settings-v1
{
  "version": 1,
  "_meta": {"owner":"search-platform", "schema":"atlasmart-products", "generation":1},
  "template": {
    "settings": {"number_of_shards":1, "number_of_replicas":0}
  }
}

PUT _index_template/atlasmart-products-template-v1
{
  "index_patterns":["atlasmart-products-v1-*"] ,
  "priority": 200,
  "version": 1,
  "_meta": {"owner":"search-platform", "schema":"atlasmart-products", "generation":1},
  "composed_of":["atlasmart-products-settings-v1","atlasmart-products-mappings-v1"]
}

2. Precedence is part of the schema

For the portable core used here, later components in composed_of can override earlier component values; mappings/settings directly in the index template are applied after components; and explicit create-index settings/mappings take precedence for the fields/options supplied there. When multiple composable index templates match, the highest priority wins. That means priority numbers and component order must be code-reviewed just like mappings.

PUT _index_template/atlasmart-products-template-catchall
{
  "index_patterns":["atlasmart-products-*"] ,
  "priority": 50,
  "template":{"settings":{"number_of_replicas":0}}
}

PUT _index_template/atlasmart-products-template-v1
{
  "index_patterns":["atlasmart-products-v1-*"] ,
  "priority": 200,
  "version": 1,
  "_meta":{"owner":"search-platform","schema":"atlasmart-products","generation":1},
  "composed_of":["atlasmart-products-settings-v1","atlasmart-products-mappings-v1"]
}

POST _index_template/_simulate_index/atlasmart-products-v1-000001

Inspect the simulation result for final settings, mappings, aliases, and overlap metadata where exposed. The evidence question is not “does my template exist?” but “what would atlasmart-products-v1-000001 actually receive right now?”

3. Simulate a candidate before installing it

POST _index_template/_simulate
{
  "index_patterns":["atlasmart-products-v2-*"] ,
  "priority": 210,
  "version": 2,
  "composed_of":["atlasmart-products-settings-v1","atlasmart-products-mappings-v1"],
  "template": {
    "mappings": {
      "properties": {
        "brand":{"type":"keyword"}
      }
    }
  }
}

This dry run is a deployment gate. Assert not only that it returns HTTP 200, but that the resolved contract contains the intended fields/settings and no unexpected higher-priority overlap. In Elastic environments, also avoid collisions with built-in index-template patterns/priority bands. Managed platforms may inject or constrain templates differently; inspect the actual target.

4. A valid template can still be an operationally wrong template

Template A: pattern atlasmart-products-*    priority 100
Template B: pattern atlasmart-products-v2-* priority 50

Index: atlasmart-products-v2-000001

Assumption: "B is more specific, so B wins."
Reality: composable template resolution uses priority; the higher-priority matching template wins.
Repair: choose/document non-overlapping patterns or explicit priority policy, then simulate the concrete name.

Do not rely on visual “specificity” of wildcard patterns. The priority value is executable behavior. Likewise, do not use environment-specific hand edits to fix a template after promotion; that creates drift invisible to source control.

5. Environment promotion: same artifact, environment inputs outside schema

schema_artifact: atlasmart-products
schema_generation: 1
component_templates:
  - atlasmart-products-settings-v1
  - atlasmart-products-mappings-v1
index_template: atlasmart-products-template-v1
expected_pattern: atlasmart-products-v1-*
expected_priority: 200
server_matrix:
  elasticsearch: 9.5.3
  opensearch: 3.8.0
preflight:
  - template/component inventory captured
  - simulate candidate template
  - simulate concrete index name
  - assert mapping/settings/aliases
  - assert no unexpected overlap
  - create disposable canary index
  - delete canary after evidence capture

Credentials, CA paths and managed endpoint names are deployment configuration, not reasons to fork the schema JSON. Product-specific capabilities may require separate artifacts, but “prod was edited manually” is never an acceptable schema branch.

6. Component updates are not retroactive

Updating atlasmart-products-mappings-v1 changes what future matching indices receive; existing indices keep the mapping/settings they were created with unless a supported mapping/settings update is explicitly applied. This is why mutating a component under the same version name is risky: the same apparent generation can produce different physical indices over time. Prefer immutable/versioned component names for material changes.

Production judgment

Template deployment is cluster-state deployment. Limit who can manage templates, review overlap and priority policy, monitor template changes, and keep promotion auditable. A template simulation does not benchmark indexing/search performance; run separate canary/load tests for shard/analysis/storage effects. Backup and restore plans must preserve both data and the schema artifacts required to create future indices consistently.

Summary and next step

AtlasMart now has versioned reusable template artifacts and deterministic resolution tests. The next lesson handles the harder case: a field contract that cannot be changed in place, requiring a new index generation, controlled reindex, validation, alias cutover and rollback.

Authoritative references

• Elastic mapping overview — Dynamic versus explicit mapping and schema-management guidance.
• Elastic dynamic field mapping — Detection rules, dynamic modes, date detection and numeric detection.
• Elastic dynamic templates — match/path/type conditions, template variables, ordering and runtime-field options.
• Elastic templates — Composable index/component templates, precedence, priority and reusable configuration.
• Elastic simulate index template API — Dry-run composition and overlapping-template evidence.
• Elastic simulate index API — Resolve the configuration that a concrete index name would receive.
• Elastic update mapping examples — Why incompatible field-type changes require a new index and reindex.
• Elastic aliases — Index aliases, write-index behavior and no-downtime reindex patterns.
• OpenSearch mappings — Dynamic mapping rules and dynamic-template controls.
• OpenSearch dynamic parameter — OpenSearch-specific dynamic modes including allow-templates variants.
• OpenSearch index templates — Composable templates, priorities and component composition.
• OpenSearch component template API — Reusable settings/mappings/aliases and creation-time behavior.
• OpenSearch simulate index template API — Preview template resolution before index creation.
• OpenSearch reindex API — Source snapshot behavior and destination-index requirements.
• OpenSearch alias API — Alias creation/update APIs and the distinction from manage-alias actions.