This section guides you through management of AWS IAM roles needed for operating Viz Now with your AWS account.

Secure, reliable operations are ensured by first clarifying permissions and adopting these best practices.

Overview

Viz Now requires two IAM roles:

IAM Role Name

Purpose

Used By

viz-now-deploy-infra

Provisions infrastructure via Terraform

Deployment Agent

viz-now-manage

Manages deployed instances

Control Plane

These roles are assumed using AWS STS (Security Token Service), and their ARNs are stored securely in Viz Now.

Prerequisites

  • An active AWS account.

  • IAM Administrator access to AWS.

  • Administrator access to the Viz Now platform.

Update Existing IAM Roles

If your AWS account already has Viz Now IAM roles defined, follow these guidelines to update them.

Note: If your AWS account has no Viz Now IAM roles defined, first see section Create New IAM Roles.

IAM Roles

You will update both the Deploy and Management IAM roles and their associated inline policies.

To update an IAM role in Viz Now

This procedure assumes that your Viz Now user details are already setup in AWS. See the Note above.

  1. Log in to your AWS Management Console with IAM Administrator permissions.
    Keep this tab active in your browser.

  2. Log in to the Viz Now and navigate to the panel Organization > Infrastructure tab > Manage IAM Roles.
    You’ll see a screen like the one below, where you can define the IAM Role ARNs for the Deploy and Control Plane functionality.

    i1.png

    Keep this tab active in your browser.

    Deploy role

  3. Update the inline policy:

    1. Switch to the AWS console IAM > Roles and from the Permissions tab, you can search for required inline policy.
      This is the same as in the Viz Now UI:

      roleCopy.pngimage-20250516-143808.png

      Click it to open.

    2. Go back to Viz Now and in the Manage IAM Roles panel, next to Deploy Role, click the Question mark icon image-20250513-065709.png.

      pol99.png

      and then Copy inline policy.

      dRole.png

      (This saves the policy details to the clipboard).

    3. Switch back to the AWS Console Policy editor and click the JSON button.

      image-20250516-145917.png

    4. In the Policy editor, paste-in the inline policy from the clipboard.

      JSON2.png

    5. Click Next and then click Save changes.

    6. A confirmation message is displayed.

      image-20250516-150538.png


      Management Role
      You now repeat the same steps for the Management role.

  4. In Viz Now, next to the input field Management Role, click the Question mark icon image-20250513-065709.png.

    ManRo1.png

    1. From the pop-up, click Copy inline policy.

      image-20250516-150844.png

    2. In the AWS Console, search for the required manage role, in this example, viz-now-manage, and click on it to display a Summary page.

      image-20250516-152830.png

    3. Select the Permissions tab and then its contained policy.
      The Policy editor page opens:

      image-20250516-155850.png

    4. Paste-in the inline policy that you copied to your clipboard, to update the JSON code.
      For an example, see the code below.

    5. Click Save changes.

  5. Validate IAM Role in Viz Now:

    1. Click Cancel.

    2. In Viz Now Manage IAM Roles panel, click Validate Roles.

      valRo.png

    3. A confirmation message is displayed.

      conRo.png

Create New IAM Roles

If you have not defined any IAM roles for Viz Now, follow these guidelines.

Note: If you have already have Viz Now IAM roles defined for your AWS account, see to Update Existing IAM Roles below.

Defining a new IAM Role

You will create both a Deploy role and a Management role, and associate customized Viz Now trust relationships and policies.

To define an IAM role in Viz Now

  1. Log in to Viz Now and navigate to Organization > Infrastructure tab > Manage IAM Roles.

    IAM5.png

  2. You’ll see a screen like the one below, where you define the IAM Roles ARNs needed for a Deploy role.

    IAMD1.png

    Deploy Role
    The role viz-now-deploy-infra allows deploying infrastructure in your AWS Account.

  3. Log in to the AWS Management Console with IAM Administrator rights.

  4. Back in Viz Now, click Edit Roles.

    role4.jpeg.png

  5. Next to the Deploy Role input field, click the image-20250513-065709.png icon.

    image-20250516-091805.png

  6. From the pop-up, follow the link click here to open the AWS console.

    image-20250516-094020.png

  7. The AWS console opens in a new tab (if not logged-in, you will need to authenticate).

    5a32d743-a29e-4251-a098-78a82bddbbe1.png

  8. Click Next twice to skip the Add permissions step and arrive at Name, review, and create.
    Role Name is pre-populated as: viz-now-deploy-infra.

  9. Click Create Role.
    A confirmation message is displayed.

    image-20250516-095126.png

