# Model Registry and Versioning with SageMaker

> Chapter 9 of the Courseiva AWS-ML-ENGINEER-ASSOCIATE curriculum — https://courseiva.com/learn/aws-ml-engineer-associate/model-registry-versioning

**Official objective:** 2.5 — Manage model versions and lineage using SageMaker Model Registry

## Introduction

Model Registry and Versioning with SageMaker. It solves the chaos of managing multiple machine learning models at once. If you are studying for the MLA-C01 exam, understanding this topic is critical because it tests how to organise, track, and control the lifecycle of models—something every real-world ML team must do to avoid deploying the wrong version of a model to production.

## The Master Baker's Recipe Log Analogy

The Master Baker at a chain bakery runs the entire baking operation. She doesn't just mix flour and sugar; she is the keeper of every recipe the bakery has ever created. One day, she perfects a new sourdough loaf. She doesn't just scribble it on a napkin and hope for the best. Instead, she writes it into the bakery's official Recipe Log, assigning it a unique version number: 'Sourdough v1.0'. She carefully notes the exact ingredient ratios, the rising time, the oven temperature, and even which assistant baked the test batch. This is her immutable record of that specific loaf.

A month later, a branch manager wants to use that recipe, but the Master Baker has since improved it, reducing the salt and adding a starter culture. She doesn't erase the old entry; she adds a new entry: 'Sourdough v2.0'. The Recipe Log now contains a clear history. The branch manager can see v1.0 (the original) and v2.0 (the improved version). The log also tells him that v1.0 was approved for retail sale but v2.0 is still in internal testing. If the health inspector ever asks, 'Which version of that sourdough was on the shelves last Tuesday?', the Master Baker can point to the log and say, 'That was Sourdough v1.0, approved for sale on that date.' She has full lineage: she knows which baker made it, which oven was used, and which batch of flour went into it.

This is exactly what the SageMaker Model Registry does for machine learning models. The Master Baker is the MLOps engineer or data scientist. The Recipe Log is the Model Registry. The version numbers track model iterations. The approval status ('in testing', 'approved') controls which models are used in production. And the lineage information—linking the model to the training data, the algorithm, and the training job—is the equivalent of noting which assistant baked the test batch and which oven was used. Without this registry, the bakery would be chaos: bakers using the wrong recipe, no one knowing which version of the sourdough is actually correct, and no way to trace a mistake back to its source.

## Core explanation

Think about what happens when you write a school essay. You start with a first draft, then you edit it, and you might end up with five different versions saved on your computer. If you are smart, you name them 'Essay_v1', 'Essay_v2_final', 'Essay_v3_actually_final'. But eventually, you get confused about which one is truly the final version. That is the exact problem companies face with machine learning models. They train one model, then they tune it, then they train another version with different data, and suddenly they have dozens of model files. They need a central system that acts like a library catalogue—something that tells them: 'This is model v1.0, this is v2.0, and v2.0 is approved for production use.'

The SageMaker Model Registry is that central catalogue. It is a feature within Amazon SageMaker, which is Amazon's cloud-based service for building, training, and deploying machine learning models. The Model Registry lives inside SageMaker and works hand-in-hand with two other SageMaker components: SageMaker Pipelines (for automating the model training workflow) and SageMaker Projects (for organising end-to-end ML projects). But you do not need to understand every detail of those right now. The core idea is simple: the registry stores model containers (which are like packages containing the model code and dependencies) and tracks their versions.

Here is the process step-by-step. First, a data scientist trains a model using SageMaker's training jobs. Once the model is trained, it is saved as what SageMaker calls a 'model package'. A model package is essentially a collection of the model artifact (the trained file), the inference code (the code that makes predictions), and metadata (information about the model, like its accuracy score or the date it was trained). The data scientist then registers this model package in the Model Registry. The registry creates a 'model package group', which is like a folder for all versions of a specific model. The first version entered gets the version number 1. When the data scientist trains an improved model and registers it in the same group, it becomes version 2, and so on.

Why is this better than just saving model files on a network drive? Three reasons. First, versioning: you can see the entire history of a model. Second, approval workflows: you can mark a model version as 'pending approval', 'approved', or 'rejected'. This means only approved models can be deployed to production, reducing the risk of deploying a broken model. Third, lineage tracking: the registry automatically captures metadata about where the model came from. It records which training job produced it, which dataset was used for training, which hyperparameters were used (hyperparameters are settings that control the learning process, like the learning rate), and which algorithm was employed. This lineage is crucial for debugging, auditing, and regulatory compliance.

