Setup
Follow these steps before using Amazon Braket in an AWS account that has not previously been enabled for Amazon Braket.
Creating the Braket service-linked role
AWS CLI
aws iam create-service-linked-role \
--aws-service-name braket.amazonaws.comIf the role already exists, the command returns EntityAlreadyExists; no
additional action is required.
AWS MCP
Reference the aws-iam skill and use the service principal braket.amazonaws.com to create the service-linked role.
Console
For manual console onboarding, follow Enable Amazon Braket.
Accepting third-party device terms and conditions
The user must manually accept these terms in the Braket console, once per AWS account, before using third-party QPUs. See Enable Amazon Braket for the steps.
Creating execution roles
Before creating each role, run aws iam get-role --role-name <name> to check if a role already exists and reuse it if it does.
If programmatic IAM role creation is unavailable, follow the console workflows in Hybrid Jobs prerequisites and Create an Amazon Braket notebook instance.
Replace every <account-id> in this section with the customer's AWS account ID.
Pass each policy document as an inline JSON string, quoted for the user's shell. Do not use file:// with AWS MCP call_aws.
Hybrid Jobs execution role
Create AmazonBraketJobsExecutionRole with the trust policy and command below:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "braket.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "<account-id>"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:braket:*:<account-id>:*"
}
}
}
]
}aws iam create-role \
--role-name AmazonBraketJobsExecutionRole \
--path /service-role/ \
--assume-role-policy-document '<trust policy JSON above>'Attach the AmazonBraketJobsExecutionPolicy AWS managed policy:
aws iam attach-role-policy \
--role-name AmazonBraketJobsExecutionRole \
--policy-arn arn:aws:iam::aws:policy/AmazonBraketJobsExecutionPolicySeparately, grant the principal that submits Hybrid Jobs iam:PassRole on the exact execution-role ARN, restricted to Braket.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::<account-id>:role/service-role/AmazonBraketJobsExecutionRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": "braket.amazonaws.com"
}
}
}
]
}Notebook execution role
Create AmazonBraketServiceSageMakerNotebookRole at the /service-role/ path.
Configure the role with this trust policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "sagemaker.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "<account-id>"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:sagemaker:*:<account-id>:notebook-instance/*"
}
}
}
]
}Create the role with the trust policy above:
aws iam create-role \
--role-name AmazonBraketServiceSageMakerNotebookRole \
--path /service-role/ \
--assume-role-policy-document '<trust policy JSON above>'Create and attach a customer-managed policy named
AmazonBraketServiceSageMakerNotebookAccess with the following policy document, and attach the AmazonBraketFullAccess managed policy, as the Braket console does:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::amazon-braket-*",
"arn:aws:s3:::braketnotebookcdk-*"
]
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:DescribeLogStreams",
"logs:PutLogEvents",
"logs:CreateLogGroup"
],
"Resource": [
"arn:aws:logs:*:<account-id>:log-group:/aws/sagemaker/*"
]
},
{
"Effect": "Allow",
"Action": "braket:*",
"Resource": "*"
}
]
}aws iam create-policy \
--policy-name AmazonBraketServiceSageMakerNotebookAccess \
--path /service-role/ \
--policy-document '<policy JSON above>'
aws iam attach-role-policy \
--role-name AmazonBraketServiceSageMakerNotebookRole \
--policy-arn arn:aws:iam::<account-id>:policy/service-role/AmazonBraketServiceSageMakerNotebookAccess
aws iam attach-role-policy \
--role-name AmazonBraketServiceSageMakerNotebookRole \
--policy-arn arn:aws:iam::aws:policy/AmazonBraketFullAccessSeparately, grant the principal that creates the notebook iam:PassRole on the
exact notebook execution-role ARN, restricted to SageMaker:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::<account-id>:role/service-role/AmazonBraketServiceSageMakerNotebookRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": "sagemaker.amazonaws.com"
}
}
}
]
}S3 results bucket
For new S3 buckets:
- Use the Secure New Bucket workflow in the
securing-s3-bucketsskill when available; otherwise follow Security best practices for Amazon S3. - Meet the Braket requirements in Using Amazon S3 buckets with Amazon Braket.
If the user requires a customer managed KMS key, use the key the user specifies.
Customer Managed Keys
If the user specifies a customer-managed KMS key, ask the user about adding the following statements, substituting the placeholders enclosed in angle brackets <>, to the key's existing key policy following the API procedure at Change a key policy.
[
{
"Sid": "Allow Amazon Braket to write quantum task results to S3 with this key",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::<account-id>:role/aws-service-role/braket.amazonaws.com/AWSServiceRoleForAmazonBraket"},
"Action": "kms:GenerateDataKey",
"Resource": "*",
"Condition": {
"StringEquals": {"kms:ViaService": "s3.<key-region>.amazonaws.com"},
"StringLike": {"kms:EncryptionContext:aws:s3:arn": ["arn:aws:s3:::<bucket>", "arn:aws:s3:::<bucket>/*"]}
}
},
{
"Sid": "Allow the Braket hybrid jobs execution role to use this key through S3",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::<account-id>:role/service-role/AmazonBraketJobsExecutionRole"},
"Action": ["kms:Decrypt", "kms:GenerateDataKey"],
"Resource": "*",
"Condition": {"StringEquals": {"kms:ViaService": "s3.<key-region>.amazonaws.com"}}
},
{
"Sid": "Allow the Braket notebook execution role to use this key through S3",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::<account-id>:role/service-role/AmazonBraketServiceSageMakerNotebookRole"},
"Action": ["kms:Decrypt", "kms:GenerateDataKey"],
"Resource": "*",
"Condition": {"StringEquals": {"kms:ViaService": "s3.<key-region>.amazonaws.com"}}
},
{
"Sid": "Allow the Braket hybrid jobs execution role to describe this key",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::<account-id>:role/service-role/AmazonBraketJobsExecutionRole"},
"Action": "kms:DescribeKey",
"Resource": "*"
}
]For further customization, see Key policies in AWS KMS and Using IAM policies with AWS KMS.
Notebooks
Open notebooks.md for information on creating notebooks.
Spending limits and cost guardrails
Before the first QPU task on each device, search for an existing spending limit and create one if none exists; see spending-limit.md for the device-specific commands.
References
- Developer guide:
- Enable Amazon Braket
- Getting started with Amazon Braket
- Amazon Braket service-linked role
- Hybrid Jobs prerequisites
- Using the API with Hybrid Jobs
- Managing access to Amazon Braket
- Restrict user access to certain S3 buckets
- Restrict user access to certain notebook instances
- Cost tracking and spending limits
- API:
- AWS managed policies:
- Local references:
- AWS IAM skill