Custom blueprints

Custom blueprints in Amazon SageMaker Unified Studio enable organizations to standardize and accelerate how data projects get set up. They are administrator-defined templates, powered by AWS CloudFormation, that give teams a ready-made starting point for analytics and machine learning environments.

In addition to the blueprints that Amazon SageMaker Unified Studio provides, you can also design your own. For more information, see Supported blueprints. With custom blueprints, organizations can include their specific dependencies, security controls, and best practices to allow for new projects to align with internal standards. Since they're defined through infrastructure-as-code, custom blueprints are easy to version control, share across teams, and evolve over time. This not only speeds up onboarding but also keeps projects consistent and governed, no matter how big or distributed your data science organization becomes.

Register a custom blueprint in the console

Have your AWS CloudFormation template ready before you start. The Amazon SageMaker Unified Studio console accepts either an Amazon S3 URL or a file that you upload.

Now that your custom blueprint is created, you can use it when creating custom project profiles. For more information, see Custom project profile.

Register a custom blueprint with the API

The CreateEnvironmentBlueprint API requires an Amazon S3 URL for the AWS CloudFormation template. The blueprint's provisioning role must have access to that Amazon S3 object. The SageMakerStudioProjectProvisioningRolePolicy managed policy grants s3:GetObject on buckets whose names begin with amazon-sagemaker-cf-templates. The console creates such a bucket when you upload a template there.

aws datazone create-environment-blueprint \
  --domain-identifier domain-id \
  --name blueprint-name \
  --provisioning-properties '{
    "cloudFormation": {
      "templateUrl": "https://amazon-sagemaker-cf-templates-region-suffix.s3.region.amazonaws.com/my-template.yaml"
    }
  }'

After you create the blueprint, Amazon SageMaker Unified Studio disables it by default. To enable a blueprint in an AWS Region, you must supply a provisioning role with permissions for all resources in the template.

aws datazone put-environment-blueprint-configuration \
  --domain-identifier domain-id \
  --environment-blueprint-identifier blueprint-id \
  --enabled-regions region \
  --provisioning-role-arn provisioning-role-arn

Reserved parameters

Reserved parameters are AWS CloudFormation parameters whose values Amazon SageMaker Unified Studio supplies when it deploys your template. The names are case-sensitive. When Amazon SageMaker Unified Studio cannot find a value for an optional parameter, an empty string is injected, which overrides any Default you declared. The one exception is sagemakerUnifiedStudioNetworkGlueConnectionNames, which Amazon SageMaker Unified Studio omits instead, leaving your Default in place.

The prefixes amazon, aws, datazone, and sagemaker are reserved. When you register a blueprint, Amazon SageMaker Unified Studio rejects any name in userParameters that begins with one of them, whether or not it appears in the table.

Parameters: [parameterName] must have values

Trust policy for the provisioning role

Amazon SageMaker Unified Studio assumes the blueprint's provisioning role with sts:AssumeRole to deploy your AWS CloudFormation template. It also attaches your user context to that session as tags with sts:TagSession. Amazon SageMaker Unified Studio resources such as connections and data sources require this user context to provision. Therefore, the trust policy of the provisioning role must allow both actions for the datazone.amazonaws.com service principal, as shown in the following example. The aws:SourceAccount condition restricts the role to your own AWS account, which guards against the cross-service confused deputy problem.

{
    "Version": "2012-10-17", 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "datazone.amazonaws.com"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "111122223333"
                }
            }
        }
    ]
}

Sample custom blueprint template

The following template creates an AWS Glue database in your SageMaker Lakehouse catalog, grants the project's users access to it through AWS Lake Formation, and attaches a managed policy to the project's role. It is the same template that the View templates button on the Blueprints page shows.

