Updating models in containers without rebuilding

Before you begin: Complete Deploying your services to Index Cloud, so you already understand the artifact naming convention and how auto-deployment works.

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 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 (the data your logic reads at runtime, such as model weights, scores, or lookup tables) 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 a Docker 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, with the same detection, security scan, and promotion steps. The only difference is that 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 Notifications and alerting section of Deploying your services to Index Cloud.

Note: A badly named folder is either silently ignored or flagged with a warning, depending on which part of the name is wrong. If an upload seems to have done nothing, check the folder name against What happens to a non-conforming artifact before contacting your Index Representative.

Setting up model updates

1. Grant Index read access to a dedicated Amazon S3 bucket using a cross-account IAM role. You normally do this during onboarding, as part of validation. If you haven't already, follow Grant Index access to your S3 model bucket. Model updates do not require write access. See If Index's access is scoped to a subfolder below for where your version folders go.

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, the subfolder Index has access to, 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 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

If Index's access is scoped to a subfolder

Most partners grant Index access to a subfolder (prefix) of a bucket rather than to the whole bucket. In that case, put your version folders directly inside that subfolder. Do not add any folder levels between the subfolder and the version folder.

In the following example, Index's access is scoped to models/, as in the policy in Grant Index access to your S3 model bucket:

s3://<YOUR_MODEL_BUCKET>/
  models/                    <-- the subfolder Index can read
    2025.08.20.0/            <-- version folders go directly here
      manifest.json
      model_data/
        CarBrand1-model.csv
    2025.08.20.1/
      manifest.json
      model_data/
        CarBrand1-model.csv
        CarBrand2-model.csv

The subfolder you scope access to in Grant Index access to your S3 model bucket must be the same subfolder that holds your version folders.

Example model manifest

The following is an example 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.