Configuration Guide

Goal

This page is the map of the configuration system. It explains which concept controls which part of a deployment, then points you to the right detailed page.

Configuration in One Sentence

mlknife-compose.yaml defines the stack, --profile selects a config variant, --workspace selects deployment isolation, and provider credentials select the cloud account.

Configuration Layers

ModelKnife keeps these concepts separate so teams can safely reuse the same codebase across people, environments, and providers.

Layer	Controls	Example	Where To Learn More
Compose file	Services, modules, parameters, and stack metadata	`mlknife-compose.yaml`	YAML Reference
Config profile	Which compose variant is loaded	`--profile prod`	Multi-Profile
Workspace	Deployment boundary and provider-side isolation	`--workspace prod`	Workspaces
Provider credentials	Cloud account, project, region, or identity context	AWS profile, GCP ADC, Azure identity	Team Setup

First Compose File

Start with a small default file. Add profiles and workspaces only when you need variants or deployment isolation.

mlknife-compose.yaml

name: image-classifier
backend: aws
description: Image classification workflow

parameters:
  environment: dev
  data_path: s3://example-${parameters.environment}/images

services:
  artifacts_bucket:
    type: object_storage_bucket
    configuration:
      bucket_name: image-classifier-${parameters.environment}-artifacts

modules:
  prepare_training_data:
    type: etl
    repository: ../src
    entry_point: jobs/prepare_training_data.py
    job_parameters:
      input_path: ${parameters.data_path}/raw
      output_path: ${parameters.data_path}/prepared

How Config Is Loaded

ModelKnife resolves configuration in a predictable order.

Typical commands

# Load mlknife-compose.yaml
mk s show

# Load mlknife-compose.prod.yaml on top of the default file
mk s show --profile prod

# Deploy the prod profile into the prod workspace
mk s deploy --workspace prod --profile prod

Do Not Mix the Meanings

--profile prod chooses production configuration. --workspace prod chooses production deployment isolation. Most production commands use both intentionally.

Provider Credentials

Provider credentials are separate from config profiles and workspaces. They determine which cloud account, project, region, or identity ModelKnife uses when it talks to a provider.

Provider-Owned Defaults

AWS may use an AWS CLI profile and region. GCP may use Application Default Credentials and project context. Azure may use its configured identity and subscription. ModelKnife keeps this separate from YAML profile selection.

Troubleshooting

Wrong Values Loaded

Check the selected --profile. The profile controls which YAML variant is merged into the base compose file.

Deployment Went to the Wrong Boundary

Check --workspace. Workspace controls ModelKnife-managed deployment isolation and provider-side resource boundaries.

Cloud Access Failed

Check provider credentials and region or project settings. These are not controlled by --profile or --workspace.