Note: If a warning indicates that the name already exists, update it by adding a suffix, for example: viz-now-deploy-infra-something else.

  1. Click View role, AWS opens with the Summary page of the new role:

    newRole.png


    Update the Trust Policy

  2. Back in Viz Now, click Copy trust policy.

    image-20250516-095923.png

  3. Switching back to the AWS console, on the tab Trust relationships, click Edit trust policy.

    image-20250516-101147.png

  4. Paste the trust policy and click Update Policy.

  5. The JSON code, shown below and which you can copy, is verified.

    {
    "Version": "2012-10-17",
    "Statement": [
    {
    "Effect": "Allow",
    "Principal": {
    "AWS": "arn:aws:iam::324880187172:root"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
    "StringLike": {
    "sts:ExternalId": "SpaceliftIntegration@*"
    }
    }
    }
    ]
    }

Code

Explanation

Principal

Allows the Deployment Agent’s AWS account (here324880187172) to assume the role.

Condition

Ensures the external ID starts with SpaceliftIntegration@.

  1. Continue in the AWS console by clicking the role’s name in the breadcrumbs to reach the role’s Summary page:

    image-20250516-103151.png

  2. From the Permissions tab, click Add permissions > Create inline policy.

    image-20250516-103339.png

  3. Go back to Viz Now, and from the input field Deploy Role, click Copy inline policy.

    image-20250516-103507.png

  4. Back to the AWS console, in the Policy editor, click the JSON button and then paste the inline policy into the Policy editor.

    policyInline.png

  5. The pasted JSON looks like:

    {
    "Version": "2012-10-17",
    "Statement": [
    {
    "Sid": "VizNowDeployInfra0",
    "Effect": "Allow",
    "Action": [
    "iam:*",
    "s3:*",
    "kms:*",
    "route53:*",
    "sts:*",
    "ec2:*",
    "tag:*",
    "logs:*"
    ],
    "Resource": "*"
    }
    ]
    }

  6. Click Next, and in the input field Policy name, name the policy (for example use, viz-now-deploy-infra-inline-policy) and click Create policy.

    image-20250516-104924.png

  7. Associate the IAM Role in Viz Now:

    1. Copy the role’s ARN from the AWS Console.

      pol1.png

    2. Over in Viz Now, in Manage IAM Roles, paste the ARN from the clipboard into the field Deploy Role.

      depRole5.png

      (The Update Roles button will be enabled only after filling the Management Role ARN in the next steps).

      Management Role
      The viz-now-manage role enables Viz Now to manage deployed instances and perform operational tasks.

  8. Still in the Manage IAM Roles menu, click the image-20250513-065709.png icon next to the input field Management Role.

    depRole6.png

    1. Follow the link Click here, the AWS Console opens.

      image-20250509-153208.png

    2. Click Next twice to skip the Add permissions step and arrive at the Name, review, and create menu.
      Role Name is pre-populated as viz-now-manage.

      image-20250516-105756.png

    3. Click Create Role.
      Note: If a warning indicates that the name already exists, update it by adding a suffix, for example: viz-now-manage-something else.

    4. Click View role.
      A confirmation message is displayed:

      image-20250516-110405.png

  9. Add Inline permissions:

    1. Switch to the AWS console, and from the role’s Summary page, click Permissions tab > Add permissions > Create inline policy.

      inline9.png

    2. Go back to Viz Now, and next to the input field Management Role, click the image-20250513-065709.png icon, then, Copy inline policy.

      image-20250516-110837.png

    3. Switch to the AWS console and click the JSON button.

    4. Paste the inline policy into the Policy editor.

      PE1.png

    5. In the Editor, the pasted-in the JSON code will look like:

      {
      "Version": "2012-10-17",
      "Statement": [
      {
      "Sid": "VizNowManage0",
      "Effect": "Allow",
      "Action": [
      "iam:*",
      "kms:*",
      "route53:*",
      "servicequotas:*",
      "s3:*",
      "ec2:*",
      "tag:*",
      "sts:*",
      "logs:*"
      ],
      "Resource": "*"
      },
      {
      "Sid": "AllowSSMDocumentsForSendCommand",
      "Effect": "Allow",
      "Action": "ssm:SendCommand",
      "Resource": "arn:aws:ssm:*:*:document/*"
      },
      {
      "Sid": "AllowSendCommandToVizNowInstances",
      "Effect": "Allow",
      "Action": ["ssm:SendCommand"],
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
      "StringEquals": {
      "ssm:ResourceTag/VizNow": "true"
      }
      }
      },
      {
      "Sid": "AllowCommandInvocationChecks",
      "Effect": "Allow",
      "Action": ["ssm:ListCommandInvocations", "ssm:GetCommandInvocation"],
      "Resource": "*"
      },
      {
      "Sid": "AllowSSMInventoryReadOnly",
      "Effect": "Allow",
      "Action": ["ssm:ListInventoryEntries", "ssm:DescribeInstanceInformation"],
      "Resource": "*",
      "Condition": {
      "StringEquals": {
      "ssm:ResourceTag/VizNow": "true"
      }
      }
      },
      {
      "Sid": "AllowCreateMediaConnectFlows",
      "Effect": "Allow",
      "Action": ["mediaconnect:CreateFlow"],
      "Resource": "*"
      },
      {
      "Sid": "AllowManageVizNowFlowsByName",
      "Effect": "Allow",
      "Action": [
      "mediaconnect:DeleteFlow",
      "mediaconnect:UpdateFlow",
      "mediaconnect:StartFlow",
      "mediaconnect:StopFlow",
      "mediaconnect:AddFlowOutputs",
      "mediaconnect:RemoveFlowOutput",
      "mediaconnect:UpdateFlowOutput",
      "mediaconnect:AddFlowSources",
      "mediaconnect:RemoveFlowSource",
      "mediaconnect:UpdateFlowSource",
      "mediaconnect:AddFlowVpcInterfaces",
      "mediaconnect:RemoveFlowVpcInterface",
      "mediaconnect:GrantFlowEntitlements",
      "mediaconnect:UpdateFlowEntitlement",
      "mediaconnect:DescribeFlow",
      "mediaconnect:ListEntitlements"
      ],
      "Resource": "arn:aws:mediaconnect:*:*:*VizNow-*"
      },
      {
      "Sid": "AllowListMediaConnectFlows",
      "Effect": "Allow",
      "Action": [
      "mediaconnect:ListFlows",
      "mediaconnect:DescribeFlow",
      "mediaconnect:ListTagsForResource"
      ],
      "Resource": "*"
      }
      ]
      }

    6. Click Next, and in Policy name, provide an identity for the policy (for example, use: viz-now-manage-inline-policy), and then click Create policy.

      image-20250516-111302.png

  10. Associate and update the IAM Role in Viz Now:

    1. Copy the role’s ARN from the AWS Console on the Summary page.

      policyOb.png

    2. In Viz Now Manage IAM Roles panel, paste the ARN in Management Role field.

      policy1b.png

    3. To save, click Update Roles.

      policy2b.png

    4. Viz Now validates the updated roles:

      image-20250516-111707.png

