# MLflow App Setup An [MLflow App](https://mlflow.org/docs/latest/tracking.html#mlflow-tracking-server-optional) is a stand-alone HTTP server that serves multiple REST API endpoints for tracking runs and experiments. An MLflow App is required to begin tracking your machine learning (ML) experiments with SageMaker AI and MLflow. You can create an MLflow App through the Studio UI, or through the AWS CLI for more granular security customization. You must have the correct IAM permissions configured to create an MLflow App. MLflow Apps are the latest managed MLflow offering on SageMaker and should be preferred over existing MLflow Tracking Servers. MLflow Apps offer additional features such as faster startup time, cross-account sharing, integrations with other SageMaker features, and other features beyond the existing MLflow Tracking Servers. **Topics** + [MLflow App Setup Prequisites](mlflow-app-setup-prerequisites.md) + [Create MLflow App](mlflow-app-setup-create-app.md) # MLflow App Setup Prequisites # Set up IAM permissions for MLflow Apps You must configure the necessary IAM service roles to get started with MLflow Apps in Amazon SageMaker AI. If you create a new Amazon SageMaker AI domain to access your experiments in Studio, you can configure the necessary IAM permissions during domain setup. For more information, see [Set up MLflow IAM permissions when creating a new domain](mlflow-create-tracking-server-iam.md#mlflow-create-tracking-server-iam-role-manager). To set up permissions using the IAM console, see [Create necessary IAM service roles in the IAM console](mlflow-create-tracking-server-iam.md#mlflow-create-tracking-server-iam-service-roles). You must configure authorization controls for `sagemaker-mlflow` actions. You can optionally define more granular authorization controls to govern action-specific MLflow permissions. For more information, see [Create action-specific authorization controls](#mlflow-create-app-update-iam-actions). ## Set up MLflow IAM permissions when creating a new domain When setting up a new Amazon SageMaker AI domain for your organization, you can configure IAM permissions for your domain service role through the **Users and ML Activities** settings. 1. Set up a new domain using the SageMaker AI console. On the **Set up SageMaker AI domain** page, choose **Set up for organizations**. For more information, see [Custom setup using the console](onboard-custom.md#onboard-custom-instructions-console). 1. When setting up **Users and ML Activities**, choose from the following ML activities for MLflow: **Use MLflow**, **Manage MLflow Apps**, and **Access required to AWS Services for MLflow**. For more information about these activities, see the explanations that follow this procedure. 1. Complete the setup and creation of your new domain. The following MLflow ML activities are available in Amazon SageMaker Role Manager: + **Use MLflow**: This ML activity grants the domain service role permission to call MLflow REST APIs in order to manage experiments, runs, and models in MLflow. + **Manage MLflow Apps**: This ML activity grants the domain service role permission to create, update, and delete MLflow Apps. + **Access required to AWS services for MLflow Apps**: This ML activity provides the domain service role permissions needed to access Amazon S3 and the SageMaker AI Model Registry. This allows you to use the domain service role as the tracking server service role. For more information about ML activities in Role Manager, see [ML activity reference](role-manager-ml-activities.md). ## Create necessary IAM service roles in the IAM console If you did not create or update your domain service role, you must instead create the following service roles in the IAM console in order to create and use an MLflow Apps: + An MLflow App IAM service role that the App can use to access SageMaker AI resources + A SageMaker AI IAM service role that SageMaker AI can use to create and manage MLflow resources ### IAM policies for the MLflow App IAM service role The MLflow App IAM service role is used by the app to access the resources it needs such as Amazon S3 and the SageMaker Model Registry. When creating the app IAM service role, use the following IAM trust policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "sagemaker.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` ------ In the IAM console, add the following permissions policy to your app service role: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:Get*", "s3:Put*", "s3:List*", "sagemaker:AddTags", "sagemaker:CreateModelPackageGroup", "sagemaker:CreateModelPackage", "sagemaker:UpdateModelPackage", "sagemaker:DescribeModelPackageGroup" ], "Resource": "*" } ] } ``` ------ ### IAM policy for the SageMaker AI IAM service role The SageMaker AI service role is used by the client accessing the MLflow App and needs permissions to call MLflow REST APIs. The SageMaker AI service role also needs SageMaker API permissions to create, view update, and delete apps. You can create a new role or update an existing role. The SageMaker AI service role needs the following policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sagemaker-mlflow:*", "sagemaker:CreateMlflowTrackingServer", "sagemaker:ListMlflowTrackingServers", "sagemaker:UpdateMlflowTrackingServer", "sagemaker:DeleteMlflowTrackingServer", "sagemaker:StartMlflowTrackingServer", "sagemaker:StopMlflowTrackingServer", "sagemaker:CreatePresignedMlflowTrackingServerUrl" ], "Resource": "*" } ] } ``` ------ ## Create action-specific authorization controls You must set up authorization controls for `sagemaker-mlflow`, and can optionally configure action-specific authorization controls to govern more granular MLflow permissions that your users have on an MLflow Apps. **Note** The following steps assume that you have an ARN for an MLflow Apps already available. ### Data Plane IAM actions supported for MLflow Apps The following SageMaker AI MLflow actions are supported for authorization access control: + sagemaker:CallMlflowAppApi # Create MLflow App # Create an app using the AWS CLI You can create an app using the AWS CLI for more granular security customization. ## Prerequisites To create an app using the AWS CLI, you must have the following: + **Access to a terminal. **This can include local IDEs, an Amazon EC2 instance, or AWS CloudShell. + **Access to a development environment.** This can include local IDEs or a Jupyter notebook environment within Studio or Studio Classic. + **A configured AWS CLI installation**. For more information, see [Configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). + **An IAM role with appropriate permissions**. The following steps require your environment to have `iam:CreateRole`, `iam:CreatePolicy`, `iam:AttachRolePolicy`, and `iam:ListPolicies` permissions. These permissions are needed on the role that is being used to run the steps in this user guide. The instructions in this guide create an IAM role that is used as the execution role of the MLflow App so that it can access data in your Amazon S3 buckets. Additionally, a policy is created to give the IAM role of the user that is interacting with the App via the MLflow SDK permission to call MLflow APIs. For more information, see [Modifying a role permissions policy (console) ](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-modify_permissions-policy). If using a SageMaker Studio Notebook, update the service role for your Studio user profile with these IAM permissions. To update the service role, navigate to the SageMaker AI console and select the domain you are using. Then, under the domain, select the user profile you are using. You will see the service role listed there. Navigate to the IAM console, search for the service role under **Roles**, and update your role with a policy that allows the `iam:CreateRole`, `iam:CreatePolicy`, `iam:AttachRolePolicy`, and `iam:ListPolicies` actions. ## Set up AWS CLI model Follow these command line steps within a terminal to set up the AWS CLI for Amazon SageMaker AI with MLflow. 1. Install an updated version of the AWS CLI. For more information, see [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS CLI User Guide*. 1. Verify that the AWS CLI is installed using the following command: ``` aws sagemaker help ``` Press `q` to exit the prompt. For troubleshooting help, see [Troubleshoot common setup issues](mlflow-troubleshooting.md). ## Set up MLflow infrastructure The following section shows you how to set up an MLflow App along with the Amazon S3 bucket and IAM role needed for the app. ### Create an S3 bucket Within your terminal, use the following commands to create a general purpose Amazon S3 bucket: **Important** When you provide the Amazon S3 URI for your artifact store, ensure the Amazon S3 bucket is in the same AWS Region as your MLflow App. **Cross-region artifact storage is not supported**. ``` bucket_name=bucket-name region=valid-region aws s3api create-bucket \ --bucket $bucket_name \ --region $region \ --create-bucket-configuration LocationConstraint=$region ``` The output should look similar to the following: ``` { "Location": "/bucket-name" } ``` ### Set up IAM trust policies Use the following steps to create an IAM trust policy. For more information about roles and trust policies, see [Roles terms and concepts](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html) in the *AWS Identity and Access Management User Guide*. 1. Within your terminal, use the following command to create a file called `mlflow-trust-policy.json`. ``` cat < /tmp/mlflow-trust-policy.json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "sagemaker.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } EOF ``` 1. Within your terminal, use the following command to create a file called `custom-policy.json`. ``` cat < /tmp/custom-policy.json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:Get*", "s3:Put*", "sagemaker:AddTags", "sagemaker:CreateModelPackageGroup", "sagemaker:CreateModelPackage", "sagemaker:DescribeModelPackageGroup", "sagemaker:UpdateModelPackage", "s3:List*" ], "Resource": "*" } ] } EOF ``` 1. Use the trust policy file to create a role. Then, attach IAM role policies that allow MLflow to access Amazon S3 and SageMaker Model Registry within your account. MLflow must have access to Amazon S3 for your app's artifact store and SageMaker Model Registry for automatic model registration. **Note** If you are updating an existing role, use the following command instead: `aws iam update-assume-role-policy --role-name $role_name --policy-document file:///tmp/mlflow-trust-policy.json`. ``` role_name=role-name aws iam create-role \ --role-name $role_name \ --assume-role-policy-document file:///tmp/mlflow-trust-policy.json aws iam put-role-policy \ --role-name $role_name \ --policy-name custom-policy \ --policy-document file:///tmp/custom-policy.json role_arn=$(aws iam get-role --role-name $role_name --query 'Role.Arn' --output text) ``` ## Create MLflow App Within your terminal, use the `create-mlflow-app` API to create an app in the AWS Region of your choice. This step normally takes approximately 2-3 minutes. The following command creates a new app with automatic model registration enabled. To deactivate automatic model registration, specify `--no-automatic-model-registration`. After creating your app, you can launch the MLflow UI. For more information, see [Launch the MLflow UI using a presigned URL](mlflow-launch-ui.md). **Note** It may take up to 2-3 minutes to complete app creation. If the app takes over 3 minutes to create, check that you have the necessary IAM permissions. When you successfully create an app, it automatically starts. By default, the app that is created is the latest version and will be automatically updated. ``` app_name=app-name region=valid-region version=valid-version aws sagemaker create-mlflow-app \ --name $app_name \ --artifact-store-uri s3://$bucket_name \ --role-arn $role_arn \ --automatic-model-registration \ --region $region ``` The output should be similar to the following: ``` { "AppArn": "arn:aws:sagemaker:region:123456789012:mlflow-app/app-name" } ``` **Important** **Take note of the app ARN for later use.** You will also need the `$bucket_name` for clean up steps.