# Staging Construct for your Model Lifecycle You can define a series of stages that models can progress through for your model workflows and lifecycle with the Model Registry staging construct. This simplifies tracking and managing models as they transition through development, testing, and production stages. The following will provide information on staging constructs and how to use them in your model governance. The stage construct allows you to define a series of stages and statuses that models progress through. At each stage, specific personas with the relevant permissions can update the stage status. As a model advances through the stages, its metadata is carried forward, providing a comprehensive view of the model's lifecycle. This metadata can be accessed and reviewed by authorized personas at each stage, enabling informed decision making. This includes the following benefits. + Model Life Cycle Permissions - Set permissions for designated personas to update a model stage state and enforce approval gates at critical transition points. Administrators can assign permission by using IAM policies and condition keys with the API. For example, you can restrict you data scientist from updating the Model Lifecycle stage transition from "Development" to "Production". For examples, see [Set up Staging Construct Examples](model-registry-staging-construct-set-up.md). + Model Life Cycle Events via Amazon EventBridge - You can consume the lifecycle stage events using EventBridge. This sets you up to receive event notifications when models change approval or staging state, enabling integration with third-party governance tools. See [Get event notifications for ModelLifeCycle](model-registry-staging-construct-event-bridge.md) for an example. + Search based on Model Life Cycle Fields - You can search and filter stage and stage status using the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Search.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Search.html) API. + Audit Trails for Model Life Cycle Events - You can view the history of model approval and staging events for the model lifecycle transitions. The following topics will walk you through how to set up a stage construct on the administrator side and how to update a stage status from the user side. **Topics** + [Set up Staging Construct Examples](model-registry-staging-construct-set-up.md) + [Update a model package stage and status in Studio](model-registry-staging-construct-update-studio.md) + [Update a model package stage and status example (boto3)](model-registry-staging-construct-update-boto3.md) + [Invoke ModelLifeCycle using the AWS CLI examples](model-registry-staging-construct-cli.md) + [Get event notifications for ModelLifeCycle](model-registry-staging-construct-event-bridge.md) # Set up Staging Construct Examples To set up stage constructs for your Amazon SageMaker Model Registry, the administrator will need to grant the relevant permissions to the intended roles. The following provides examples on how to set up stage constructs for various roles. **Note** Users within a Amazon SageMaker AI domain will be able to view all stages defined within the domain, but can only use the ones they have permissions for. Stages are defined by the `ModelLifeCycle` parameter and have the following structure. The administrator sets up the permissions for which `stage` and `stageStatus` can be accessed by which roles. The users assuming a role can use the relevant `stage` and `stageStatus` and include their own `stageDescription`. ``` ModelLifeCycle { stage: String # Required (e.g., Development/QA/Production) stageStatus: String # Required (e.g., PendingApproval/Approved/Rejected) stageDescription: String # Optional } ``` The following table contains Model Registry pre-defined stage construct templates. You can define your own stage constructs based on your use cases. The relevant permissions will need to be set up before users can use them. | Stage | Stage status | | --- | --- | | Proposal | PendingApproval | | Development | InProgress | | QA | OnHold | | PreProduction | Approved | | Production | Rejected | | Archived | Retired | The `ModelLifeCycle` parameter can be invoked by the following APIs: + [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModelPackage.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModelPackage.html) + [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelPackage.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelPackage.html) + [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelPackage.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModelPackage.html) ------ #### [ Policy for a data scientist role ] The following is an example IAM policy using model lifecycle condition keys. You can modify them based on your own requirements. In this example, the role’s permissions are limited to set or define the model lifecycle stage to: + Create or update a model with the stage `"Development"` and status `"Approved"`. + Update a model package with the stage quality assurance, `"QA"`, and status `"PendingApproval"`. ``` { "Action" : [ "sagemaker:UpdateModelPackage", "sagemaker:CreateModelPackage" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "sagemaker:ModelLifeCycle:stage" : "Development" "sagemaker:ModelLifeCycle:stageStatus" : "Approved" } } }, { "Action" : [ "sagemaker:UpdateModelPackage" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "sagemaker:ModelLifeCycle:stage" : "Staging" "sagemaker:ModelLifeCycle:stageStatus" : "PendingApproval" } } } ``` ------ #### [ Policy for a quality assurance specialist ] The following is an example IAM policy using model lifecycle condition keys. You can modify them based on your own requirements. In this example, the role’s permissions are limited to set or define the model lifecycle stage to: + Update a model package with: + The stage `"QA"` and status `"Approved"` or `"Rejected"`. + The stage `"Production"` and status `"PendingApproval"`. ``` { "Action": [ "sagemaker:UpdateModelPackage" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "sagemaker:ModelLifeCycle:stage": "Staging", "sagemaker:ModelLifeCycle:stageStatus": "Approved" } } }, { "Action": [ "sagemaker:UpdateModelPackage" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "sagemaker:ModelLifeCycle:stage": "Staging", "sagemaker:ModelLifeCycle:stageStatus": "Rejected" } } }, { "Action": [ "sagemaker:UpdateModelPackage" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "sagemaker:ModelLifeCycle:stage": "Production", "sagemaker:ModelLifeCycle:stageStatus": "PendingApproval" } } } ``` ------ #### [ Policy for lead engineer role ] The following is an example IAM policy using model lifecycle condition keys. You can modify them based on your own requirements. In this example, the role’s permissions are limited to set or define the model lifecycle stage to: + Update a model package with: + The stage `"Production"` and status `"Approved"` or `"Rejected"`. + The stage `"Development"` and status `"PendingApproval"`. ``` { "Action" : [ "sagemaker:UpdateModelPackage" ], "Resource": [ "*" ], "Condition": { "ForAnyvalue:StringEquals" : { "sagemaker:ModelLifeCycle:stage" : "Production", "sagemaker:ModelLifeCycle:stageStatus" : "Approved" } } }, { "Action" : [ "sagemaker:UpdateModelPackage" ], "Resource": [ "*" ], "Condition": { "StringEquals:" { "sagemaker:ModelLifeCycle:stage" : "Production" "sagemaker:ModelLifeCycle:stageStatus" : "Rejected" } } }, { "Action" : [ "sagemaker:UpdateModelPackage" ], "Resource": [ "*" ], "Condition": { "StringEquals": { "sagemaker:ModelLifeCycle:stage" : "Development" "sagemaker:ModelLifeCycle:stageStatus" : "PendingApproval" } } } ``` ------ To get Amazon EventBridge notifications on any model status update, see the example in [Get event notifications for ModelLifeCycle](model-registry-staging-construct-event-bridge.md). For an example EventBridge payload you may receive, see [SageMaker model package state change](automating-sagemaker-with-eventbridge.md#eventbridge-model-package). # Update a model package stage and status in Studio To use a model package stage construct, you will need to assume an execution role with the relevant permissions. The following page provides information on how to update the stage status using Amazon SageMaker Studio. All stage constructs defined in the domain will be viewable by all users. To update a stage, you will need have the administrator set up the relevant permissions for you to access it. For information on how, see [Set up Staging Construct Examples](model-registry-staging-construct-set-up.md). The following procedure will take you to the Studio UI where you can update your model package stage. 1. Sign in to Amazon SageMaker Studio. For more information, see [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. In the left navigation pane, choose the **Models**. 1. Find your model. + You can use the tabs to find your models. For example, choose the **Registered models** or **Deployable models** tabs. + You can use the **My models** and **Shared with me** options to find models you created or ones that are shared by you. 1. Select the checkbox next to the model you wish to update. 1. Choose the **More options** icon. 1. Choose **Update model lifecycle**. This will take you to the **Update model lifecycle** section. 1. Complete the tasks to update the stage. If you cannot update the stage, you will receive an error. Your administrator will need to set up the permissions for you to do so. For information on how to set up the permissions, see [Set up Staging Construct Examples](model-registry-staging-construct-set-up.md). # Update a model package stage and status example (boto3) To update a model package stage and status, you will need to assume an execution role with the relevant permissions. The following provides an example on how you can update the stage status using the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelPackage.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelPackage.html) API using AWS SDK for Python (Boto3). In this example, the `ModelLifeCycle` stage `"Development"` and stage status `"Approved"` condition keys for the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelPackage.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateModelPackage.html) API action has been granted to the your execution role. You can include a description in `stage-description`. See [Set up Staging Construct Examples](model-registry-staging-construct-set-up.md) for more information. ``` from sagemaker import get_execution_role, session import boto3 region = boto3.Session().region_name role = get_execution_role() sm_client = boto3.client('sagemaker', region_name=region) model_package_update_input_dict = { "ModelLifeCycle" : { "stage" : "Development", "stageStatus" : "Approved", "stageDescription" : "stage-description" } } model_package_update_response = sm_client.update_model_package(**model_package_update_input_dict) ``` # Invoke ModelLifeCycle using the AWS CLI examples You can use the AWS CLI tool to manage your AWS resources. A few AWS CLI commands include [search](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudsearchdomain/search.html) and [list-actions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/fis/list-actions.html). The following page will provide examples on how to use `ModelPackage` while using these commands. For information and examples on setting up your stage construct, see [Set up Staging Construct Examples](model-registry-staging-construct-set-up.md). The examples on this page uses the following variables. + `region` is the region that your model package exists in. + `stage-name` is the name of your defined stage. + `stage-status` is the name of your defined stage status. The following are example AWS CLI commands using ModelLifeCycle. Search for your model packages with a *stage-name* you have already defined. ``` aws sagemaker search --region 'region' --resource ModelPackage --search-expression '{"Filters": [{"Name": "ModelLifeCycle.Stage","Value": "stage-name"}]}' ``` List the actions associated with `ModelLifeCycle`. ``` aws sagemaker list-actions --region 'region' --action-type ModelLifeCycle ``` Create a model package with ModelLifeCycle. ``` aws sagemaker create-model-package --model-package-group-name 'model-package-group-name' --source-uri 'source-uri' --region 'region' --model-life-cycle '{"Stage":"stage-name", "StageStatus":"stage-status", "StageDescription":"Your Staging Comment"}' ``` Update a model package with ModelLifeCycle. ``` aws sagemaker update-model-package --model-package 'model-package-arn' --region 'region' --model-life-cycle '{"Stage":"stage-name", "StageStatus":"stage-status"}' ``` Search via the ModelLifeCycle field. ``` aws sagemaker search --region 'region' --resource ModelPackage --search-expression '{"Filters": [{"Name": "ModelLifeCycle.Stage","Value": "stage-name"}]}' ``` Fetch audit records for ModelLifeField updates via [Amazon SageMaker ML Lineage Tracking](lineage-tracking.md) APIs. ``` aws sagemaker list-actions --region 'region' --action-type ModelLifeCycle ``` ``` aws sagemaker describe-action --region 'region' --action-name 'action-arn or action-name' ``` # Get event notifications for ModelLifeCycle You can get the ModelLifeCycle update notifications and events with EventBridge in your account. The following is an example of an EventBridge rule, to be configured in your account, in order to get the ModelLifeCycle event notifications. ``` { "source": ["aws.sagemaker"], "detail-type": ["SageMaker Model Package State Change"] } ``` For an example EventBridge payload you may receive, see [SageMaker model package state change](automating-sagemaker-with-eventbridge.md#eventbridge-model-package).