Before you begin: Complete Building a Docker container. That topic assumes you have already completed Build a gRPC RTD service or Build an HTTP RTD service (legacy).
Once your container is built and tested, you share it with Index Exchange (Index) to begin the deployment process. This topic walks through the seven onboarding phases from initial scoping through to full production, including how to validate your implementation, share your image, what to expect during the trial period, and how to move to production scale.
Onboarding process
The table below shows all seven phases. If you have arrived here from Building a Docker container, phases 1-2 are already complete. Start at phase 3. This topic walks through implementing your handler and configuring your metrics endpoint
A URL which is configured to interact with a server in a specific way. (phase 3), sharing your image (phase 4), and the initial trial deployment (phase 5). For the testing tool used to validate your implementation, see Using the Index testing tool.
Bid shading partners: During scoping (phase 1), identify which of your own deals you want to shade. Bid shading is currently supported only for deals you own; there is no path to request permissioning on a deal A private auction that allows media owners to offer specific inventory directly to selected buyers identified by a deal ID. Terms are negotiated and are agreed upon before the auction occurs. owned by another partner. See Implementing bid shading for details.
Most time is spent in phases 2-3. Phases 4-5 typically take 1-2 weeks.
| Phase | What happens | Who |
|---|---|---|
1. Scope | Define use case, extension points, mutations, regions, channels. | You |
2. Build | Implement gRPC container per the build guide. | You |
3. Test locally | Validate using ARTF tools and the Index testing tool. Validate correctness and latency. Remediate as required. | You |
4. Share image | Push to Docker Hub. Index scans, validates, and automatically deploys. | You + Index |
5. Initial trial | Deployed with baseline resources. Production traffic begins. | Index |
6. Optimize | Monitor, iterate on models, tune and optimize performance. | You + Index |
7. Production | You determine your target QPS | You + Index |
Phase 3: Test locally
This section covers what to implement and configure before testing: familiarizing yourself with ARTF, implementing GetMutations, handling response codes and circuit breakers, and configuring your metrics endpoint. For the Index testing tool itself, see Using the Index testing tool.
Familiarize yourself with ARTF
The IAB Interactive Advertising Bureau (IAB). An advertising business organization that develops industry standards, conducts research, and provides legal support for the online advertising industry. Tech Lab has published an open-source implementation of ARTF at github.com/IABTechLab/agentic-rtb-framework. It contains Go and Rust reference implementations, sample test payloads in samples/, and a browser-based testing interface. You can use the ARTF testing tools locally without any involvement from Index to validate your implementation before requesting deployment. The Index testing tool, covered in Using the Index testing tool, is used for final validation against a live-like environment and requires Docker Hub access provisioned by your Index Representative.
Implement GetMutations
Your container implements the RTBExtensionPoint gRPC service, defined in agenticrtbframeworkservices.proto. The service listens on the port set via GRPC_PORT (default 50051); see the Environment variables section in Building a Docker container. Your container must also implement the gRPC healthcheck protocol on this same port; see the Required endpoints section in Building a Docker container. The single RPC, GetMutations, is where all decisioning logic lives. For what it receives and returns, and the implementation pattern, see the What your container receives, What your container returns, and Implementation pattern sections in Build a gRPC RTD service.
Handle response codes and circuit breakers
Return standard gRPC status codes. See the Response codes and Circuit breaker logic sections in Build a gRPC RTD service for the specific thresholds.
Configure your metrics endpoint
Expose an HTTP Prometheus metrics endpoint at /metrics on SERVER_PORT. The required metric is rpc.server.duration, a histogram with boundaries 0.001, 0.002, 0.003, 0.004, 0.005, 0.007, 0.010 in seconds. Permitted tags: rpc.system, rpc.grpc.status_code, rpc.method, rpc.service, error_type. Total cardinality must not exceed 10,000.
rpc.server.duration is required. Containers that do not expose this metric will fail Index Cloud health checks and will not receive traffic.
The following is an example of a correctly formatted /metrics response:
# HELP rpc_server_duration Measures the duration of inbound RPC.
# TYPE rpc_server_duration histogram
rpc_server_duration_sum{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type=""} 0.004
rpc_server_duration_count{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type=""} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.001"} 0
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.002"} 0
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.003"} 0
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.004"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.005"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.007"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="0.010"} 1
rpc_server_duration_bucket{rpc_system="grpc",rpc_grpc_status_code="0",rpc_method="GetMutations",rpc_service="RTBExtensionPoint",error_type="",le="+Inf"} 1You can expose other metrics as required. Index will collect these metrics and make them available to you. Total metric cardinality should not exceed 10,000.
In addition to your own local testing, Index conducts functional testing on your API before it is deployed to production. If your container does not meet the specifications described in this documentation, it may not be deployed.
For the Index testing tool used to send test traffic to your container and validate it against a live-like environment, see Using the Index testing tool. That tool is not specific to Index Cloud and works whether you are deploying there or hosting the service yourself.
Phase 4: Share image
Once your container is ready, share it with Index via Docker Hub. Index pulls from there, runs vulnerability scanning, and automatically deploys it.
Important: Pushing an image now triggers an automatic deployment. Only push an image when you intend to deploy it. If you do not want to deploy an image, do not push it. Chart or configuration changes that are not baked into the image still require a manual deployment; contact your Index Representative for those.
Create a Docker Hub repository for your container images.
Grant read access to
nexus@indexexchange.onmicrosoft.com.Before pushing, confirm your image is eligible to auto-deploy: see Checklist: What must pass before a container can auto-deploy for the three things that must be true (correct naming, a clean vulnerability scan, and the required endpoints).
Push your images. They are automatically detected, scanned for vulnerabilities, and deployed.
For the full artifact naming convention your image tag must follow, what happens after you push (notifications), and how to track your rollout in Grafana, see Deploying your services to Index Cloud. That topic covers everything you'll use on an ongoing basis, not just during onboarding.
Phase 5: Initial trial
| Parameter | Value |
|---|---|
Deployment region | US, Europe, APAC (based on your traffic needs) |
Baseline allocation | 80 vCPU / 120 GB RAM total |
Duration | Up to 90 days |
Index deploys your container using Helm and Argo CD. Index will provide the Helm chart used to deploy your container into Index's Kubernetes environment on demand. This chart exposes your container's API endpoints using host networking to reduce latency. Deployment happens into a dedicated Kubernetes namespace, using a staged rollout. A small set of instances running the new version (the test set) launches first and immediately begins receiving real classification requests. Existing instances of the older version (the stable set) continue serving traffic alongside it. If the test set performs within the 5ms SLA with an error rate below 3%, the stable set scales down proportionally as the test set scales up, until the test set becomes the new stable set and the rollout completes. If the test set does not meet these criteria, the deployment is automatically rolled back. The total number of instances across both sets remains constant throughout.
If you want additional checks beyond SLA and error rate included in this rollout evaluation, contact your Index Representative to discuss adding them.
Once auto-deployment is enabled for your account, container updates deploy automatically when you push a new image tag; no advance notice or request is needed. See Deploying your services to Index Cloud for what happens after each push and what, if anything, requires action from you.
If auto-deployment has not yet been enabled for your account, continue to allow at least one business day of notice when requesting container updates, and request updates no more than twice a week.
Phase 6: Optimize
Once your container is stable in production, ongoing optimization is a mix of model iteration and performance tuning.
Iterate on model data without rebuilding or redeploying your container. See Updating models in containers without rebuilding.
Review the thresholds you're optimizing against. See the Classification endpoint and Circuit breaker logic sections in Build a gRPC RTD service.
For architectural patterns that affect performance from the start, see the Architectural patterns section in Building a Docker container.
Phase 7: Production
After the trial, Index works with you to confirm your target QPS profile, then provides a production resource recommendation and pricing based on observed workload behavior. This is formalized in the compute addendum, which you and Index execute before full production provisioning begins.
Next steps: To iterate on model data without redeploying your container, see Updating models in containers without rebuilding. For the naming convention, deployment notifications, and Grafana tracking you'll use on an ongoing basis, see Deploying your services to Index Cloud. To view your container's metrics, see Access your Grafana data. For details on the auction-path data samples Index delivers to your S3 bucket, see How Index sends data to your container in Index Cloud.