Permissions Explained

Deploy Role (viz-now-deploy-infra)

The Deploy role grants broad permissions to allow Spacelift to deploy infrastructure using Terraform. All permissions apply to all resources ("Resource": "*").

Permission

Purpose

Resource Scope

iam:*

Manages IAM roles/users

Scope to specific roles

s3:*

Manages S3 buckets

Scope to specific buckets

kms:*

Manages encryption keys

Scope to specific keys

route53:*

Configures DNS

Scope to specific zones

sts:*

Assumes roles

Necessary for Spacelift

ec2:*

Provisions EC2 resources

Scope to specific VPCs

tag:*

Applies tags

All (*)

logs:*

Manages CloudWatch logs

Scope to specific log groups

Manage Role (viz-now-manage)

The Manage role enables Viz Now to perform operational tasks on deployed instances. Permissions are scoped to specific resources whenever possible.

Key Tasks Enabled by Manage Role

  • Increase service quotas for AWS resources.

  • Reserve specific EC2 instance types.

  • Create S3 buckets for file storage.

  • Manage security groups for IP-based access.

  • Handle VPC peering.

  • Start, stop, or destroy instances.

  • Manage MediaConnect flows for streaming.

Permission

Purpose

Resource Scope

iam:*

Manages IAM configurations

All (*)

kms:*

Manages encryption keys

All (*)

route53:*

Updates DNS

All (*)

servicequotas:*

Increases quotas

All (*)

s3:*

Manages S3 buckets

All (*)

ec2:*

Manages instances

All (*)

tag:*

Manages tags

All (*)

sts:*

Assumes roles

All (*)

logs:*

Manages CloudWatch logs

All (*)

ssm:SendCommand

Executes commands

SSM documents & tagged EC2 instances (VizNow=true)

ssm:ListCommandInvocations, etc.

Checks command status

All (*)

ssm:ListInventoryEntries, etc.

Retrieves instance details

Tagged resources (VizNow=true)

mediaconnect:CreateFlow

Creates MediaConnect flows

All (*)

mediaconnect:* (multiple)

Manages MediaConnect flows

Flows named VizNow-*

mediaconnect:ListFlows, etc.

Lists flows

All (*)

Additional Resources