A real-world scenario might look like this. A bank is building a model to detect fraudulent credit card transactions. The data science team trains fifty different versions of this model over six months. Without a registry, deploying the wrong version could mean blocking legitimate transactions or missing real fraud. With the Model Registry, the team can see at a glance that 'FraudDetector_v12' is approved, 'FraudDetector_v11' was rejected because of low recall (a performance metric), and 'FraudDetector_v13' is still in testing. They can deploy only the approved version to production, and if something goes wrong, they can trace back to exactly which training job created that version.

The MLA-C01 exam expects you to know how to use the Model Registry to manage model versions and lineage. Specifically, you need to understand how to register a model package, how to update its approval status, and how to retrieve model lineage using the SageMaker SDK (SDK stands for Software Development Kit—it is a set of tools for interacting with SageMaker programmatically). You should also know that the Model Registry can be integrated with CI/CD pipelines (Continuous Integration/Continuous Deployment—automated systems that test and deploy code) so that only approved models are automatically deployed. This is how you move from a messy, manual process to a streamlined, governed machine learning lifecycle.

## Real-world context

Imagine you work as a Machine Learning Engineer at a healthcare company that builds predictive models for patient readmission risk. Your team has developed a model called 'ReadmissionRisk' that predicts whether a patient is likely to be readmitted to hospital within 30 days of discharge. Over the past year, the data science team has trained dozens of versions of this model, tweaking the algorithm, adding new features (like lab results or medication history), and adjusting hyperparameters.

Without a Model Registry, this is what happens in a typical week. A developer goes to deploy a model for a new pilot study at a partner hospital. They browse a shared folder on the company's network drive. They see files named 'model_v3.pkl', 'model_final.pkl', 'model_final2.pkl', and 'model_use_this_one.pkl'. They pick one they think is correct and deploy it. A week later, the hospital reports that the model's predictions are terrible—it is flagging every patient as high risk. The developer realises they deployed an old, buggy version that wasn't tested on the new patient population. There is no record of which model was deployed, when, or why. The team wastes two weeks backtracking, trying to figure out which version was actually used.

With SageMaker Model Registry, the process is completely different. Here is a step-by-step walkthrough of how it works in practice:

- Step 1: A data scientist on your team trains a new version of the model using SageMaker Training. They use a training script that includes the code to register the model package. When the training job completes, the model is automatically registered in SageMaker Model Registry under a model package group called 'ReadmissionRisk'. The registry assigns version number 23 to this model.

- Step 2: The data scientist adds metadata: they set the 'ApprovalStatus' to 'PendingManualApproval'. They also attach notes: 'Trained on patient data from 2024, includes new lab feature, accuracy 0.91, recall 0.85'. The lineage is automatically recorded: the registry knows which training job produced this model, which dataset was used (e.g., 'patient_data_2024_v2'), and the exact hyperparameters (learning rate 0.001, number of trees 200).

- Step 3: A senior MLOps engineer reviews the model. They check the performance metrics and compare them against a baseline. They decide the model meets the bar, so they update the 'ApprovalStatus' to 'Approved' using the SageMaker console or SDK. The registry now shows that version 23 is the only approved model for deployment.

