# RStudio on Amazon SageMaker AI RStudio RStudio is an integrated development environment for R, with a console, syntax-highlighting editor that supports direct code execution, and tools for plotting, history, debugging and workspace management. Amazon SageMaker AI supports RStudio as a fully-managed integrated development environment (IDE) integrated with Amazon SageMaker AI domain through Posit Workbench. RStudio allows customers to create data science insights using an R environment. With RStudio integration, you can launch an RStudio environment in the domain to run your RStudio workflows on SageMaker AI resources. For more information about Posit Workbench, see the [Posit website](https://posit.co/products/enterprise/workbench/). This page gives information about important RStudio concepts. SageMaker AI integrates RStudio through the creation of a RStudioServerPro app. The following are supported by RStudio on SageMaker AI. + R developers use the RStudio IDE interface with popular developer tools from the R ecosystem. Users can launch new RStudio sessions, write R code, install dependencies from RStudio Package Manager, and publish Shiny apps using RStudio Connect. + R developers can quickly scale underlying compute resources to run large scale data processing and statistical analysis.  + Platform administrators can set up user identities, authorization, networking, storage, and security for their data science teams through AWS IAM Identity Center and AWS Identity and Access Management integration. This includes connection to private Amazon Virtual Private Cloud (Amazon VPC) resources and internet-free mode with AWS PrivateLink. + Integration with AWS License Manager. For information on the onboarding steps to create a domain with RStudio enabled, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md). ## Region availability The following table gives information about the AWS Regions that RStudio on SageMaker AI is supported in. | Region name | Region | | --- | --- | | US East (Ohio) | us-east-2 | | US East (N. Virginia) | us-east-1 | | US West (N. California) | us-west-1 | | US West (Oregon) | us-west-2 | | Asia Pacific (Mumbai) | ap-south-1 | | Asia Pacific (Seoul) | ap-northeast-2 | | Asia Pacific (Singapore) | ap-southeast-1 | | Asia Pacific (Sydney) | ap-southeast-2 | | Asia Pacific (Tokyo) | ap-northeast-1 | | Canada (Central) | ca-central-1 | | Europe (Frankfurt) | eu-central-1 | | Europe (Ireland) | eu-west-1 | | Europe (London) | eu-west-2 | | Europe (Paris) | eu-west-3 | | Europe (Stockholm) | eu-north-1 | | South America (São Paulo) | sa-east-1 | ## RStudio components + *RStudioServerPro*: The RStudioServerPro app is a multiuser app that is a shared resource among all user profiles in the domain. Once an RStudio app is created in a domain, the admin can give permissions to users in the domain.  + *RStudio user*: RStudio users are users within the domain that are authorized to use the RStudio license. + *RStudio admin*: An RStudio on Amazon SageMaker AI admin can access the RStudio administrative dashboard. RStudio on Amazon SageMaker AI admins differ from "stock" Posit Workbench admins because they do not have root access to the instance running the RStudioServerPro app and can't modify the RStudio configuration file. + *RStudio Server*: The RStudio Server instance is responsible for serving the RStudio UI to all authorized Users. This instance is launched on an Amazon SageMaker AI instance. + *RSession*: An RSession is a browser-based interface to the RStudio IDE running on an Amazon SageMaker AI instance. Users can create and interact with their RStudio projects through the RSession. + *RSessionGateway*: The RSessionGateway app is used to support an RSession. + *RStudio administrative dashboard*: This dashboard gives information on the RStudio users in the Amazon SageMaker AI domain and their sessions. This dashboard can only be accessed by users that have RStudio admin authorization. ## Differences from Posit Workbench RStudio on Amazon SageMaker AI has some significant differences from [Posit Workbench](https://posit.co/products/enterprise/workbench/). + When using RStudio on SageMaker AI, users don’t have access to the RStudio configuration files. Amazon SageMaker AI manages the configuration file and sets defaults. You can modify the RStudio Connect and RStudio Package Manager URLs when creating your RStudio-enabled Amazon SageMaker AI domain. + Project sharing, realtime collaboration, and Job Launcher are not currently supported when using RStudio on Amazon SageMaker AI. + When using RStudio on SageMaker AI, the RStudio IDE runs on Amazon SageMaker AI instances for on-demand containerized compute resources. + RStudio on SageMaker AI only supports the RStudio IDE and does not support other IDEs supported by a Posit Workbench installation. + RStudio on SageMaker AI only supports the RStudio version specified in [RStudio Versioning](rstudio-version.md). # RStudio on Amazon SageMaker AI management RStudio on SageMaker AI management The following topics give information on managing RStudio on Amazon SageMaker AI. This includes information about your RStudio environment configuration, user sessions, and necessary resources. For information on how to use RStudio on SageMaker AI, see [RStudio on Amazon SageMaker AI user guide](rstudio-use.md). For information about creating a Amazon SageMaker AI domain with RStudio enabled, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md).  For information about the AWS Regions that RStudio on SageMaker AI is supported in, see [Supported Regions and Quotas](regions-quotas.md).  **Topics** + [ # Get an RStudio license ](rstudio-license.md) + [ # RStudio Versioning ](rstudio-version.md) + [ # Network and Storage ](rstudio-network.md) + [ # RStudioServerPro instance type ](rstudio-select-instance.md) + [ # Add an RStudio Connect URL ](rstudio-configure-connect.md) + [ # Update the RStudio Package Manager URL ](rstudio-configure-pm.md) + [ # Create an Amazon SageMaker AI domain with RStudio using the AWS CLI ](rstudio-create-cli.md) + [ # Add RStudio support to an existing domain ](rstudio-add-existing.md) + [ # Custom images with RStudio on SageMaker AI ](rstudio-byoi.md) + [ # Create a user to use RStudio ](rstudio-create-user.md) + [ # Log in to RStudio as another user ](rstudio-login-another.md) + [ # Terminate sessions for another user ](rstudio-terminate-another.md) + [ # Use the RStudio administrative dashboard ](rstudio-admin.md) + [ # Shut down RStudio ](rstudio-shutdown.md) + [ # Billing and cost ](rstudio-billing.md) + [ # Diagnose issues and get support ](rstudio-troubleshooting.md) # Get an RStudio license RStudio on Amazon SageMaker AI is a paid product and requires that each user is appropriately licensed. Licenses for RStudio on Amazon SageMaker AI may be obtained from RStudio PBC directly, or by purchasing a subscription to Posit Workbench on AWS Marketplace. For existing customers of Posit Workbench Enterprise, licenses are issued at no additional cost. To use an RStudio license with Amazon SageMaker AI, you must first have a valid RStudio license registered with AWS License Manager. For licenses purchased directly through Rstudio PBC, a licenses grant for your AWS Account must be created. Contact RStudio for direct license purchases or to enable existing licenses in AWS License Manager. For more information about registering a license with AWS License Manager, see [Seller issued licenses in AWS License Manager](https://docs.aws.amazon.com/license-manager/latest/userguide/seller-issued-licenses.html). The following topics show how to acquire and validate a license granted by RStudio PBC. **Get an RStudio license** 1. If you don't have an RStudio license, you may purchase one from the AWS Marketplace or from RStudio PBC directly. + To purchase a subscription from the AWS Marketplace, complete the steps to [subscribe with a SaaS contract](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-saas-products.html) by searching for **Posit Team**. To fulfill the license, you will be redirected to an external form outside the AWS Marketplace. You must provide additional information, including your company name and email address. If you can’t access that form to provide a company name and a contact email, create a ticket with Posit Support at [https://support.posit.co/hc/en-us/requests/new](https://support.posit.co/hc/en-us/requests/new) with details about your purchase. + To purchase from RStudio PBC directly, navigate to [RStudio Pricing](https://www.rstudio.com/pricing/) or contact [sales@rstudio.com](mailto:sales@rstudio.com). When buying or updating an RStudio license, you must provide the AWS Account that will host your Amazon SageMaker AI domain. If you have an existing RStudio license, contact your RStudio Sales representative or [sales@rstudio.com](mailto:sales@rstudio.com) to add RStudio on Amazon SageMaker AI to your existing Posit Workbench Enterprise license, or to convert your Posit Workbench Standard license. The RStudio Sales representative will send you the appropriate electronic order form. 1. RStudio grants a Posit Workbench license to your AWS Account through AWS License Manager in the US East (N. Virginia) Region. Although the RStudio license is granted in the US East (N. Virginia) Region, your license can be consumed in any AWS Region that RStudio on Amazon SageMaker AI is supported in. You can expect the license grant process to complete within three business days after you share your AWS account ID with RStudio. 1. When this license is granted, you receive an email from your RStudio Sales representative with instructions to accept your license grant. **Validate your RStudio license to be used with Amazon SageMaker AI** 1. Log into the AWS License Manager console in the same region as your Amazon SageMaker AI domain. If you are using AWS License Manager for the first time, AWS License Manager prompts you to grant permission to use AWS License Manager. 1. Select **Start using AWS License manager**. 1. Select `I grant AWS License Manager the required permissions` and select **Grant Permissions**. 1. Navigate to **Granted Licenses** on the left panel. 1. Select the license grant with `RSW-SageMaker` as the `Product name` and select **View**. 1. From the license detail page, select **Accept & activate license**. **RStudio administrative dashboard** You can use the RStudio administrative dashboard to see the number of users on the license following the steps in [Use the RStudio administrative dashboard](rstudio-admin.md). # RStudio Versioning **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. This guide provides information about the `2025.05.1+513.pro3` version update for RStudio on SageMaker AI. Starting October 31, 2025, new domains with RStudio support are created with Posit Workbench version `2025.05.1+513.pro3`. This applies to the `RStudioServerPro` applications and default `RSessionGateway` applications. The following sections provide information about the `2025.05.1+513.pro3` release. ## Latest version updates The latest RStudio version is `2025.05.1+513.pro3`. + R versions supported: + 4.5.1 + 4.4.3 + 4.4.0 + 4.3.3 + 4.2.3 + 4.2.1 + 4.1.3 + 4.0.2 For more information about the changes in this release, see [https://docs.posit.co/ide/news/](https://docs.posit.co/ide/news/). **Note** To ensure compatibility, we recommend using RSessions with a prefix that matches the current Posit Workbench version. If you see the following warning, there is a version mismatch between the `RSession` and the Posit Workbench version used in RStudio on SageMaker AI. To resolve this issue, update the RStudio version for the domain. For information about updating the RStudio version, see [Upgrade to the new version](rstudio-version-upgrade.md). ``` Session version 2024.04.2+764.pro1 does not match server version 2025.05.1+513.pro3 - this is an unsupported configuration, and you may experience unexpected issues as a result. ``` ## Versioning There are currently two versions of Posit Workbench supported by SageMaker AI. + Latest version: `2025.05.1+513.pro3` Deprecation Date: December 5, 2026 + Previous version: `2024.04.2+764.pro1` Deprecation Date: April 30, 2026 **Note** While you can continue creating new domains with the older version `2024.04.2+764.pro1` until 04/30/2026 by explicitly pinning the version when you create the domain using CLI, we strongly recommend customers to begin using the `2025.05` version in all domains. POSIT has ceased providing vulnerability fixes for `2024.04.2+764.pro1`. Versions `2023.03.2-547.pro5` and `2022.02.2-485.pro2` are deprecated and are no longer supported. We recommend updating to the latest version. The default Posit Workbench version that SageMaker AI selects depends on the creation date of the domain. + For domains created after October 31, 2025, version `2025.05.1+513.pro3` is the default selected version. + For domains created after September 04, 2024 and before October 31, 2025, version `2024.04.2+764.pro1` is the default selected version. You can update your domains to the latest version (`2025.05.1+513.pro3`) by setting it as the default version for the domain. For more information, see [Upgrade to the new version](rstudio-version-upgrade.md). **Note** The default `RSessionGateway` application version matches the current version of the `RStudioServerPro` application. The following table lists the image ARNs for both versions for each AWS Region. These ARNs are passed as part of an `update-domain` command to set the desired version. | Region | `2024.04.2+764.pro1` Image ARN | `2025.05.1+513.pro3` Image ARN | | --- | --- | --- | | us-east-1 | arn:aws:sagemaker:us-east-1:081325390199:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:us-east-1:081325390199:image/rstudio-workbench-2025.05-sagemaker-1.0 | | us-east-2 | arn:aws:sagemaker:us-east-2:429704687514:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:us-east-2:429704687514:image/rstudio-workbench-2025.05-sagemaker-1.0 | | us-west-1 | arn:aws:sagemaker:us-west-1:742091327244:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:us-west-1:742091327244:image/rstudio-workbench-2025.05-sagemaker-1.0 | | us-west-2 | arn:aws:sagemaker:us-west-2:236514542706:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:us-west-2:236514542706:image/rstudio-workbench-2025.05-sagemaker-1.0 | | af-south-1 | arn:aws:sagemaker:af-south-1:559312083959:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:af-south-1:559312083959:image/rstudio-workbench-2025.05-sagemaker-1.0 | | ap-east-1 | arn:aws:sagemaker:ap-east-1:493642496378:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:ap-east-1:493642496378:image/rstudio-workbench-2025.05-sagemaker-1.0 | | ap-south-1 | arn:aws:sagemaker:ap-south-1:394103062818:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:ap-south-1:394103062818:image/rstudio-workbench-2025.05-sagemaker-1.0 | | ap-northeast-2 | arn:aws:sagemaker:ap-northeast-2:806072073708:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:ap-northeast-2:806072073708:image/rstudio-workbench-2025.05-sagemaker-1.0 | | ap-southeast-1 | arn:aws:sagemaker:ap-southeast-1:492261229750:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:ap-southeast-1:492261229750:image/rstudio-workbench-2025.05-sagemaker-1.0 | | ap-southeast-2 | arn:aws:sagemaker:ap-southeast-2:452832661640:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:ap-southeast-2:452832661640:image/rstudio-workbench-2025.05-sagemaker-1.0 | | ap-northeast-1 | arn:aws:sagemaker:ap-northeast-1:102112518831:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:ap-northeast-1:102112518831:image/rstudio-workbench-2025.05-sagemaker-1.0 | | ca-central-1 | arn:aws:sagemaker:ca-central-1:310906938811:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:ca-central-1:310906938811:image/rstudio-workbench-2025.05-sagemaker-1.0 | | eu-central-1 | arn:aws:sagemaker:eu-central-1:936697816551:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:eu-central-1:936697816551:image/rstudio-workbench-2025.05-sagemaker-1.0 | | eu-west-1 | arn:aws:sagemaker:eu-west-1:470317259841:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:eu-west-1:470317259841:image/rstudio-workbench-2025.05-sagemaker-1.0 | | eu-west-2 | arn:aws:sagemaker:eu-west-2:712779665605:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:eu-west-2:712779665605:image/rstudio-workbench-2025.05-sagemaker-1.0 | | eu-west-3 | arn:aws:sagemaker:eu-west-3:615547856133:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:eu-west-3:615547856133:image/rstudio-workbench-2025.05-sagemaker-1.0 | | eu-north-1 | arn:aws:sagemaker:eu-north-1:243637512696:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:eu-north-1:243637512696:image/rstudio-workbench-2025.05-sagemaker-1.0 | | eu-south-1 | arn:aws:sagemaker:eu-south-1:592751261982:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:eu-south-1:592751261982:image/rstudio-workbench-2025.05-sagemaker-1.0 | | sa-east-1 | arn:aws:sagemaker:sa-east-1:782484402741:image/rstudio-workbench-2024.04-sagemaker-1.1 | arn:aws:sagemaker:sa-east-1:782484402741:image/rstudio-workbench-2025.05-sagemaker-1.0 | ### Changes to BYOI Images If you use a BYOI image with RStudio and update your `RStudioServerPro` version to `2025.05.1+513.pro3`, you must upgrade your custom images to use the `2025.05.1+513.pro3` release and redeploy your existing RSessions. If you attempt to load a non-compatible image in an RSession of a domain using the `2025.05.1+513.pro3` version, the RSession fails because it cannot parse parameters that it receives. To prevent failure, update all of the deployed custom images in your existing `RStudioServerPro` application. The `RSW_VERSION` in the Dockerfile must be consistent with the Posit Workbench version used in RStudio on SageMaker AI. You can validate the current version in Posit Workbench. To do so, use the version name that's located in the lower left corner of the Posit Workbench launcher page. ``` ARG RSW_VERSION=2025.05.1+513.pro3 ENV RSTUDIO_FORCE_NON_ZERO_EXIT_CODE="1" ARG RSW_NAME=rstudio-workbench ARG OS_CODE_NAME=jammy ARG RSW_DOWNLOAD_URL=https://s3.amazonaws.com/rstudio-ide-build/server/${OS_CODE_NAME}/amd64 RUN RSW_VERSION_URL=`echo -n "${RSW_VERSION}" | sed 's/+/-/g'` \ && curl -o rstudio-workbench.deb ${RSW_DOWNLOAD_URL}/${RSW_NAME}-${RSW_VERSION_URL}-amd64.deb \ && gdebi -n ./rstudio-workbench.deb ``` # Upgrade to the new version Existing domains using version `2024.04.2+764.pro1` can upgrade to `2025.05.1+513.pro3` version in one of two ways: + Create a new domain from the AWS CLI with RStudio enabled. + Update an existing domain to use the `2025.05.1+513.pro3` version. The following procedure shows how to delete the RStudio application for an existing domain, set the default version to `2025.05.1+513.pro3`, and then create an RStudio application. 1. Delete the `RStudioServerPro` application and all `RSessionGateway` applications associated with your existing domain. For information about how to find your domain ID, see [View domains](domain-view.md). For more information about deleting applications, see [Shut down RStudio](rstudio-shutdown.md). ``` aws sagemaker delete-app \ --region region \     --domain-id domainId \     --user-profile-name domain-shared \     --app-type RStudioServerPro \     --app-name default ``` 1. If your domain is using RStudio version `2024.04.2+764.pro1`, update the domain to set `2025.05.1+513.pro3` as the default Posit Workbench version. The `SageMakerImageArn` value in the following `update-domain` command specifies the RStudio `2025.05.1+513.pro3` version as the default. This ARN must match the Region that your domain is in. For a list of all available ARNs, see [Versioning](rstudio-version.md#rstudio-version-new). Pass an execution role ARN for the domain that provides permissions to update the domain. ``` aws sagemaker update-domain \ --region region \ --domain-id domainId \ --domain-settings-for-update "{\"RStudioServerProDomainSettingsForUpdate\":{\"DefaultResourceSpec\": {\"SageMakerImageArn\": \"arn-for-2025.05.1+513.pro3-version\", \"InstanceType\": \"system\"}, \"DomainExecutionRoleArn\": \"execution-role-arn\"}}" ``` 1. Create a new `RStudioServerPro` application in the existing domain. ``` aws sagemaker create-app \ --region region     --domain-id domainId \     --user-profile-name domain-shared \     --app-type RStudioServerPro \     --app-name default ``` Your `RStudioServerPro` application is now updated to version `2025.05.1+513.pro3`. You can now relaunch your `RSessionGateway` applications. # Downgrade to a previous version You can manually downgrade the version of your existing RStudio application to the `2024.04.2+764.pro1` version. **To downgrade to a previous version** 1. Delete the `RStudioServerPro` application that's associated with your existing domain. For information about how to find your domain ID, see [View domains](domain-view.md). ``` aws sagemaker delete-app \     --domain-id domainId \     --user-profile-name domain-shared \     --app-type RStudioServerPro \     --app-name default ``` 1. Pass the corresponding `2024.04.2+764.pro1` ARN for your Region as part of the `update-domain` command. For a list of all available ARNs, see [Versioning](rstudio-version.md#rstudio-version-new). You must also pass an execution role ARN for the domain that provides permissions to update the domain. ``` aws sagemaker update-domain \ --region region \ --domain-id domainId \ --domain-settings-for-update "{\"RStudioServerProDomainSettingsForUpdate\":{\"DefaultResourceSpec\": {\"SageMakerImageArn\": \"arn-for-2024.04.2+764.pro1-version\", \"InstanceType\": \"system\"}, \"DomainExecutionRoleArn\": \"execution-role-arn\"}}" ``` 1. Create a new `RStudioServerPro` application in the existing domain. The RStudio version defaults to `2024.04.2+764.pro1`. ``` aws sagemaker create-app \     --domain-id domainId \     --user-profile-name domain-shared \     --app-type RStudioServerPro \     --app-name default ``` Your `RStudioServerPro` application is now downgraded to version `2024.04.2+764.pro1`. # Network and Storage The following topic describes network access and data storage considerations for your RStudio instance. For general information about network access and data storage when using Amazon SageMaker AI, see [Data Protection in Amazon SageMaker AI](data-protection.md). **Amazon EFS volume** RStudio on Amazon SageMaker AI shares an Amazon EFS volume with the Amazon SageMaker Studio Classic application in the domain. When the RStudio application is added to a domain, SageMaker AI creates a folder named `shared` in the Amazon EFS directory. If this `shared` folder is deleted or changed manually, then the RStudio application may no longer function. For more information about the Amazon EFS volume, see [Manage Your Amazon EFS Storage Volume in Amazon SageMaker Studio Classic](studio-tasks-manage-storage.md). **Installed packages and scripts** Packages that you install from within RStudio are scoped to the user profile level. This means that the installed package persists through RSession shut down, restarts, and across RSessions for each user profile that they are installed in. R Scripts that are saved in RSessions behave the same way. Both packages and R Scripts are saved in the user's Amazon EFS volume. **Encryption** RStudio on Amazon SageMaker AI supports encryption at rest. **Use RStudio in VPC-only mode** RStudio on Amazon SageMaker AI supports [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-services-overview.html) integration. With this integration, you can use RStudio on SageMaker AI in VPC-only mode without direct access to the internet. When you use RStudio in VPC-only mode, your security groups are automatically managed by the service. This includes connectivity between your RServer and your RSessions. The following are required to use RStudio in VPC-only mode. For more information on selecting a VPC, see [Choose an Amazon VPC](onboard-vpc.md). + A private subnet with either access the internet to make a call to Amazon SageMaker AI & License Manager, or Amazon Virtual Private Cloud (Amazon VPC) endpoints for both Amazon SageMaker AI & License Manager. + The domain cannot have any more than two associated Security Groups. + A Security Group ID for use with the domain in domain Settings. This must allow all outbound access. + A Security Group ID for use with the Amazon VPC endpoint. This security group must allow inbound traffic from the domain Security Group ID. + Amazon VPC Endpoint for `sagemaker.api` and AWS License Manager. This must be in the same Amazon VPC as the private subnet. # RStudioServerPro instance type When deciding which Amazon EC2 instance type to use for your RStudioServerPro app, the main factor to consider is bandwidth. Bandwidth is important because the RStudioServerPro instance is responsible for serving the RStudio UI to all users. This includes UI heavy workflows, such as generating figures, animations, and displaying many data rows. Therefore, there may be some UI performance degradation depending on the workload across all users. The following are the available instance types to use for your RStudioServerPro. For pricing information about these instances, see [Amazon SageMaker Pricing](https://aws.amazon.com/sagemaker/pricing/). + `system`: This instance type is recommended for Domains with low UI use. **Note** The `system` value is translated to `ml.t3.medium`. + `ml.c5.4xlarge`: This instance type is recommended for Domains with moderate UI use. + `ml.c5.9xlarge`: This instance type is recommended for Domains with heavy UI use. **Changing RStudio instance type** To change the instance type of your RStudioServerPro, pass the new instance type as part of a call to the `update-domain` CLI command. You then need to delete the existing RStudioServerPro app using the `delete-app` CLI command and create a new RStudioServerPro app using the `create-app` CLI command. # Add an RStudio Connect URL RStudio Connect is a publishing platform for Shiny applications, R Markdown reports, dashboards, plots, and more. RStudio Connect makes it easy to surface machine learning and data science insights by making hosting content simple and scalable. If you have an RStudio Connect server, then you can set the server as the default place where apps are published. For more information about RStudio Connect, see [RStudio Connect](https://www.rstudio.com/products/connect/). When you onboard to RStudio on Amazon SageMaker AI domain, an RStudio Connect server is not created. You can create an RStudio Connect server on an Amazon EC2 instance to use Connect with Amazon SageMaker AI domain. For information about how to set up your RStudio Connect server, see [Host RStudio Connect and Package Manager for ML development in RStudio on Amazon SageMaker AI](https://aws.amazon.com/blogs/machine-learning/host-rstudio-connect-and-package-manager-for-ml-development-in-rstudio-on-amazon-sagemaker/). **Add an RStudio Connect URL** If you have an RStudio Connect URL, you can update the default URL so that your RStudio Users can publish to it. 1. Navigate to the **domains** page. 1. Select the desired domain. 1. Choose **domain Settings**. 1. Under **General Settings**, select **Edit**. 1. From the new page, select **RStudio Settings** on the left side.  1. Under **RStudio Connect URL**, enter the RStudio Connect URL to add. 1. Select **Submit**. **CLI** You can set a default RStudio Connect URL when you create your domain. The only way to update your RStudio Connect URL from the AWS CLI is to delete your domain and create a new one with the updated RStudio Connect URL. # Update the RStudio Package Manager URL RStudio Package Manager is a repository management server used to organize and centralize packages across your organization. For more information on RStudio Package Manager, see [RStudio Package Manager](https://www.rstudio.com/products/package-manager/). If you don't supply your own Package Manager URL, Amazon SageMaker AI domain uses the default Package Manager repository when you onboard RStudio following the steps in [Amazon SageMaker AI domain overview](gs-studio-onboard.md). For more information, see [Host RStudio Connect and Package Manager for ML development in RStudio on Amazon SageMaker AI](https://aws.amazon.com/blogs/machine-learning/host-rstudio-connect-and-package-manager-for-ml-development-in-rstudio-on-amazon-sagemaker/). The following procedure shows how to update the Package Manager URL. **Update Package Manager URL** You can update the Package Manager URL used for your RStudio-enabled domain as follows. 1. Navigate to the **domains** page. 1. Select the desired domain. 1. Choose **domain Settings**. 1. Under **General Settings**, select **Edit**. 1. From the new page, select **RStudio Settings** on the left side.  1. Under **RStudio Package Manager**, enter your RStudio Package Manager URL. 1. Select **Submit**. **CLI** The only way to update your Package Manager URL from the AWS CLI is to delete your domain and create a new one with the updated Package Manager URL. # Create an Amazon SageMaker AI domain with RStudio using the AWS CLI **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. The following topic shows how to onboard to Amazon SageMaker AI domain with RStudio enabled using the AWS CLI. To onboard using the AWS Management Console, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md). ## Prerequisites + Install and configure [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) + Configure the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) with IAM credentials ## Create `DomainExecution` role To launch the RStudio App, you must provide a `DomainExecution` role. This role is used to determine whether RStudio needs to be launched as part of Amazon SageMaker AI domain creation. This role is also used by Amazon SageMaker AI to access the RStudio License and push RStudio logs.  **Note** The `DomainExecution` role should have at least AWS License Manager permissions to access RStudio License, and CloudWatch permissions to push logs in your account. The following procedure shows how to create the `DomainExecution` role with the AWS CLI. 1. Create a file named `assume-role-policy.json` with the following content. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": [ "sagemaker.amazonaws.com" ] } } ] } ``` ------ 1. Create the `DomainExecution` role. `` should be the AWS Region to launch your domain in. ``` aws iam create-role --region --role-name DomainExecution --assume-role-policy-document file://assume-role-policy.json ``` 1. Create a file named `domain-setting-policy.json` with the following content. This policy allows the RStudioServerPro app to access necessary resources and allows Amazon SageMaker AI to automatically launch an RStudioServerPro app when the existing RStudioServerPro app is in a `Deleted` or `Failed` status. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "license-manager:ExtendLicenseConsumption", "license-manager:ListReceivedLicenses", "license-manager:GetLicense", "license-manager:CheckoutLicense", "license-manager:CheckInLicense", "logs:CreateLogDelivery", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DeleteLogDelivery", "logs:Describe*", "logs:GetLogDelivery", "logs:GetLogEvents", "logs:ListLogDeliveries", "logs:PutLogEvents", "logs:PutResourcePolicy", "logs:UpdateLogDelivery", "sagemaker:CreateApp" ], "Resource": "*" } ] } ``` ------ 1. Create the domain setting policy that is attached to the `DomainExecution` role. Be aware of the `PolicyArn` from the response, you will need to enter that ARN in the following steps. ``` aws iam create-policy --region --policy-name domain-setting-policy --policy-document file://domain-setting-policy.json ``` 1. Attach `domain-setting-policy` to the `DomainExecution` role. Use the `PolicyArn` returned in the previous step. ``` aws iam attach-role-policy --role-name DomainExecution --policy-arn ``` ## Create Amazon SageMaker AI domain with RStudio App The RStudioServerPro app is launched automatically when you create a Amazon SageMaker AI domain using the `create-domain` CLI command with the `RStudioServerProDomainSettings` parameter specified. When launching the RStudioServerPro App, Amazon SageMaker AI checks for a valid RStudio license in the account and fails domain creation if the license is not found. The creation of a Amazon SageMaker AI domain differs based on the authentication method and the network type. These options must be used together, with one authentication method and one network connection type selected. For more information about the requirements to create a new domain, see [CreateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateDomain.html). The following authentication methods are supported. + `IAM Auth` + `SSO Auth` The following network connection types are supported: + `PublicInternet` + `VPCOnly` ### Authentication methods **IAM Auth Mode** The following shows how to create a Amazon SageMaker AI domain with RStudio enabled and an `IAM Auth` Network Type. For more information about AWS Identity and Access Management, see [What is IAM?](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html). + `DomainExecutionRoleArn` should be the ARN for the role created in the previous step. + `ExecutionRole` is the ARN of the role given to users in the Amazon SageMaker AI domain. + `vpc-id` should be the ID of your Amazon Virtual Private Cloud. `subnet-ids` should be a space-separated list of subnet IDs. For information about `vpc-id` and `subnet-ids`, see [VPCs and subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html). + `RStudioPackageManagerUrl` and `RStudioConnectUrl` are optional and should be set to the URLs of your RStudio Package Manager and RStudio Connect server, respectively. + `app-network-access-type` should be either `PublicInternetOnly` or `VPCOnly`. ``` aws sagemaker create-domain --region --domain-name \ --auth-mode IAM \ --default-user-settings ExecutionRole= \ --domain-settings RStudioServerProDomainSettings={RStudioPackageManagerUrl=<,RStudioConnectUrl=<,DomainExecutionRoleArn=} \ --vpc-id \ --subnet-ids \ --app-network-access-type ``` **Authentication using IAM Identity Center** The following shows how to create a Amazon SageMaker AI domain with RStudio enabled and an `SSO Auth` Network Type. AWS IAM Identity Center must be enabled for the region that the domain is launched on. For more information about IAM Identity Center, see [What is AWS IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). + `DomainExecutionRoleArn` should be the ARN for the role created in the previous step. + `ExecutionRole` is the ARN of the role given to users in the Amazon SageMaker AI domain. + `vpc-id` should be the ID of your Amazon Virtual Private Cloud. `subnet-ids` should be a space-separated list of subnet IDs. For information about `vpc-id` and `subnet-ids`, see [VPCs and subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html). + `RStudioPackageManagerUrl` and `RStudioConnectUrl` are optional and should be set to the URLs of your RStudio Package Manager and RStudio Connect server, respectively. + `app-network-access-type` should be either `PublicInternetOnly` or `VPCOnly`. ``` aws sagemaker create-domain --region --domain-name \ --auth-mode SSO \ --default-user-settings ExecutionRole= \ --domain-settings RStudioServerProDomainSettings={RStudioPackageManagerUrl=<,RStudioConnectUrl=<,DomainExecutionRoleArn=} \ --vpc-id \ --subnet-ids \ --app-network-access-type ``` ### Connection types **PublicInternet/Direct Internet network type** The following shows how to create a Amazon SageMaker AI domain with RStudio enabled and a `PublicInternet` Network Type. + `DomainExecutionRoleArn` should be the ARN for the role created in the previous step. + `ExecutionRole` is the ARN of the role given to users in the Amazon SageMaker AI domain. + `vpc-id` should be the ID of your Amazon Virtual Private Cloud. `subnet-ids` should be a space-separated list of subnet IDs. For information about `vpc-id` and `subnet-ids`, see [VPCs and subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html). + `RStudioPackageManagerUrl` and `RStudioConnectUrl` are optional and should be set to the URLs of your RStudio Package Manager and RStudio Connect server, respectively. + `auth-mode` should be either `SSO` or `IAM`. ``` aws sagemaker create-domain --region --domain-name \ --auth-mode \ --default-user-settings ExecutionRole= \ --domain-settings RStudioServerProDomainSettings={RStudioPackageManagerUrl=<,RStudioConnectUrl=<,DomainExecutionRoleArn=} \ --vpc-id \ --subnet-ids \ --app-network-access-type PublicInternetOnly ``` **VPCOnly mode** The following shows how to launch a Amazon SageMaker AI domain with RStudio enabled and a `VPCOnly` Network Type. For more information about using the `VPCOnly` network access type, see [Connect Studio notebooks in a VPC to external resources](studio-notebooks-and-internet-access.md). + `DomainExecutionRoleArn` should be the ARN for the role created in the previous step. + `ExecutionRole` is the ARN of the role given to users in the Amazon SageMaker AI domain. + `vpc-id` should be the ID of your Amazon Virtual Private Cloud. `subnet-ids` should be a space-separated list of subnet IDs. Your private subnet must be able to either access the internet to make a call to Amazon SageMaker AI, and AWS License Manager or have Amazon VPC endpoints for both Amazon SageMaker AI and AWS License Manager. For information about Amazon VPC endpoints, see [Interface Amazon VPC endpoints ](https://docs.aws.amazon.com/vpc/latest/privatelink/vpce-interface.html)For information about `vpc-id` and `subnet-ids`, see [VPCs and subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html). + `SecurityGroups` must allow outbound access to the Amazon SageMaker AI and AWS License Manager endpoints. + `auth-mode` should be either `SSO` or `IAM`. **Note** When using Amazon Virtual Private Cloud endpoints, the security group attached to your Amazon Virtual Private Cloud endpoints must allow inbound traffic from the security group you pass as part of the `domain-setting` parameter of the `create-domain` CLI call. With RStudio, Amazon SageMaker AI manages security groups for you. This means that Amazon SageMaker AI manages security group rules to ensure RSessions can access RStudioServerPro Apps. Amazon SageMaker AI creates one security group rule per user profile. ``` aws sagemaker create-domain --region --domain-name \ --auth-mode \ --default-user-settings SecurityGroups=,ExecutionRole= \ --domain-settings SecurityGroupIds=,RStudioServerProDomainSettings={DomainExecutionRoleArn=} \ --vpc-id \ --subnet-ids "" \ --app-network-access-type VPCOnly --app-security-group-management Service ``` Note: The RStudioServerPro app is launched by a special user profile named `domain-shared`. As a result, this app is not returned as part of `list-app` API calls by any other user profiles. You may have to increase the Amazon VPC quota in your account to increase the number of users. For more information, see [Amazon VPC quotas](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-security-groups). ## Verify domain creation Use the following command to verify that your domain has been created with a `Status` of `InService`. Your `domain-id` is appended to the domains ARN. For example, `arn:aws:sagemaker:::domain/`. ``` aws sagemaker describe-domain --domain-id --region ``` # Add RStudio support to an existing domain **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. If you have added an RStudio License through AWS License Manager, you can create a new Amazon SageMaker AI domain with support for RStudio on SageMaker AI. If you have an existing domain that does not support RStudio, you can add RStudio support to that domain without having to delete and recreate the domain.  The following topic outlines how to add this support. ## Prerequisites You must complete the following steps before you update your current domain to add support for RStudio on SageMaker AI.  + Install and configure [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) + Configure the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) with IAM credentials + Create a domain execution role following the steps in [Create a SageMaker AI Domain with RStudio using the AWS CLI](https://docs.aws.amazon.com/sagemaker/latest/dg/rstudio-create-cli.html#rstudio-create-cli-domainexecution). This domain-level IAM role is required by the RStudioServerPro app. The role requires access to AWS License Manager for verifying a valid Posit Workbench license and Amazon CloudWatch Logs for publishing server logs.  + Bring your RStudio license to AWS License Manager following the steps in [RStudio license](https://docs.aws.amazon.com/sagemaker/latest/dg/rstudio-license.html). + (Optional) If you want to use RStudio in `VPCOnly` mode, complete the steps in [RStudio in VPC-Only](https://docs.aws.amazon.com/sagemaker/latest/dg/rstudio-network.html). + Ensure that the security groups you have configured for each [UserProfile](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateUserProfile.html) in your domain meet the account-level quotas. When configuring the default user profile during domain creation, you can use the `DefaultUserSettings` parameter of the [CreateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateDomain.html) API to add `SecurityGroups` that are inherited by all the user profiles created in the domain. You can also provide additional security groups for a specific user as part of the `UserSettings` parameter of the [CreateUserProfile](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateUserProfile.html) API. If you have added security groups this way, you must ensure that the total number of security groups per user profile doesn’t exceed the maximum quota of 2 in `VPCOnly` mode and 4 in `PublicInternetOnly` mode. If the resulting total number of security groups for any user profile exceeds the quota, you can combine multiple security groups’ rules into one security group.  ## Add RStudio support to an existing domain After you have completed the prerequisites, you can add RStudio support to your existing domain. The following steps outline how to update your existing domain to add support for RStudio. ### Step 1: Delete all apps in the domain To add support for RStudio in your domain, SageMaker AI must update the underlying security groups for all existing user profiles. To complete this, you must delete and recreate all existing apps in the domain. The following procedure shows how to delete all of the apps. 1. List all of the apps in the domain. ``` aws sagemaker \   list-apps \ --domain-id-equals ``` 1. Delete each app for each user profile in the domain. ``` // JupyterServer apps aws sagemaker \ delete-app \ --domain-id  \ --user-profile-name  \ --app-type JupyterServer \ --app-name // KernelGateway apps aws sagemaker \ delete-app \ --domain-id  \ --user-profile-name  \ --app-type KernelGateway \ --app-name ``` ### Step 2 - Update all user profiles with the new list of security groups This is a one-time action that you must complete for all of the existing user profiles in your domain when you have refactored your existing security groups. This prevents you from hitting the quota for the maximum number of security groups. The `UpdateUserProfile` API call fails if the user has any apps that are in [InService](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeApp.html#sagemaker-DescribeApp-response-Status) status. Delete all apps, then call `UpdateUserProfile` API to update the security groups. **Note** The following requirement for `VPCOnly` mode outlined in [Connect Amazon SageMaker Studio Classic Notebooks in a VPC to External Resources](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-notebooks-and-internet-access.html#studio-notebooks-and-internet-access-vpc-only) is no longer needed when adding RStudio support because `AppSecurityGroupManagement` is managed by the SageMaker AI service: “[TCP traffic within the security group](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html#sg-rules-other-instances). This is required for connectivity between the JupyterServer app and the KernelGateway apps. You must allow access to at least ports in the range `8192-65535`.” ``` aws sagemaker \ update-user-profile \ --domain-id \ --user-profile-name  \ --user-settings "{\"SecurityGroups\": [\"\", \"\"]}" ``` ### Step 3 - Activate RStudio by calling the UpdateDomain API 1. Call the [UpdateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html) API to add support for RStudio on SageMaker AI. The `defaultusersettings` parameter is only needed if you have refactored the default security groups for your user profiles. + For `VPCOnly` mode: ``` aws sagemaker \ update-domain \ --domain-id \ --app-security-group-management Service \ --domain-settings-for-update RStudioServerProDomainSettingsForUpdate={DomainExecutionRoleArn=} \ --default-user-settings "{\"SecurityGroups\": [\"\", \"\"]}" ``` + For `PublicInternetOnly` mode: ``` aws sagemaker \ update-domain \ --domain-id  \    --domain-settings-for-update RStudioServerProDomainSettingsForUpdate={DomainExecutionRoleArn=} \ --default-user-settings "{\"SecurityGroups\": [\"\", \"\"]}" ``` 1. Verify that the domain status is `InService`. After the domain status is `InService`, support for RStudio on SageMaker AI is added. ``` aws sagemaker \ describe-domain \ --domain-id  ``` 1. Verify that the RStudioServerPro app’s status is `InService` using the following command. ``` aws sagemaker list-apps --user-profile-name domain-shared ``` ### Step 4 - Add RStudio access for existing users As part of the update in Step 3, SageMaker AI marks the RStudio [AccessStatus](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RStudioServerProAppSettings.html#sagemaker-Type-RStudioServerProAppSettings-AccessStatus) of all existing user profiles in the domain as `DISABLED` by default. This prevents exceeding the number of users allowed by your current license. To add access for existing users, there is a one-time opt-in step. Perform the opt-in by calling the [UpdateUserProfile](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateUserProfile.html) API with the following [RStudioServerProAppSettings](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UserSettings.html#sagemaker-Type-UserSettings-RStudioServerProAppSettings): + `AccessStatus` = `ENABLED` + *Optional* - `UserGroup` = `R_STUDIO_USER` or `R_STUDIO_ADMIN` ``` aws sagemaker \ update-user-profile \ --domain-id \ --user-profile-name  \ --user-settings "{\"RStudioServerProAppSettings\": {\"AccessStatus\": \"ENABLED\"}}" ``` **Note** By default, the number of users that can have access to RStudio is 60. ### Step 5 – Deactivate RStudio access for new users Unless otherwise specified when calling `UpdateDomain`, RStudio support is added by default for all new user profiles created after you have added support for RStudio on SageMaker AI. To deactivate access for a new user profile, you must explicitly set the `AccessStatus` parameter to `DISABLED` as part of the `CreateUserProfile` API call. If the `AccessStatus` parameter is not specified as part of the `CreateUserProfile` API, the default access status is `ENABLED`. ``` aws sagemaker \ create-user-profile \ --domain-id \ --user-profile-name  \ --user-settings "{\"RStudioServerProAppSettings\": {\"AccessStatus\": \"DISABLED\"}}" ``` # Custom images with RStudio on SageMaker AI Bring your own image A SageMaker image is a file that identifies language packages and other dependencies that are required to run RStudio on Amazon SageMaker AI. SageMaker AI uses these images to create an environment where you run RStudio. Amazon SageMaker AI provides a built-in RStudio image for you to use. If you need different functionality, you can bring your own custom images. This page gives information about key concepts for using custom images with RStudio on SageMaker AI. The process to bring your own image to use with RStudio on SageMaker AI takes three steps: 1. Build a custom image from a Dockerfile and push it to a repository in Amazon Elastic Container Registry (Amazon ECR). 1. Create a SageMaker image that points to a container image in Amazon ECR and attach it to your Amazon SageMaker AI domain. 1. Launch a new session in RStudio with your custom image. You can create images and image versions, and attach image versions to your domain, using the SageMaker AI control panel, the [AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html), and the [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/). You can also create images and image versions using the SageMaker AI console, even if you haven't onboarded to a domain. The following topics show how to bring your own image to RStudio on SageMaker AI by creating, attaching, and launching a custom image. ## Key terminology The following section defines key terms for bringing your own image to use with RStudio on SageMaker AI. + **Dockerfile:** A Dockerfile is a file that identifies the language packages and other dependencies for your Docker image. + **Docker image:** The Docker image is a built Dockerfile. This image is checked into Amazon ECR and serves as the basis of the SageMaker AI image. + **SageMaker image:** A SageMaker image is a holder for a set of SageMaker image versions based on Docker images. + **Image version:** An image version of a SageMaker image represents a Docker image that is compatible with RStudio and stored in an Amazon ECR repository. Each image version is immutable. These image versions can be attached to a domain and used with RStudio on SageMaker AI. # Complete prerequisites You must complete the following prerequisites before bringing your own image to use with RStudio on Amazon SageMaker AI. + If you have an existing domain with RStudio that was created before April 7, 2022, you must delete your RStudioServerPro application and recreate it. For information about how to delete an application, see [Shut Down and Update Amazon SageMaker Studio Classic](studio-tasks-update-studio.md). + Install the Docker application. For information about setting up Docker, see [Orientation and setup](https://docs.docker.com/get-started/). + Create a local copy of an RStudio-compatible Dockerfile that works with SageMaker AI. For information about creating a sample RStudio dockerfile, see [Use a custom image to bring your own development environment to RStudio on Amazon SageMaker AI](https://aws.amazon.com/blogs/machine-learning/use-a-custom-image-to-bring-your-own-development-environment-to-rstudio-on-amazon-sagemaker/). + Use an AWS Identity and Access Management execution role that has the [AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess) policy attached. If you have onboarded to domain, you can get the role from the **domain Summary** section of the SageMaker AI control panel. Add the following permissions to access the Amazon Elastic Container Registry (Amazon ECR) service to your execution role. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid": "VisualEditor0", "Effect":"Allow", "Action":[ "ecr:CreateRepository", "ecr:BatchGetImage", "ecr:CompleteLayerUpload", "ecr:DescribeImages", "ecr:DescribeRepositories", "ecr:UploadLayerPart", "ecr:ListImages", "ecr:InitiateLayerUpload", "ecr:BatchCheckLayerAvailability", "ecr:PutImage" ], "Resource": "*" } ] } ``` ------ + Install and configure AWS CLI with the following (or higher) version. For information about installing the AWS CLI, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). ``` AWS CLI v1 >= 1.23.6 AWS CLI v2 >= 2.6.2 ``` # Custom RStudio image specifications Custom image specifications In this guide, you'll learn custom RStudio image specifications to use when you bring your own image. There are two sets of requirements that you must satisfy with your custom RStudio image to use it with Amazon SageMaker AI. These requirements are imposed by RStudio PBC and the Amazon SageMaker Studio Classic platform. If either of these sets of requirements aren't satisfied, then your custom image won't function properly. ## RStudio PBC requirements RStudio PBC requirements are laid out in the [Using Docker images with RStudio Workbench / RStudio Server Pro, Launcher, and Kubernetes](https://support.rstudio.com/hc/en-us/articles/360019253393-Using-Docker-images-with-RStudio-Server-Pro-Launcher-and-Kubernetes) article. Follow the instructions in this article to create the base of your custom RStudio image. For instructions about how to install multiple R versions in your custom image, see [Installing multiple versions of R on Linux](https://support.rstudio.com/hc/en-us/articles/215488098). ## Amazon SageMaker Studio Classic requirements Amazon SageMaker Studio Classic imposes the following set of installation requirements for your RStudio image. + You must use an RStudio base image of at least `2025.05.1+513.pro3`. For more information, see [RStudio Versioning](rstudio-version.md). + You must install the following packages: ``` yum install -y sudo \ openjdk-11-jdk \ libpng-dev \ && yum clean all \ && /opt/R/${R_VERSION}/bin/R -e "install.packages('reticulate', repos='https://packagemanager.rstudio.com/cran/__linux__/centos7/latest')" \ && /opt/python/${PYTHON_VERSION}/bin/pip install --upgrade \ 'boto3>1.0<2.0' \ 'awscli>1.0<2.0' \ 'sagemaker[local]<3' ``` + You must provide default values for the `RSTUDIO_CONNECT_URL` and `RSTUDIO_PACKAGE_MANAGER_URL` environment values. ``` ENV RSTUDIO_CONNECT_URL "YOUR_CONNECT_URL" ENV RSTUDIO_PACKAGE_MANAGER_URL "YOUR_PACKAGE_MANAGER_URL" ENV RSTUDIO_FORCE_NON_ZERO_EXIT_CODE 1 ``` The following general specifications apply to the image that is represented by an RStudio image version. **Running the image** `ENTRYPOINT` and `CMD` instructions are overridden so that the image is run as an RSession application. **Stopping the image** The `DeleteApp` API issues the equivalent of a `docker stop` command. Other processes in the container won’t get the SIGKILL/SIGTERM signals. **File system** The `/opt/.sagemakerinternal` and `/opt/ml` directories are reserved. Any data in these directories might not be visible at runtime. **User data** Each user in a SageMaker AI domain gets a user directory on a shared Amazon Elastic File System volume in the image. The location of the current user’s directory on the Amazon Elastic File System volume is `/home/sagemaker-user`. **Metadata** A metadata file is located at `/opt/ml/metadata/resource-metadata.json`. No additional environment variables are added to the variables defined in the image. For more information, see [Get App Metadata](notebooks-run-and-manage-metadata.md#notebooks-run-and-manage-metadata-app). **GPU** On a GPU instance, the image is run with the `--gpus` option. Only the CUDA toolkit should be included in the image, not the NVIDIA drivers. For more information, see [NVIDIA User Guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/user-guide.html). **Metrics and logging** Logs from the RSession process are sent to Amazon CloudWatch in the customer’s account. The name of the log group is `/aws/sagemaker/studio`. The name of the log stream is `$domainID/$userProfileName/RSession/$appName`. **Image size** Image size is limited to 25 GB. To view the size of your image, run `docker image ls`. # Create a custom RStudio image Create an image **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. This topic describes how you can create a custom RStudio image using the SageMaker AI console and the AWS CLI. If you use the AWS CLI, you must run the steps from your local machine. The following steps do not work from within Amazon SageMaker Studio Classic. When you create an image, SageMaker AI also creates an initial image version. The image version represents a container image in [Amazon Elastic Container Registry (ECR)](https://console.aws.amazon.com/ecr/). The container image must satisfy the requirements to be used in RStudio. For more information, see [Custom RStudio image specifications](rstudio-byoi-specs.md). For information about testing your image locally and resolving common issues, see the [SageMaker Studio Custom Image Samples repo](https://github.com/aws-samples/sagemaker-studio-custom-image-samples/blob/main/DEVELOPMENT.md). **Topics** + [ ## Add a SageMaker AI-compatible RStudio Docker container image to Amazon ECR ](#rstudio-byoi-sdk-add-container-image) + [ ## Create a SageMaker image from the console ](#rstudio-byoi-create-console) + [ ## Create an image from the AWS CLI ](#rstudio-byoi-create-cli) ## Add a SageMaker AI-compatible RStudio Docker container image to Amazon ECR Use the following steps to add a Docker container image to Amazon ECR: + Create an Amazon ECR repository. + Authenticate to Amazon ECR. + Build a SageMaker AI-compatible RStudio Docker image. + Push the image to the Amazon ECR repository. **Note** The Amazon ECR repository must be in the same AWS Region as your domain. **To build and add a Docker image to Amazon ECR** 1. Create an Amazon ECR repository using the AWS CLI. To create the repository using the Amazon ECR console, see [Creating a repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html). ``` aws ecr create-repository \ --repository-name rstudio-custom \ --image-scanning-configuration scanOnPush=true ``` Response: ``` { "repository": { "repositoryArn": "arn:aws:ecr:us-east-2:acct-id:repository/rstudio-custom", "registryId": "acct-id", "repositoryName": "rstudio-custom", "repositoryUri": "acct-id.dkr.ecr.us-east-2.amazonaws.com/rstudio-custom", ... } } ``` 1. Authenticate to Amazon ECR using the repository URI returned as a response from the `create-repository` command. Make sure that the Docker application is running. For more information, see [Registry Authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html#registry_auth). ``` aws ecr get-login-password | \ docker login --username AWS --password-stdin ``` Response: ``` Login Succeeded ``` 1. Build the Docker image. Run the following command from the directory that includes your Dockerfile. ``` docker build . ``` 1. Tag your built image with a unique tag. ``` docker tag ":" ``` 1. Push the container image to the Amazon ECR repository. For more information, see [ImagePush](https://docs.docker.com/engine/api/v1.40/#operation/ImagePush) and [Pushing an image](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html). ``` docker push : ``` Response: ``` The push refers to repository [.dkr.ecr.us-east-2.amazonaws.com/rstudio-custom] r: digest: size: 3066 ``` ## Create a SageMaker image from the console **To create an image** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **Images**. 1. On the **Custom images** page, choose **Create image**. 1. For **Image source**, enter the registry path to the container image in Amazon ECR. The path is in the following format: ` acct-id.dkr.ecr.region.amazonaws.com/repo-name[:tag] or [@digest] ` 1. Choose **Next**. 1. Under **Image properties**, enter the following: + Image name – The name must be unique to your account in the current AWS Region. + (Optional) Image display name – The name displayed in the domain user interface. When not provided, `Image name` is displayed. + (Optional) Description – A description of the image. + IAM role – The role must have the [AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess) policy attached. Use the dropdown menu to choose one of the following options: + Create a new role – Specify any additional Amazon Simple Storage Service (Amazon S3) buckets that you want your notebooks users to access. If you don't want to allow access to additional buckets, choose **None**. SageMaker AI attaches the `AmazonSageMakerFullAccess` policy to the role. The role allows your notebook users to access the Amazon S3 buckets listed next to the check marks. + Enter a custom IAM role ARN – Enter the Amazon Resource Name (ARN) of your IAM role. + Use existing role – Choose one of your existing roles from the list. + (Optional) Image tags – Choose **Add new tag**. You can add up to 50 tags. Tags are searchable using the SageMaker AI console or the SageMaker AI `Search` API. 1. Under **Image type**, select RStudio image. 1. Choose **Submit**. The new image is displayed in the **Custom images** list and briefly highlighted. After the image has been successfully created, you can choose the image name to view its properties or choose **Create version** to create another version. **To create another image version** 1. Choose **Create version** on the same row as the image. 1. For **Image source**, enter the registry path to the Amazon ECR image. The image shouldn't be the same image as used in a previous version of the SageMaker AI image. To use the custom image in RStudio, you must attach it to your domain. For more information, see [Attach a custom SageMaker image](rstudio-byoi-attach.md). ## Create an image from the AWS CLI This section shows how to create a custom Amazon SageMaker image using the AWS CLI. Use the following steps to create a SageMaker image: + Create an `Image`. + Create an `ImageVersion`. + Create a configuration file. + Create an `AppImageConfig`. **To create the SageMaker image entities** 1. Create a SageMaker image. The role ARN must have at least the `AmazonSageMakerFullAccessPolicy` policy attached. ``` aws sagemaker create-image \ --image-name rstudio-custom-image \ --role-arn arn:aws:iam:::role/service-role/ ``` Response: ``` { "ImageArn": "arn:aws:sagemaker:us-east-2:acct-id:image/rstudio-custom-image" } ``` 1. Create a SageMaker image version from the image. Pass the unique tag value that you chose when you pushed the image to Amazon ECR. ``` aws sagemaker create-image-version \ --image-name rstudio-custom-image \ --base-image : ``` Response: ``` { "ImageVersionArn": "arn:aws:sagemaker:us-east-2:acct-id:image-version/rstudio-image/1" } ``` 1. Check that the image version was successfully created. ``` aws sagemaker describe-image-version \ --image-name rstudio-custom-image \ --version 1 ``` Response: ``` { "ImageVersionArn": "arn:aws:sagemaker:us-east-2:acct-id:image-version/rstudio-custom-image/1", "ImageVersionStatus": "CREATED" } ``` **Note** If the response is `"ImageVersionStatus": "CREATED_FAILED"`, the response also includes the failure reason. A permissions issue is a common cause of failure. You also can check your Amazon CloudWatch Logs. The name of the log group is `/aws/sagemaker/studio`. The name of the log stream is `$domainID/$userProfileName/KernelGateway/$appName`. 1. Create a configuration file, named `app-image-config-input.json`. The app image config is used to configuration for running a SageMaker image as a Kernel Gateway application. ``` { "AppImageConfigName": "rstudio-custom-config" } ``` 1. Create the AppImageConfig using the file that you created in the previous step. ``` aws sagemaker create-app-image-config \ --cli-input-json file://app-image-config-input.json ``` Response: ``` { "AppImageConfigArn": "arn:aws:sagemaker:us-east-2:acct-id:app-image-config/r-image-config" } ``` # Attach a custom SageMaker image Attach an image **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. This guide shows how to attach a custom RStudio image to your Amazon SageMaker AI domain using the SageMaker AI console or the AWS Command Line Interface (AWS CLI). To use a custom SageMaker image, you must attach a custom RStudio image to your domain. When you attach an image version, it appears in the RStudio Launcher and is available in the **Select image** dropdown list. You use the dropdown to change the image used by RStudio. There is a limit to the number of image versions that you can attach. After you reach the limit, you must first detach a version so that you can attach a different version of the image. **Topics** + [ ## Attach an image version to your domain using the console ](#rstudio-byoi-attach-console) + [ ## Attach an existing image version to your domain using the AWS CLI ](#rstudio-byoi-attach-cli) ## Attach an image version to your domain using the console You can attach a custom SageMaker image version to your domain using the SageMaker AI console's control panel. You can also create a custom SageMaker image, and an image version, and then attach that version to your domain. **To attach an existing image** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. Select the desired domain. 1. Choose **Environment**. 1. Under **Custom SageMaker Studio Classic images attached to domain**, choose **Attach image**. 1. For **Image source**, choose **Existing image** or **New image**. If you select **Existing image**, choose an image from the Amazon SageMaker image store. If you select **New image**, provide the Amazon ECR registry path for your Docker image. The path must be in the same AWS Region as the domain. The Amazon ECR repo must be in the same account as your domain, or cross-account permissions for SageMaker AI must be enabled. 1. Choose an existing image from the list. 1. Choose a version of the image from the list. 1. Choose **Next**. 1. Enter values for **Image name**, **Image display name**, and **Description**. 1. Choose the IAM role. For more information, see [Create a custom RStudio image](rstudio-byoi-create.md). 1. (Optional) Add tags for the image. 1. (Optional) Choose **Add new tag**, then add a configuration tag. 1. For **Image type**, select **RStudio Image**. 1. Choose **Submit**. Wait for the image version to be attached to the domain. After the version is attached, it appears in the **Custom images** list and is briefly highlighted. ## Attach an existing image version to your domain using the AWS CLI Two methods are presented to attach the image version to your domain using the AWS CLI. In the first method, you create a new domain with the version attached. This method is simpler but you must specify the Amazon Virtual Private Cloud (Amazon VPC) information and execution role that's required to create the domain. If you have already onboarded to the domain, you can use the second method to attach the image version to your current domain. In this case, you don't need to specify the Amazon VPC information and execution role. After you attach the version, delete all of the applications in your domain and relaunch RStudio. ### Attach the SageMaker image to a new domain To use this method, you must specify an execution role that has the [AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess) policy attached. Use the following steps to create the domain and attach the custom SageMaker AI image: + Get your default VPC ID and subnet IDs. + Create the configuration file for the domain, which specifies the image. + Create the domain with the configuration file. **To add the custom SageMaker image to your domain** 1. Get your default VPC ID. ``` aws ec2 describe-vpcs \ --filters Name=isDefault,Values=true \ --query "Vpcs[0].VpcId" --output text ``` Response: ``` vpc-xxxxxxxx ``` 1. Get your default subnet IDs using the VPC ID from the previous step. ``` aws ec2 describe-subnets \ --filters Name=vpc-id,Values= \ --query "Subnets[*].SubnetId" --output json ``` Response: ``` [ "subnet-b55171dd", "subnet-8a5f99c6", "subnet-e88d1392" ] ``` 1. Create a configuration file named `create-domain-input.json`. Insert the VPC ID, subnet IDs, `ImageName`, and `AppImageConfigName` from the previous steps. Because `ImageVersionNumber` isn't specified, the latest version of the image is used, which is the only version in this case. Your execution role must satisfy the requirements in [Complete prerequisites](rstudio-byoi-prerequisites.md). ``` { "DomainName": "domain-with-custom-r-image", "VpcId": "", "SubnetIds": [ "" ], "DomainSettings": { "RStudioServerProDomainSettings": { "DomainExecutionRoleArn": "" } }, "DefaultUserSettings": { "ExecutionRole": "", "RSessionAppSettings": { "CustomImages": [ { "AppImageConfigName": "rstudio-custom-config", "ImageName": "rstudio-custom-image" } ] } }, "AuthMode": "IAM" } ``` 1. Create the domain with the attached custom SageMaker image. ``` aws sagemaker create-domain \ --cli-input-json file://create-domain-input.json ``` Response: ``` { "DomainArn": "arn:aws:sagemaker:region:acct-id:domain/domain-id", "Url": "https://domain-id.studio.region.sagemaker.aws/..." } ``` ### Attach the SageMaker image to an existing domain This method assumes that you've already onboarded to domain. For more information, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md). **Note** You must delete all of the applications in your domain to update the domain with the new image version. For information about deleting these applications, see [Delete an Amazon SageMaker AI domain](gs-studio-delete-domain.md). Use the following steps to add the SageMaker image to your current domain. + Get your `DomainID` from the SageMaker AI console. + Use the `DomainID` to get the `DefaultUserSettings` for the domain. + Add the `ImageName` and `AppImageConfig` as a `CustomImage` to the `DefaultUserSettings`. + Update your domain to include the custom image. **To add the custom SageMaker image to your domain** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. Select the desired domain. 1. Choose **domain settings**. 1. Under **General Settings**, find the **domain ID**. The ID is in the following format: `d-xxxxxxxxxxxx`. 1. Use the domain ID to get the description of the domain. ``` aws sagemaker describe-domain \ --domain-id ``` Response: ``` { "DomainId": "d-xxxxxxxxxxxx", "DefaultUserSettings": { "KernelGatewayAppSettings": { "CustomImages": [ ], ... } } } ``` 1. Save the `DefaultUserSettings` section of the response to a file named `update-domain-input.json`. 1. Insert the `ImageName` and `AppImageConfigName` from the previous steps as a custom image. Because `ImageVersionNumber` isn't specified, the latest version of the image is used, which is the only version in this case. ``` { "DefaultUserSettings": { "RSessionAppSettings": { "CustomImages": [ { "ImageName": "rstudio-custom-image", "AppImageConfigName": "rstudio-custom-config" } ] } } } ``` 1. Use the domain ID and default user settings file to update your domain. ``` aws sagemaker update-domain \ --domain-id \ --cli-input-json file://update-domain-input.json ``` Response: ``` { "DomainArn": "arn:aws:sagemaker:region:acct-id:domain/domain-id" } ``` 1. Delete the `RStudioServerPro` application. You must restart the `RStudioServerPro` domain-shared application for the RStudio Launcher UI to pick up the latest changes. ``` aws sagemaker delete-app \ --domain-id --user-profile-name domain-shared \ --app-type RStudioServerPro --app-name default ``` 1. Create a new `RStudioServerPro` application. You must create this application using the AWS CLI. ``` aws sagemaker create-app \ --domain-id --user-profile-name domain-shared \ --app-type RStudioServerPro --app-name default ``` # Launch a custom SageMaker image in RStudio Launch a custom image You can use your custom image when launching an RStudio applicaton from the console. After you create your custom SageMaker image and attach it to your domain, the image appears in the image selector dialog box of the RStudio Launcher. To launch a new RStudio app, follow the steps in [Launch RSessions from the RStudio Launcher](rstudio-launcher.md) and select your custom image as shown in the following image. ![\[Screenshot of the RStudio launcher with image dropdown.\]](http://docs.aws.amazon.com/sagemaker/latest/dg/images/rstudio-launcher-custom.png) # Clean up image resources This guide shows how to clean up RStudio image resources that you created in the previous sections. To delete an image, complete the following steps using either the SageMaker AI console or the AWS CLI, as shown in this guide. + Detach the image and image versions from your Amazon SageMaker AI domain. + Delete the image, image version, and app image config. After you've completed these steps, you can delete the container image and repository from Amazon ECR. For more information about how to delete the container image and repository, see [Deleting a repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-delete.html). ## Clean up resources from the SageMaker AI console When you detach an image from a domain, all versions of the image are detached. When an image is detached, all users of the domain lose access to the image versions. **To detach an image** 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. Select the desired domain. 1. Choose **Environment**. 1. Under **Custom images attached to domain**, choose the image and then choose **Detach**. 1. (Optional) To delete the image and all versions from SageMaker AI, select **Also delete the selected images ...**. This does not delete the associated images from Amazon ECR. 1. Choose **Detach**. ## Clean up resources from the AWS CLI **To clean up resources** 1. Detach the image and image versions from your domain by passing an empty custom image list to the domain. Open the `update-domain-input.json` file that you created in [Attach the SageMaker image to your current domain](studio-byoi-attach.md#studio-byoi-sdk-attach-current-domain). 1. Delete the `RSessionAppSettings` custom images and then save the file. Do not modify the `KernelGatewayAppSettings` custom images. ``` { "DomainId": "d-xxxxxxxxxxxx", "DefaultUserSettings": { "KernelGatewayAppSettings": { "CustomImages": [ ], ... }, "RSessionAppSettings": { "CustomImages": [ ], "DefaultResourceSpec": { } ... } } } ``` 1. Use the domain ID and default user settings file to update your domain. ``` aws sagemaker update-domain \ --domain-id \ --cli-input-json file://update-domain-input.json ``` Response: ``` { "DomainArn": "arn:aws:sagemaker:us-east-2:acct-id:domain/d-xxxxxxxxxxxx" } ``` 1. Delete the app image config. ``` aws sagemaker delete-app-image-config \ --app-image-config-name rstudio-image-config ``` 1. Delete the SageMaker image, which also deletes all image versions. The container images in Amazon ECR that are represented by the image versions are not deleted. ``` aws sagemaker delete-image \ --image-name rstudio-image ``` # Create a user to use RStudio **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. After your RStudio-enabled Amazon SageMaker AI domain is running, you can add user profiles (UserProfiles) to the domain. The following topics show how to create user profiles that are authorized to use RStudio, as well as update an existing user profile. For information on how to delete an RStudio App, UserProfile, or domain, follow the steps in [Delete an Amazon SageMaker AI domain](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-studio-delete-domain.html). **Note** The limit for the total number of UserProfiles in a Amazon SageMaker AI domain is 60. There are two types of users: + Unauthorized: This user cannot access the RStudio app. + Authorized: This user can access the RStudio app and use one of the RStudio license seats. By default, a new user is `Authorized` if the domain is enabled for RStudio. Changing a user's authorization status is only valid from `Unauthorized` to `Authorized`. If a user is authorized, they can be given one of the following levels of access to RStudio. + RStudio User: This is a standard RStudio user and can access RStudio. + RStudio Admin: The admin of your Amazon SageMaker AI domain has the ability to create users, add existing users, and update the permissions of existing users. Admins can also access the RStudio Administrative dashboard. However, this admin is not able to update parameters that are managed by Amazon SageMaker AI. ## Methods to create a user The following topics show how to create a user in your RStudio-enabled Amazon SageMaker AI domain. **Create user console** To create a user in your RStudio-enabled Amazon SageMaker AI domain from the console, complete the steps in [Add user profiles](domain-user-profile-add.md). **Create user CLI** The following command shows how to add users to a Amazon SageMaker AI domain with IAM authentication. A User can belong to either the `R_STUDIO_USER` or `R_STUDIO_ADMIN` User group. ``` aws sagemaker create-user-profile --region \ --domain-id \ --user-profile-name \ --user-settings RStudioServerProAppSettings={UserGroup=} ``` The following command shows how to add users to a Amazon SageMaker AI domain with authentication using IAM Identity Center. A user can belong to either the `R_STUDIO_USER` or `R_STUDIO_ADMIN` User group. ``` aws sagemaker create-user-profile --region \ --domain-id \ --user-profile-name \ --user-settings RStudioServerProAppSettings={UserGroup=} \ --single-sign-on-user-identifier UserName \ --single-sign-on-user-value ``` # Log in to RStudio as another user The following topic demonstrates how to log in to RStudio on Amazon SageMaker AI as another user. 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. On the left navigation pane, choose **Admin configurations**. 1. Under **Admin configurations**, choose **domains**. 1. Select the domain containing the user profile. 1. Select a user name from the list of users. This opens a new page with details about the user profile and the apps that are running. 1. Select **Launch**. 1. From the dropdown, select **RStudio** to launch an RStudio instance. # Terminate sessions for another user The following topic demonstrates how to terminate sessions for another user in RStudio on Amazon SageMaker AI. 1. From the list of running apps, identify the app you want to delete. 1. Click the respective **Delete app** button for the app you are deleting. # Use the RStudio administrative dashboard This topic shows how to access and use the RStudio administrative dashboard. With the RStudio administrative dashboard, admins can manage users and RSessions, as well as view information about RStudio Server instance utilization and Amazon CloudWatch Logs. ## Launch the RStudio administrative dashboard The `R_STUDIO_ADMIN` authorization allows the user to access the RStudio administrative dashboard. An `R_STUDIO_ADMIN` user can access the RStudio administrative dashboard by replacing `workspaces` with `admin` in their RStudio URL manually. The following shows how to modify the URL to access the RStudio administrative dashboard. For example, the following RStudio URL: ``` https://.studio.us-east-2.sagemaker.aws/rstudio/default/s//workspaces ``` Can be converted to: ``` https://.studio.us-east-2.sagemaker.aws/rstudio/default/s//admin ``` ## Dashboard tab This tab gives an overview of your RStudio Server instance utilization, as well as information on the number of active RSessions. ## Sessions tab This tab gives information on the active RSessions, such as the user that launched the RSessions, the time that the RSessions have been running, and their resource utilization. ## Users tab This tab gives information on the RStudio authorized users in the domain, such as the time that the last RSession was launched and their resource utilization. ## Stats tab This tab gives information on the utilization of your RStudio Server instance. ## Logs tab This tab displays Amazon CloudWatch Logs for the RStudio Server instance. For more information about logging events with Amazon CloudWatch Logs, see [What is Amazon CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html). # Shut down RStudio **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. To shut down and restart your Posit Workbench and the associated RStudioServerPro app, you must first shut down all of your existing RSessions. You can shut down the RSessionGateway apps from within RStudio. You can then shut down the RStudioServerPro app using the AWS CLI. After the RStudioServerPro app is shut down, you must reopen RStudio through the SageMaker AI console. Any unsaved notebook information is lost in the process. The user data in the Amazon EFS volume isn't impacted. **Note** If you are using a custom image with RStudio, ensure that your docker image is using an RStudio version that is compatible with the version of Posit Workbench being used by SageMaker AI after you restart your RStudioServerPro app. The following topics show how to shut down the RSessionGateway and RStudioServerPro apps and restart them. ## Suspend your RSessions Complete the following procedure to suspend all of your RSessions. 1. From the RStudio Launcher, identify the RSession that you want to suspend. 1. Select **Suspend** for the session. 1. Repeat this for all RSessions. ## Delete your RSessions Complete the following procedure to shut down all of your RSessions. 1. From the RStudio Launcher, identify the RSession that you want to delete. 1. Select **Quit** for the session. This opens a new **Quit Session** window. 1. From the **Quit Session** window, select **Force Quit**, to end all child processes in the session. 1. Select **Quit Session** to confirm deletion of the session. 1. Repeat this for all RSessions. ## Delete your RStudioServerPro app Run the following commands from the AWS CLI to delete and restart your RStudioServerPro app. 1. Delete the RStudioServerPro application by using your current domain id. ``` aws sagemaker delete-app \ --domain-id \ --user-profile-name domain-shared \ --app-type RStudioServerPro \ --app-name default ``` 1. Re-create the RStudioServerPro application. ``` aws sagemaker create-app \ --domain-id \ --user-profile-name domain-shared \ --app-type RStudioServerPro \ --app-name default ``` # Billing and cost To track the costs associated with your RStudio environment, you can use the AWS Billing and Cost Management service. AWS Billing and Cost Management provides useful tools to help you gather information related to your cost and usage, analyze your cost drivers and usage trends, and take action to budget your spending. For more information, see [What is AWS Billing and Cost Management?](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-what-is.html). The following describes components required to run RStudio on Amazon SageMaker AI and how each component factors into billing for your RStudio instance. + RStudio License –You must purchase an RStudio license. There is no additional charge for using your RStudio license with Amazon SageMaker AI. For more information about your RStudio license, see [Get an RStudio license](rstudio-license.md). + RSession - These are RStudio working sessions launched by end users. You are charged while the RSession is running. + RStudio Server - A multi-tenant server manages all the RSessions. You can choose the instance type to run RStudio Server on, and pay the related costs. The default instance, "system", is free, but you can choose to pay for higher tiers. For more information about the available instance types for your RStudio Server, see [RStudioServerPro instance type](rstudio-select-instance.md). **Tracking billing at user level** To track billing at the user level using Cost Allocation Tags, see [Using Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html). # Diagnose issues and get support The following sections describe how to diagnose issues with RStudio on Amazon SageMaker AI. To get support for RStudio on Amazon SageMaker AI, contact Amazon SageMaker AI support. For help with purchasing an RStudio license or modifying the number of license seats, contact [sales@rstudio.com](mailto:sales@rstudio.com). ## Upgrade your version If you receive a warning that there is a version mismatch between your RSession and RStudioServerPro apps, then you must upgrade the version of your RStudioServerPro app. For more information, see [RStudio Versioning](rstudio-version.md). ## View Metrics and Logs You can monitor your workflow performance while using RStudio on Amazon SageMaker AI. View data logs and information about metrics with the RStudio administrative dashboard or Amazon CloudWatch. ### View your RStudio logs from the RStudio administrative dashboard You can view metrics and logs directly from the RStudio administrative dashboard. 1. Log in to your **Amazon SageMaker AI domain**. 1. Navigate to the RStudio administrative dashboard following the steps in [Use the RStudio administrative dashboard](rstudio-admin.md). 1. Select the **Logs** tab. ### View your RStudio logs from Amazon CloudWatch Logs Amazon CloudWatch monitors your AWS resources and the applications that you run on AWS in real time. You can use Amazon CloudWatch to collect and track metrics, which are variables that you can measure for your resources and applications. To ensure that your RStudio apps have permissions for Amazon CloudWatch, you must include the permissions described in [Amazon SageMaker AI domain overview](gs-studio-onboard.md). You don’t need to do any setup to gather Amazon CloudWatch Logs. The following steps show how to view Amazon CloudWatch Logs for your RSession. These logs can be found in the `/aws/sagemaker/studio` log stream from the AWS CloudWatch console. 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Select `Logs` from the left side. From the dropdown menu, select `Log groups`. 1. On the `Log groups` screen, search for `aws/sagemaker/studio`. Select the Log group. 1. On the `aws/sagemaker/studio` `Log group` screen, navigate to the `Log streams` tab. 1. To find the logs for your domain, search `Log streams` using the following format: ``` /domain-shared/rstudioserverpro/default ``` # RStudio on Amazon SageMaker AI user guide With RStudio support in Amazon SageMaker AI, you can put your production workflows in place and take advantage of SageMaker AI features. The following topics show how to launch an RStudio session and complete key workflows. For information about managing RStudio on SageMaker AI, see [RStudio on Amazon SageMaker AI management](rstudio-manage.md). For information about the onboarding steps to create an Amazon SageMaker AI domain with RStudio enabled, see [Amazon SageMaker AI domain overview](gs-studio-onboard.md).  For information about the AWS Regions that RStudio on SageMaker AI is supported in, see [Supported Regions and Quotas](regions-quotas.md).  **Topics** + [ ## Collaborate in RStudio ](#rstudio-collaborate) + [ ## Base R image ](#rstudio-base-image) + [ ## RSession application colocation ](#rstudio-colocation) + [ # Launch RSessions from the RStudio Launcher ](rstudio-launcher.md) + [ # Suspend your RSessions ](rstudio-launcher-suspend.md) + [ # Delete your RSessions ](rstudio-launcher-delete.md) + [ # RStudio Connect ](rstudio-connect.md) + [ # Amazon SageMaker AI feature integration with RStudio on Amazon SageMaker AI ](rstudio-sm-features.md) ## Collaborate in RStudio To share your RStudio project, you can connect RStudio to your Git repo. For information on setting this up, see [ Version Control with Git and SVN](https://support.rstudio.com/hc/en-us/articles/200532077-Version-Control-with-Git-and-SVN). Note: Project sharing and realtime collaboration are not currently supported when using RStudio on Amazon SageMaker AI.  ## Base R image When launching your RStudio instance, the Base R image serves as the basis of your instance. This image extends the [r-session-complete](https://hub.docker.com/r/rstudio/r-session-complete) Docker image.  This Base R image includes the following: + R v4.0 or higher + `awscli`, `sagemaker`, and `boto3` Python packages + [Reticulate](https://rstudio.github.io/reticulate/) package for R SDK integration ## RSession application colocation Users can create multiple RSession applications on the same instance. Each instance type supports up to four colocated RSession applications. This applies to each user independently. For example, if two users create applications, then SageMaker AI allocates different underlying instances to each user. Each of these instances would support 4 RSession applications. Customers only pay for the instance type used regardless of how many Rsession applications are running on the instance. If a user creates an RSession with a different associated instance type, then a new underlying instance is created. # Launch RSessions from the RStudio Launcher **Important** Custom IAM policies that allow Amazon SageMaker Studio or Amazon SageMaker Studio Classic to create Amazon SageMaker resources must also grant permissions to add tags to those resources. The permission to add tags to resources is required because Studio and Studio Classic automatically tag any resources they create. If an IAM policy allows Studio and Studio Classic to create resources but does not allow tagging, "AccessDenied" errors can occur when trying to create resources. For more information, see [Provide permissions for tagging SageMaker AI resources](security_iam_id-based-policy-examples.md#grant-tagging-permissions). [AWS managed policies for Amazon SageMaker AI](security-iam-awsmanpol.md) that give permissions to create SageMaker resources already include permissions to add tags while creating those resources. The following sections show how to use the RStudio Launcher to launch RSessions. They also include information about how to open the RStudio Launcher when using RStudio on Amazon SageMaker AI. ## Open RStudio Launcher Open the RStudio launcher using the following set of procedures that matches your environment. ### Open RStudio Launcher from the Amazon SageMaker AI Console 1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. From the left navigation, select **RStudio**. 1. Under **Get Started**, select the domain and user profile to launch. 1. Choose **Launch RStudio**. ### Open RStudio Launcher from Amazon SageMaker Studio 1. Navigate to Studio following the steps in [Launch Amazon SageMaker Studio](studio-updated-launch.md). 1. Under **Applications**, select **RStudio**. 1. From the RStudio landing page, choose **Launch application**. ### Open RStudio Launcher from the AWS CLI The procedure to open the RStudio Launcher using the AWS CLI differs depending on the method used to manage your users. **IAM Identity Center** 1. Use the AWS access portal to open your Amazon SageMaker AI domain. 1. Modify the URL path to “/rstudio/default” as follows. ``` #Studio URL https://.studio..sagemaker.aws/jupyter/default/lab #modified URL https://.studio..sagemaker.aws/rstudio/default ``` **IAM** To open the RStudio Launcher from the AWS CLI in IAM mode, complete the following procedure. 1. Create a presigned URL using the following command. ``` aws sagemaker create-presigned-domain-url --region \ --domain-id \ --user-profile-name ``` 1. Append *&redirect=RStudioServerPro* to the generated URL. 1. Navigate to the updated URL. ## Launch RSessions After you’ve launched the RStudio Launcher, you can create a new RSession. 1. Select **New Session**. 1. Enter a **Session Name**. 1. Select an instance type that your RSession runs on. This defaults to `ml.t3.medium`. 1. Select an Image that your RSession uses as the kernel. 1. Select Start Session. 1. After your session has been created, you can start it by selecting the name.  **Note** If you receive a warning that there is a version mismatch between your RSession and RStudioServerPro apps, then you must upgrade the version of your RStudioServerPro app. For more information, see [RStudio Versioning](rstudio-version.md). # Suspend your RSessions The following procedure demonstrates how to suspend an RSession from the RStudio Launcher when using RStudio on Amazon SageMaker AI. For information about accessing the RStudio Launcher, see [Launch RSessions from the RStudio Launcher](rstudio-launcher.md). 1. From the RStudio Launcher, identify the RSession that you want to suspend. 1. Select **Suspend** for the session. # Delete your RSessions The following procedure demonstrates how to delete an RSession from the RStudio Launcher when using RStudio on Amazon SageMaker AI. For information about accessing the RStudio Launcher, see [Launch RSessions from the RStudio Launcher](rstudio-launcher.md). 1. From the RStudio Launcher, identify the RSession that you want to delete. 1. Select **Quit** for the session. This opens a new **Quit Session** window. 1. From the **Quit Session** window, select **Force Quit**, to end all child processes in the session. 1. Select **Quit Session** to confirm deletion of the session. # RStudio Connect RStudio Connect enables data scientists to publish insights, dashboard and web applications from RStudio on Amazon SageMaker AI. For more information, see [Host RStudio Connect and Package Manager for ML development in RStudio on Amazon SageMaker AI](https://aws.amazon.com/blogs/machine-learning/host-rstudio-connect-and-package-manager-for-ml-development-in-rstudio-on-amazon-sagemaker/). For more information on RStudio Connect, see the [RStudio Connect User Guide](https://docs.rstudio.com/connect/user/). # Amazon SageMaker AI feature integration with RStudio on Amazon SageMaker AI One of the benefits of using RStudio on Amazon SageMaker AI is the integration of Amazon SageMaker AI features. This includes integration with Amazon SageMaker Studio Classic and Reticulate. The following gives information about these integrations and examples for using them. **Use Amazon SageMaker Studio Classic and RStudio on Amazon SageMaker AI** Your Amazon SageMaker Studio Classic and RStudio instances share the same Amazon EFS file system. This means that files that you import and create using Studio Classic can be accessed using RStudio and vice versa. This allows you to work on the same files using both Studio Classic and RStudio without having to move your files between the two. For more information on this workflow, see the [Announcing Fully Managed RStudio on Amazon SageMaker AI for Data Scientists](https://aws.amazon.com/blogs/aws/announcing-fully-managed-rstudio-on-amazon-sagemaker-for-data-scientists) blog. **Use Amazon SageMaker SDK with reticulate** The [reticulate](https://rstudio.github.io/reticulate) package is used as an R interface to [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable/) to make API calls to Amazon SageMaker. The reticulate package translates between R and Python objects, and Amazon SageMaker AI provides a serverless data science environment to train and deploy Machine Learning (ML) models at scale. For general information about the reticulate package, see [ R Interface to Python](https://rstudio.github.io/reticulate/). For a blog that outlines how to use the reticulate package with Amazon SageMaker AI, see [Using R with Amazon SageMaker AI](https://aws.amazon.com/blogs/machine-learning/using-r-with-amazon-sagemaker/). The following examples show how to use reticulate for specific use cases. + For a notebook that describes how to use reticulate to do batch transform to make predictions, see [Batch Transform Using R with Amazon SageMaker AI](https://sagemaker-examples.readthedocs.io/en/latest/r_examples/r_batch_transform/r_xgboost_batch_transform.html). + For a notebook that describes how to use reticulate to conduct hyperparameter tuning and generate predictions, see [Hyperparameter Optimization Using R with Amazon SageMaker AI](https://sagemaker-examples.readthedocs.io/en/latest/r_examples/r_xgboost_hpo_batch_transform/r_xgboost_hpo_batch_transform.html).