IAM Roles & Permissions

This document explains the IAM roles and permissions required for Ownstak to provision and manage resources in your AWS account.

CloudFormation Templates

Ownstak provides two CloudFormation templates for setting up the required IAM roles:

Standard Template (Recommended)

The standard template includes broad permissions that allow Ownstak to manage all aspects of your AWS infrastructure. This template is recommended for most users as it provides flexibility for future Ownstak features.

Download Standard Template (ownstak_iam_roles.yml)

Minimal Template

The minimal template includes only the essential permissions required for current Ownstak functionality. This template is suitable for users who prefer the principle of least privilege.

Note: If you use the minimal template, you may need to update it when new Ownstak features are released.

Download Minimal Template (ownstak_iam_roles_minimal.yml)

Deploying the Templates

1. Download one of the templates above
2. In the AWS CloudFormation console, create a new stack
3. Upload the template file
4. Review and create the stack

After deployment, you'll have an IAM user called "OwnstakCloudCredentialsUser" that you can use to generate access keys for Ownstak.

Detailed Permission Analysis

The following table documents every permission in the minimal template and explains how Ownstak uses it:

ACM (Certificate Manager) Permissions

Permission	Purpose
acm:ListCertificates	Checks if SSL certificates already exist for the domain
acm:RequestCertificate	Creates new SSL certificates for *.your-backend.your-org.ownstak.link domains
acm:DeleteCertificate	Removes SSL certificates when tearing down cloud backends
acm:DescribeCertificate	Checks certificate validation status and retrieves DNS validation records
acm:AddTagsToCertificate	Adds tags to certificates for resource management

EC2 Permissions

Permission	Purpose
ec2:AuthorizeSecurityGroupIngress	Adds inbound rules to security groups for ALB and ECS communication
ec2:CreateSecurityGroup	Creates security groups for Application Load Balancer and ECS tasks
ec2:CreateTags	Tags security groups for resource management
ec2:DeleteSecurityGroup	Removes security groups during teardown
ec2:DescribeAccountAttributes	Checks account limits and capabilities
ec2:DescribeInstances	Lists EC2 instances for single-instance mode management
ec2:DescribeSecurityGroups	Checks if security groups already exist
ec2:DescribeSubnets	Discovers available subnets for VPC configuration
ec2:DescribeVpcs	Finds default VPC or validates custom VPC configuration
ec2:RunInstances	Creates EC2 instances for single-instance mode deployments
ec2:TerminateInstances	Removes EC2 instances during single-instance mode teardown

Elastic Load Balancing Permissions

Permission	Purpose
elasticloadbalancing:AddTags	Tags load balancers for resource management
elasticloadbalancing:CreateListener	Creates HTTP (80) and HTTPS (443) listeners on the ALB
elasticloadbalancing:CreateLoadBalancer	Creates Application Load Balancer in public subnets
elasticloadbalancing:CreateTargetGroup	Creates target groups for routing traffic to ECS tasks
elasticloadbalancing:DeleteLoadBalancer	Removes ALB during teardown
elasticloadbalancing:DeleteTargetGroup	Removes target groups during teardown
elasticloadbalancing:DescribeLoadBalancers	Checks if ALB already exists
elasticloadbalancing:DescribeListeners	Checks if listeners already exist
elasticloadbalancing:DescribeTargetGroups	Checks if target group already exists
elasticloadbalancing:ModifyTargetGroupAttributes	Configures deregistration delay for faster scaling

ECS (Elastic Container Service) Permissions

Permission	Purpose
ecs:DescribeClusters	Checks if ECS cluster already exists
ecs:DescribeServices	Checks if ECS services already exist
ecs:DescribeTaskDefinition	Retrieves task definition details for comparison
ecs:ListServices	Lists all services in a cluster for cleanup
ecs:ListTasks	Lists running tasks for cleanup during teardown
ecs:ListTaskDefinitions	Lists task definition revisions for cleanup
ecs:DeregisterTaskDefinition	Removes task definition revisions during teardown
ecs:CreateCluster	Creates ECS cluster for running Lambda proxy
ecs:CreateService	Creates ECS service for Lambda proxy
ecs:DeleteCluster	Removes ECS cluster during teardown
ecs:DeleteService	Removes ECS service during teardown
ecs:RegisterTaskDefinition	Creates new task definitions for Lambda proxy
ecs:StopTask	Stops running tasks during teardown
ecs:TagResource	Tags ECS resources for management
ecs:UpdateService	Updates ECS service with new task definitions

