Workspaces

Use workspaces to isolate deployments for personal development, shared testing, and production.

Goal

By the end of this tutorial, you will understand what a workspace controls, how it differs from a config profile, and when to use an explicit production workspace.

Core Rule

--profile selects which configuration to load. --workspace selects where that configuration is deployed and tracked.

What Is a Workspace?

A workspace is a logical deployment boundary. ModelKnife includes the workspace in stack identity, state tracking, and provider metadata so different people or environments can deploy from the same project without overwriting each other.

Who

Developers use personal workspaces for experiments and validation.

What

A workspace isolates stack names, deployment state, and managed resources.

Why

Production gets a stable, explicit boundary instead of sharing developer state.

Profile vs Workspace

Profiles and workspaces are intentionally separate because they answer different questions.

Profile

Chooses the compose configuration.

--profile prod
Workspace

Chooses the deployment boundary.

--workspace prod
Provider

Chooses the cloud account and region.

aws / gcp
Deployment

ModelKnife combines these choices into one stack identity, state record, and set of managed resources.

Provider-side isolation

ModelKnife carries the workspace into provider deployment and applies provider-specific isolation automatically.

AWS names + tags GCP project or labels Azure resource group / tags

Same profile, different workspace

Both commands load the same profile. Only the workspace changes. ModelKnife turns that workspace into provider-specific isolation automatically.

Command Config Loaded Workspace Used Provider Isolation
mk s deploy --profile prod mlknife-compose.prod.yaml personal workspace ModelKnife-managed personal boundary, using provider-specific names, tags, labels, or state.
mk s deploy --workspace prod --profile prod mlknife-compose.prod.yaml prod workspace ModelKnife-managed prod boundary, using the provider's natural isolation mechanism.

Transparent to Users

You choose the workspace with --workspace. ModelKnife handles resource naming, state identity, tags, labels, or provider-specific boundaries through its provider adapters.

Mental model 
profile   = which YAML configuration should ModelKnife load?
workspace = what deployment boundary should provider resources belong to?
provider  = which cloud account or credential context is being used?
Same profile, different workspaces 
mk s deploy --profile prod
mk s deploy --workspace prod --profile prod

Default Workspace Behavior

If you do not pass --workspace, ModelKnife uses a personal workspace for non-production work. This lets different developers deploy the same stack from the same codebase without colliding.

Beginner Default

For local development, start without --workspace. Add an explicit workspace only when you need shared or production isolation.

Step 1: Deploy in Your Workspace

Use the normal commands during development. ModelKnife keeps the deployment isolated from other developers.

Personal workspace deployment 
mk s deploy --profile prod
mk p deploy --profile prod
mk p status --profile prod

Step 2: Deploy to Production Workspace

Use --workspace prod when the deployment should represent production. This makes production intent explicit and keeps production state separate from personal work.

Production workspace deployment 
mk s deploy --workspace prod --profile prod
mk p deploy --workspace prod --profile prod
mk p status --workspace prod --profile prod

Production Requires Intent

Production deployments should use an explicit workspace. In production, ModelKnife can enforce stricter checks such as requiring a clean Git worktree before deployment.

Step 3: Inspect Workspace State

Use workspace-aware commands to confirm which stacks exist and where they were deployed.

Workspace-aware inspection 
mk stacks list
mk s show --workspace prod --profile prod
mk p status --workspace prod --profile prod

Tags and State Isolation

ModelKnife records workspace information in stack identity, local state, and provider metadata where supported. Provider adapters use the workspace context when creating or updating resources, so the cloud account can distinguish personal, shared, and production deployments without users manually adding names, tags, or labels.

Common metadata 
modelknife:workspace
modelknife:stack
modelknife:config_profile
modelknife:managed

Troubleshooting

Deployment Used the Wrong Config

Check --profile. Workspace does not choose a YAML file.

Deployment Went to the Wrong Workspace

Check --workspace. Profile does not isolate deployment state.

Production Deploy Is Blocked

Production workspaces may require stricter deploy checks. Commit or remove local changes before deploying production if clean Git enforcement is enabled.

Best Practices

  • Use personal workspaces for development: let each developer deploy safely without affecting others.
  • Use --workspace prod for production: make production intent explicit.
  • Keep profile and workspace names meaningful: --profile prod means production config, while --workspace prod means production isolation.
  • Use clean Git for production: production deployments should map back to committed code.
  • Inspect before deploying: review stack identity and plan output before changing shared or production workspaces.
Multi-Profile
Production Deployment