{
  "Parameters": {
    "datazoneEnvironmentEnvironmentId": {
      "Type": "String",
      "Description": "EnvironmentId for which the resource will be created for."
    },
    "datazoneEnvironmentProjectId": {
      "Type": "String",
      "Description": "DZ projectId for which project the resource will be created for."
    },
    "userRoleArn": {
      "Type": "String",
      "Description": "Project Role ARN"
    },
    "glueDbName": {
      "Type": "String",
      "Default": "gluedb",
      "Description": "Glue DB name"
    }
  },
  "Resources": {
    "GlueDatabase": {
      "Type": "AWS::Glue::Database",
      "Properties": {
        "CatalogId": {
          "Ref": "AWS::AccountId"
        },
        "DatabaseInput": {
          "CreateTableDefaultPermissions": [],
          "Description": {
            "Fn::Join": [
              "",
              [
                "Created by DataZone for project ",
                {
                  "Ref": "datazoneEnvironmentProjectId"
                }
              ]
            ]
          },
          "LocationUri": {
            "Fn::Join": [
              "",
              [
                {
                  "Fn::ImportValue": {
                    "Fn::Join": [
                      "",
                      [
                        "s3BucketPath-",
                        {
                          "Ref": "datazoneEnvironmentProjectId"
                        },
                        "-dev"
                      ]
                    ]
                  }
                },
                "/data/catalogs/"
              ]
            ]
          },
          "Name": {
            "Fn::Sub": "${glueDbName}-${datazoneEnvironmentEnvironmentId}"
          }
        }
      }
    },
    "GlueAccessManagedPolicy": {
      "Type": "AWS::IAM::ManagedPolicy",
      "Properties": {
        "ManagedPolicyName": {
          "Fn::Sub": "GlueAccess-${glueDbName}-${datazoneEnvironmentEnvironmentId}-Policy"
        },
        "PolicyDocument": {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": [
                "glue:GetDatabase",
                "glue:GetTables",
                "glue:GetTable",
                "glue:CreateTable",
                "glue:UpdateTable",
                "glue:DeleteTable",
                "glue:BatchDeleteTable",
                "glue:GetPartitions",
                "glue:GetPartition",
                "glue:BatchCreatePartition",
                "glue:BatchDeletePartition"
              ],
              "Resource": [
                {
                  "Fn::Sub": "arn:aws:glue:${AWS::Region}:${AWS::AccountId}:catalog"
                },
                {
                  "Fn::Sub": "arn:aws:glue:${AWS::Region}:${AWS::AccountId}:database/${glueDbName}-${datazoneEnvironmentEnvironmentId}"
                },
                {
                  "Fn::Sub": "arn:aws:glue:${AWS::Region}:${AWS::AccountId}:table/${glueDbName}-${datazoneEnvironmentEnvironmentId}/*"
                }
              ]
            }
          ]
        }
      }
    },
    "LakeFormationDbPermissions": {
      "Type": "AWS::LakeFormation::Permissions",
      "Properties": {
        "DataLakePrincipal": {
          "DataLakePrincipalIdentifier": {
            "Ref": "userRoleArn"
          }
        },
        "Resource": {
          "DatabaseResource": {
            "CatalogId": {
              "Ref": "AWS::AccountId"
            },
            "Name": {
              "Fn::Sub": "${glueDbName}-${datazoneEnvironmentEnvironmentId}"
            }
          }
        },
        "Permissions": [
          "DESCRIBE",
          "CREATE_TABLE"
        ]
      },
      "DependsOn": [
        "GlueDatabase"
      ]
    },
    "LakeFormationTablePermissions": {
      "Type": "AWS::LakeFormation::Permissions",
      "Properties": {
        "DataLakePrincipal": {
          "DataLakePrincipalIdentifier": {
            "Ref": "userRoleArn"
          }
        },
        "Resource": {
          "TableResource": {
            "CatalogId": {
              "Ref": "AWS::AccountId"
            },
            "DatabaseName": {
              "Fn::Sub": "${glueDbName}-${datazoneEnvironmentEnvironmentId}"
            },
            "TableWildcard": {}
          }
        },
        "Permissions": [
          "ALL"
        ]
      },
      "DependsOn": [
        "GlueDatabase"
      ]
    }
  },
  "Outputs": {
    "GlueDatabaseName": {
      "Value": {
        "Fn::Sub": "${glueDbName}-${datazoneEnvironmentEnvironmentId}"
      },
      "Export": {
        "Name": {
          "Fn::Sub": "${glueDbName}-${datazoneEnvironmentEnvironmentId}"
        }
      }
    },
    "GlueAccessManagedPolicy": {
      "Description": "ARN of the created managed policy",
      "Value": {
        "Ref": "GlueAccessManagedPolicy"
      },
      "Export": {
        "Name": {
          "Fn::Sub": "datazone-managed-policy-glue-${glueDbName}-${datazoneEnvironmentEnvironmentId}"
        }
      }
    }
  }
}