- Step 4: The CI/CD pipeline is configured to automatically deploy any model with an 'Approved' status. When the pipeline runs, it fetches the latest approved version (version 23) from the registry, pulls the model package (which includes the model artifact and inference code), and deploys it to a SageMaker endpoint (a hosted endpoint that serves predictions to the hospital's system). No manual file picking is needed.

- Step 5: Six months later, the hospital's system sends a new patient's data and the model returns a readmission score. But the hospital asks: 'Which version of the model was used to predict this patient's risk?' Your team can look at the endpoint's configuration, which links back to the model package version 23 in the registry. You can then trace the lineage: version 23 came from training job 'train-abc123', which used dataset 'patient_data_2024_v2' and algorithm 'XGBoost'. This information is critical for audits and regulatory compliance in healthcare.

In this scenario, the Model Registry is not a luxury; it is a necessity. It prevents the chaos of manually managing model files, enforces governance by requiring approval before deployment, and provides complete traceability. For the MLA-C01 exam, you need to know that this workflow—register, approve, deploy—is the core pattern the exam tests.

## Exam focus

The MLA-C01 exam tests the Model Registry and Versioning topic in a straightforward but detail-oriented way. There will likely be multiple-choice questions where you are given a scenario and asked to choose the correct SageMaker service or action to manage model versions or lineage. Here is exactly what you need to focus on.

Exam topics that appear frequently:
- What is a 'model package' versus a 'model package group'? A model package is an individual version of a model, including its artifact, inference code, and metadata. A model package group is the collection of all versions of a specific model. In the exam, a scenario might say: 'A data scientist has trained five different versions of a model. They want to organise them by model name.' The correct answer is to create a model package group and register each version as a model package within that group.
- Approval statuses: The registry has three standard approval statuses: 'Approved', 'Rejected', and 'PendingManualApproval'. You can also define custom statuses. The exam may ask: 'Which status should a model have to be deployed automatically in a CI/CD pipeline?' The answer is 'Approved'. They might also ask: 'What happens if you try to deploy a model with a status of Rejected?' The answer is that the pipeline should be configured to reject deployment, and SageMaker itself will not prevent you from deploying a rejected model, but best practice is to enforce this via pipeline logic.
- Lineage tracking: The registry automatically captures lineage to the training job, the dataset (if it is tracked by SageMaker), and the algorithm. The exam may ask: 'Which SageMaker feature stores information about which training job produced a specific model version?' The answer is the Model Registry's lineage tracking. They might also ask about retrieving lineage using the SageMaker SDK—the 'list_artifacts' or 'query_lineage' APIs.
- Integration with SageMaker Pipelines: Pipelines can automatically register model packages as a step in the ML workflow. The exam might present a scenario where a pipeline trains, evaluates, and registers a model in one step. The question could ask: 'Which step in a SageMaker Pipeline is used to register a model?' The answer is the 'RegisterModel' step. They might also ask: 'What is the benefit of using a pipeline to register models?' The benefit is that it automates the registration and ensures lineage is captured without manual intervention.

Trap patterns to watch out for:
- Trap: Confusing the Model Registry with other SageMaker features like SageMaker Experiments (which tracks training job runs and their parameters) or SageMaker Model Monitor (which monitors deployed models for data drift). The exam loves to ask: 'Which service tracks model versions and approval status?' The answer is Model Registry, not Experiments or Monitor.
- Trap: Thinking that the Model Registry stores the actual model artifact. It stores a pointer to the model artifact (in Amazon S3, SageMaker's default storage) along with metadata. The artifact itself is stored in S3.
- Trap: Assuming you can have multiple versions with the same version number. You cannot—each version in a model package group is uniquely numbered. The exam might ask: 'What happens if you try to register a model with an existing version number?' The system will increment or reject the request; it does not overwrite.
- Trap: Overlooking the need for IAM permissions (Identity and Access Management—the system that controls who can do what in AWS). To register a model, you need the 'sagemaker:CreateModelPackage' permission. The exam may include a question that tests whether you know that IAM roles must allow access to the registry.

Key definitions to memorise:
- Model Package: A versioned model resource that includes the model artifact, inference code, and metadata.
- Model Package Group: A logical grouping of model packages that represent different versions of the same model.
- Approval Status: A property of a model package that indicates whether it is allowed for deployment (Approved), not allowed (Rejected), or awaiting review (PendingManualApproval).
- Lineage: The provenance of a model—tracing it back to the training job, dataset, and algorithm used to create it.

The exam will not ask you to write code. Instead, they will present a business scenario (e.g., 'A team needs to track which dataset was used to train a model that is now in production') and you must identify that the Model Registry's lineage feature solves that problem. Practise thinking like an IT professional: when you see a question about versioning, approval, or lineage, your first mental association should be SageMaker Model Registry.

## Step by step

1. **1. Create a Model Package Group** — First, you create a model package group in the SageMaker Model Registry. This is like creating a folder for all versions of a specific model, for example, 'FraudDetectionModel'. You can do this via the AWS Management Console, the SageMaker SDK, or through a SageMaker Pipeline. This step organises all future versions of that model in one place.
2. **2. Train and Register a Model Package** — After training a model using SageMaker Training, you use the SageMaker SDK or a Pipeline step to register the model as a model package within the group. You provide the model artifact (stored in S3), inference code, and metadata like the training job ID and evaluation metrics. The registry automatically assigns a version number (1, 2, 3, etc.) and captures lineage.
3. **3. Set the Approval Status** — Once the model package is registered, you (or an automated process) set its approval status. Common statuses are 'PendingManualApproval' for models awaiting human review, 'Approved' for models cleared for production, and 'Rejected' for models that did not meet performance criteria. This status is a key part of governance.
4. **4. Retrieve and Deploy an Approved Model** — When it is time to deploy, your CI/CD pipeline or manual process retrieves the model package with 'Approved' status from the registry. You use the SageMaker SDK to list model packages in a group, filter by approval status, and then deploy the chosen version to a SageMaker endpoint or batch transform job.
5. **5. Audit Lineage for Compliance** — If there is a need to trace which model version made a prediction (e.g., for a regulatory audit), you query the Model Registry's lineage. You retrieve the model package version, then use SageMaker's lineage API to see the training job, dataset, and algorithm that produced it. This step is critical in regulated industries like healthcare and finance.

## Comparisons

### Model Package Group vs Model Package

**Model Package Group:**
- A container that holds all versions of one model.
- Created once for a specific model name.
- Has no version number itself; it is the parent entity.

**Model Package:**
- An individual version of a model within a group.
- Created each time a new version is registered.
- Has a unique version number (e.g., v1, v2).

### SageMaker Model Registry vs SageMaker Experiments

**SageMaker Model Registry:**
- Manages model lifecycle: versioning, approval, lineage.
- Stores pointers to model artifacts in S3.
- Output is a deployable model package.

**SageMaker Experiments:**
- Tracks training job runs: parameters, metrics, and outputs.
- Stores detailed run-level data for comparison.
- Output is a record of experiments, not a deployable model.

### Approved Status vs PendingManualApproval Status

**Approved Status:**
- Indicates the model is cleared for deployment.
- Set after review by a human or automated evaluation.
- Often used as a trigger in CI/CD pipelines for deployment.

**PendingManualApproval Status:**
- Indicates the model is awaiting human review.
- Set automatically when a model is first registered.
- Cannot be deployed if the pipeline enforces approval checks.

## Diagram

_Flowchart showing the lifecycle from model training through registration, approval, and deployment using SageMaker Model Registry._

```mermaid
flowchart TD
    A[Data Scientist trains model] --> B[SageMaker Training Job]
    B --> C[Model Artifact in S3]
    C --> D[Register Model Package in Registry]
    D --> E[Model Package Group]
    E --> F[Version 1: Pending Approval]
    E --> G[Version 2: Approved]
    E --> H[Version 3: Rejected]
    G --> I[Automated CI/CD Pipeline]
    I --> J[Deploy to SageMaker Endpoint]
    J --> K[Production Predictions]
    F --> L[Manual Review by MLOps Engineer]
    L --> G
```

## Common misconceptions

- **Misconception:** The Model Registry stores the actual model file (the .pkl or .tar.gz file) inside the registry itself. **Reality:** The registry stores metadata and a pointer to the model artifact, which is stored in an Amazon S3 bucket. The artifact itself is not kept in the registry. (Many beginners think a registry is like a database that stores the entire file. In reality, it is more like a card catalogue in a library—it tells you where the book (the model file) is, but the book sits on the shelf (S3).)
- **Misconception:** You can edit or overwrite an existing model package version (for example, to fix a bug). **Reality:** Model packages are immutable once created. You cannot edit a version. To make changes, you must create a new version in the same model package group. This ensures a complete, auditable history. (This comes from a habit of overwriting files on a computer. In machine learning, immutability is key for reproducibility—you want to know exactly what was deployed at a given time.)
- **Misconception:** The Model Registry is only useful for large teams with complex CI/CD pipelines, not for individual data scientists or small projects. **Reality:** The Model Registry is beneficial even for a single person working on a project, because it organises model versions and prevents you from accidentally deploying the wrong one. It scales from one person to hundreds. (Beginners often assume AWS services are only for enterprise use. The exam tests best practices, and using the registry is a best practice for any project involving multiple model iterations.)
- **Misconception:** SageMaker Experiments and SageMaker Model Registry are the same thing and can be used interchangeably. **Reality:** They serve different purposes. SageMaker Experiments tracks the details of individual training runs (like hyperparameters and metrics). SageMaker Model Registry manages the lifecycle of models, including versioning and approval status. They complement each other but are not the same. (Both features involve 'tracking', so beginners confuse them. The exam will deliberately present scenarios that test your ability to distinguish between the two.)
- **Misconception:** Once a model is marked as 'Approved' in the registry, it is automatically deployed to production. **Reality:** The approval status is just a label. It does not trigger deployment by itself. You must configure a CI/CD pipeline or manually deploy the model. The registry only indicates that the model is ready for deployment. (Beginners expect 'Approved' to mean 'deployed', but in AWS, services are modular. The registry is responsible for tracking, not for execution. The exam tests this separation of concerns.)

## Key takeaways

- A model package group is a container for all versions of a specific model, and each individual version is called a model package.
- The Model Registry automatically captures lineage information, linking a model version to its training job, dataset, and algorithm.
- Approval statuses ('Approved', 'Rejected', 'PendingManualApproval') control which models are allowed for deployment but do not trigger deployment automatically.
- Model packages are immutable once created; to update a model, you must register a new version in the same model package group.
- The Model Registry stores metadata and a pointer to the model artifact in Amazon S3, not the artifact itself.
- SageMaker Pipelines can automatically register model packages as part of an ML workflow using the RegisterModel step.
- Using the Model Registry prevents the common mistake of deploying an outdated or untested model version to production.

## FAQ

**What is the difference between a model package and a model package group in SageMaker Model Registry?**

A model package group is a container that holds all versions of a specific model (e.g., 'CustomerChurnModel'). A model package is an individual version within that group (e.g., version 1, version 2). Think of the group as a binder and each model package as a page in that binder.

**Can I delete a model package version from the Model Registry?**

Yes, you can delete a model package version, but it is not recommended because you lose the audit trail. The best practice is to mark a version as 'Rejected' instead of deleting it, so you keep a record of why it was not used.

**Does SageMaker Model Registry automatically track which dataset was used for training?**

The registry automatically captures lineage to the training job, but tracking the specific dataset depends on whether the dataset is stored as a SageMaker Experiment artifact or referenced in the training job configuration. You may need to manually associate dataset information for full lineage.

**Can I use SageMaker Model Registry without using SageMaker Pipelines?**

Yes, you can use the registry independently. You can register model packages manually via the SageMaker SDK or console. Pipelines simply automate the registration as part of a larger workflow, but the registry works fine on its own.

**How do I see all versions of a model in the Model Registry?**

You can use the SageMaker console, navigate to the Model Registry section, and select the model package group. It will list all versions with their version numbers, approval statuses, and creation dates. Programmatically, you can use the 'list_model_packages' API call.

**Is the approval status in the Model Registry checked by SageMaker when I try to deploy a model?**

No, SageMaker itself does not enforce the approval status during deployment. It is up to you or your CI/CD pipeline to check the status and decide whether to deploy. The exam tests that you understand this separation: the registry labels the model, but you must implement the enforcement.

## Check your understanding

1. **A data scientist wants to organise five different iterations of a fraud detection model in SageMaker. What should they create to group these versions together?**

   Answer: They should create a model package group (e.g., 'FraudDetectionModel') and then register each iteration as a model package within that group.

2. **Which approval status should a model package have to be automatically deployed by a CI/CD pipeline?**

   Answer: The model package should have an 'Approved' status. The pipeline should be configured to filter for models with that status before deployment.

3. **True or false: SageMaker Model Registry stores the entire model artifact (the .tar.gz file) inside the registry.**

   Answer: False. The registry stores metadata and a pointer (Amazon S3 URI) to the model artifact. The actual artifact is stored in an S3 bucket.

4. **What SageMaker service automatically captures the lineage between a model version and its training job?**

   Answer: SageMaker Model Registry automatically captures lineage. It records which training job, dataset, and algorithm produced the model package.

5. **A team accidentally deleted the model artifact from S3 but still has the model package in the registry. Can they still deploy the model?**

   Answer: No, because the registry only stores a pointer to the S3 artifact. Without the artifact, the deployment will fail. The registry's pointer is useless without the underlying file.

---

Interactive version with quiz and diagrams: https://courseiva.com/learn/aws-ml-engineer-associate/model-registry-versioning