Updating models in containers without rebuilding

Before you begin: Complete Validating and deploying your container.

You can update the models that power your container without rebuilding or redeploying the image. This is an optional feature. Your container will function without it. If your decisioning logic is embedded directly in the container image, you can skip this topic.

This feature is useful if you want to iterate on model data independently of your code, enabling faster updates and reduced downtime.

Bid shading partners: Model updates are the recommended path for iterating on shading model weights, clearing price curves, and segment-level parameters without redeploying your container.

A model update requires two types of files: models (decisioning and scoring data used at runtime) and manifests (lists the model data files included in the update).

Important: Uploading a model folder to your S3 location now triggers an automatic deployment, the same as pushing a container image. Only upload a folder when you intend to deploy it. If you do not want to deploy a model update, do not upload it.

How it works

Your container reads model files from the directory specified by the MODEL_PATH environment variable (see the Environment variables section in Building your container).

When you upload a new model folder to S3, Index automatically detects, scans, and validates it, then redeploys your container with the updated files mounted at that same path. This follows the same auto-deployment spec as container images: detection, security scan, and promotion; except the unit being deployed is a versioned folder (see S3 folder structure below) rather than an image tag.

Your folder's version tag is the entire interface; there is no separate placeholder for models in the notifications. The tag itself both identifies the artifact and controls which region(s) it deploys to. See Artifact naming conventions and deployment regions for the full naming convention.

You'll receive Slack notifications for each step, matching the notification table in the Auto-deployment notifications section of Validating and deploying your container.

If your folder name doesn't match the required naming convention, Index will not generate any event or Slack notification at all; the upload is silently ignored. If an upload seems to have done nothing, check the folder name against Artifact naming conventions and deployment regions before contacting your Index Representative.

Setting up model updates

1. Create a dedicated Amazon S3 location. Follow the S3 bucket permissions guide to provide Index read-only and list access.

2. Create the MODEL_PATH directory in your container. Include mkdir -p $MODEL_PATH in your Dockerfile. Index Cloud must be able to mount this path.

3. Share details with your Index Representative. Provide the bucket name and the MODEL_PATH variable your container expects.

4. Upload model artifacts. Each upload is a versioned folder containing a manifest and one or more model data files.

5. Index scans and validates. The sync job polls your bucket, detects new uploads, and scans them. Artifacts must be non-executable, in supported formats (JSON, YAML, CSV, TXT, TOML), and within the agreed size limit. Unsupported formats or artifacts that fail validation are rejected. Your Index Representative will notify you of any failures.

6. Container is redeployed. Validated artifacts are mounted at MODEL_PATH. Your container restarts and reads the new files. Model data becomes available in all active data centers.

S3 folder structure

Model folders must use the naming convention described in Artifact naming conventions and deployment regions: <version>-<annotation>_<REGION>, for example 2025.08.20.0 (deploys everywhere) or 2025.08.20.0_EMEA (deploys to EMEA only). This is the same naming convention used for container image tags. Each folder contains one manifest and one or more data files.

Do not modify folders after upload. They will not be re-synced. Create a new folder with a bumped version instead.

Example folder structure

2025.08.20.0/
  manifest.json
  model_data/
    CarBrand1-model.csv

2025.08.20.1/
  manifest.json
  model_data/
    CarBrand1-model.csv
    CarBrand2-model.csv

Example model manifest

manifest.json:
{
  "name": "Manifest for August 20th",
  "models": [
    "CarBrand1-model.csv",
    "CarBrand2-model.csv"
  ]
}

Responsibilities

If you need to use a storage option other than Amazon S3, contact your Index Representative.