CloudWatch Logs Permissions

Permission	Purpose
logs:DescribeLogGroups	Checks if log groups already exist
logs:CreateLogGroup	Creates log groups for ECS task logging
logs:DeleteLogGroup	Removes log groups during teardown
logs:GetLogEvents	Retrieves log events for debugging and monitoring
logs:GetLogRecord	Gets specific log records for analysis
logs:ListTagsLogGroup	Lists tags on log groups for resource management
logs:PutRetentionPolicy	Sets log retention policy (60 days)
logs:TagLogGroup	Tags log groups for resource management

Lambda Permissions

Permission	Purpose
lambda:ListFunctions	Lists Lambda functions for cleanup during teardown
lambda:CreateAlias	Creates version aliases for deployments (deployment-123)
lambda:CreateFunction	Creates Lambda functions for your applications
lambda:DeleteAlias	Removes aliases during teardown
lambda:GetAlias	Checks if deployment alias already exists
lambda:GetFunction	Checks if Lambda function already exists
lambda:GetFunctionConfiguration	Retrieves function configuration for updates
lambda:InvokeFunction	Allows invoking created Lambda functions
lambda:ListAliases	Lists function aliases for cleanup and management
lambda:ListTags	Retrieves function tags
lambda:PublishVersion	Publishes new versions of Lambda functions
lambda:TagResource	Tags Lambda functions for management
lambda:UpdateAlias	Updates aliases to point to new versions
lambda:UpdateFunctionCode	Updates Lambda function code from S3
lambda:UpdateFunctionConfiguration	Updates Lambda function configuration

IAM Permissions

Permission	Purpose
iam:CreateServiceLinkedRole	Creates service-linked role for Elastic Load Balancing
iam:GetRole	Checks if IAM roles already exist
iam:GetInstanceProfile	Checks if IAM instance profiles already exist
iam:passRole	Allows passing IAM roles to Lambda and ECS services

Note: The iam:passRole permission is limited to the following specific roles:

• ownstak-lambda-execution-role: For Lambda function execution
• ownstak-ecs-execution-role: For ECS task execution
• ownstak-ecs-task-role: For ECS task runtime permissions
• ownstak-ec2-instance-profile-role: For EC2 single-instance mode

S3 Permissions

Permission	Purpose
s3:CreateBucket	Creates S3 buckets for assets, compute, and permanent assets
s3:DeleteBucket	Removes S3 buckets during teardown
s3:DeleteObject	Removes objects during bucket cleanup
s3:GetObject	Retrieves deployment artifacts from S3
s3:GetObjectAttributes	Checks object metadata
s3:ListBucket	Lists bucket contents for cleanup
s3:PutBucketPolicy	Sets public read policy for public asset buckets
s3:PutBucketPublicAccessBlock	Configures public access settings for public buckets
s3:PutObject	Uploads deployment artifacts to S3

IAM Roles Created

The templates create the following IAM roles:

Lambda Execution Role

• Name: ownstak-lambda-execution-role
• Purpose: Allows Lambda functions to access S3 buckets and VPC resources
• Used by: Your application Lambda functions

ECS Execution Role

• Name: ownstak-ecs-execution-role
• Purpose: Allows ECS tasks to pull container images and write logs
• Used by: Lambda proxy ECS tasks

ECS Task Role

• Name: ownstak-ecs-task-role
• Purpose: Allows ECS tasks to invoke Lambda functions
• Used by: Lambda proxy ECS tasks

EC2 Instance Profile Role

• Name: ownstak-ec2-instance-profile-role
• Purpose: Allows EC2 instances to invoke Lambda functions (for single-instance mode)
• Used by: EC2 instances in single-instance deployments

For more information about the AWS architecture, see the AWS Integration Guide.