Service Accounts for Runtimes and Notebooks

Syntasa supports associating Cloud Service Accounts (AWS IAM Roles or IAM Users) directly with Notebook Workspaces and Runtime Templates. When a notebook is launched or a job is submitted, the platform automatically assumes the correct cloud identity - no manual credential management inside notebook code is required.

Cloud provider support: AWS (IAM Roles and IAM Users) is currently supported. GCP and Azure support is planned for a future release.

Overview

This guide covers:

• How credential resolution works across interactive and batch contexts
• Supported AWS identity types and their trade-offs
• Configuration steps for Workspace and Runtime Template service accounts

How It Works: The Identity Resolution Stack

When a kernel starts or a job is submitted, the platform evaluates credentials in a fixed priority order. The first match wins; the rest are skipped.

Notebooks Flow

Applies to: Workspaces, Notebook Cards, Notebook Process

Important: A Workspace Service Account fully overrides the Runtime Template Service Account. If the Workspace SA lacks permissions needed by background services in that workspace, those services will fail. Ensure the Workspace SA has all required permissions.

Jobs Flow

Applies to: Spark Processors, Scheduled Jobs

There is no active workspace context in this flow. The resolution is simpler:

The Workspace Service Account is completely ignored in jobs, even if the job originated from a workspace that has a SA attached.

Supported Cloud Identities (AWS)

Within a Service Account, two types of AWS identity are supported. They are mutually exclusive — configure one or the other, not both.

IAM Role ARN (Recommended)

The platform calls AWS STS AssumeRole to obtain short-lived temporary credentials (access key, secret key, session token) valid for 12 hours.

AWS prerequisite — MaxSessionDuration: The target IAM role must have its MaxSessionDuration set to at least 43200 seconds (12 hours) in AWS IAM. The AWS default is 3600 seconds (1 hour). If this is not configured, AssumeRole will fail with

DurationSeconds exceeds the MaxSessionDuration set for this role

Trust policy requirement: The Syntasa infrastructure role (K8s node role or EMR instance profile) must be listed as a trusted principal in the target role's trust policy:

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::<ACCOUNT_ID>:role/<SyntasaInfraRole>"
  },
  "Action": "sts:AssumeRole"
}

Syntasa infra role permission: The Syntasa infrastructure role itself must also have sts:AssumeRole permission in its own identity policy to be allowed to make the call. This is typically pre-configured by your platform team — if AssumeRole fails despite a correct trust policy, verify with your platform administrator that this permission is in place.

IAM User (Static Keys)

Provide a static AWS Access Key and Secret Key. These are long-lived credentials with no automatic expiry. While supported, this approach is generally discouraged:

• Keys do not rotate automatically
• If a key is compromised, manual rotation is required
• They do not benefit from the time-limited security of STS sessions

Note: IAM User and IAM Role are mutually exclusive — the UI prevents configuring both on the same Service Account. If both were somehow present, static keys would take priority.

How to Configure

Configuring a Workspace Service Account

1. Navigate to Notebook Workspaces in the Syntasa UI.
2. Select your workspace (or create a new one).
3. Open Workspace Settings → find the Service Account field.
4. Select an existing Service Account from the dropdown, or create a new one pointing to your IAM Role ARN or IAM User credentials.
5. Save. All kernels launched from this workspace will use these credentials.
    

Effect: Overrides the Runtime Template SA for all notebook sessions in this workspace.

Configuring a Runtime Template Service Account

1. Navigate to Runtime Templates in the Syntasa UI.
2. Select an existing template or create a new one.
3. Find the Service Account field and assign the appropriate Service Account.
4. Save. All runtimes provisioned from this template inherit these credentials.

Effect: Used by notebooks (workspaces and cards) when no Workspace SA is set, and by all background jobs running on this runtime — regardless of any Workspace SA.

Required IAM Permissions

Regardless of whether you use an IAM Role or IAM User, the configured identity must have read/write access to the following Syntasa platform folders in your cloud storage bucket. These folders are used by platform services for workspaces, job execution, logging, and cluster operations.

In addition, the identity must have access to AWS Bedrock for AI/ML model inference used by Jupyter AI chat in notebooks.

Required Bedrock permissions:

{
  "Effect": "Allow",
  "Action": [
    "bedrock:InvokeModel",
    "bedrock:InvokeModelWithResponseStream"
  ],
  "Resource": "*"
}

Note: You can restrict Resource to specific model ARNs (e.g. arn:aws:bedrock:<region>::foundation-model/anthropic.claude-*) if your security policy requires least-privilege access to individual models.

Example S3 policy statement (replace <your-bucket> with your actual bucket name):

{
  "Effect": "Allow",
  "Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:DeleteObject",
    "s3:ListBucket"
  ],
  "Resource": [
    "arn:aws:s3:::<your-bucket>/syn-workspace/*",
    "arn:aws:s3:::<your-bucket>/syn-app-logs/*",
    "arn:aws:s3:::<your-bucket>/syn-cluster-config/*",
    "arn:aws:s3:::<your-bucket>/syn-file-uploads/*",
    "arn:aws:s3:::<your-bucket>/syn-volumes/*",
    "arn:aws:s3:::<your-bucket>/syn-spark-history/*",
    "arn:aws:s3:::<your-bucket>/syn-cluster-logs/*",
    "arn:aws:s3:::<your-bucket>"
  ]
}

Note: If your IAM role does not have access to these folders, platform services (including notebook kernels and Spark jobs) will fail with AccessDenied errors even if the role is otherwise configured correctly.

Relationship to Session Policy

Service Accounts and Session Policy are complementary, not competing features.

When a Service Account is configured, Session Policy is skipped — the SA's own IAM permissions govern data access. When no SA is configured, Session Policy applies a data-plane-scoped restriction on top of the default cluster role.

Troubleshooting

DurationSeconds exceeds the MaxSessionDuration set for this role

The target IAM role's MaxSessionDuration is below 43200 seconds. Update it:

aws iam update-role --role-name <RoleName> --max-session-duration 43200

AssumeRole fails at job start, falls back to session policy

Common causes:

• Trust policy on the target role does not include the Syntasa infrastructure role.
• Role ARN is malformed or points to a non-existent role 
• Network connectivity to the STS endpoint is blocked

Contact your platform administrator to check the runtime-service logs for details.

Credentials expired mid-session (notebook)

Credentials are issued at kernel start and are not refreshed. Restart the kernel from the Syntasa portal to receive a fresh 12-hour set.

Job uses wrong identity (background job)

Verify the Service Account is attached to the Runtime Template, not the Workspace. Background jobs ignore Workspace SAs entirely.

Identity check shows node role instead of expected SA role

Verify the Service Account is attached to the correct entity — Workspace or Runtime Template — depending on your use case. If the configuration looks correct, contact your platform administrator to review runtime-service logs for credential injection failures.