Team Access Management

Overview

ModelKnife provides team-based access control through AWS IAM groups. This allows you to manage who can deploy services, run pipelines, and perform administrative tasks.

Prerequisites

Before running mk setup init, ensure your AWS account and IAM user are properly configured with the necessary permissions.

1. AWS Account Setup Verification

Verify your AWS account is ready for ModelKnife setup:

# Check your AWS connection
aws sts get-caller-identity

Expected output should show your account ID, user ARN, and user ID:

{
    "UserId": "AIDACKCEVSQ6C2EXAMPLE",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/your-username"
}

2. AWS Console Setup Instructions

This section provides detailed step-by-step instructions for setting up IAM permissions through the AWS Management Console. Follow these steps if you prefer using the web interface over CLI commands.

Step 1: Access the AWS IAM Console

1. Sign in to the AWS Management Console
2. Navigate to the IAM service by:
   • Typing "IAM" in the search bar at the top
   • Or clicking "Services" → "Security, Identity, & Compliance" → "IAM"
3. You should see the IAM dashboard with navigation options on the left

Step 2: Create IAM User (If Needed)

If you don't already have an IAM user for ModelKnife administration:

1. Navigate to Users:
   • Click "Users" in the left navigation panel
   • Click the "Add users" button
2. Configure User Details:
   • Enter username: modelknife-admin (or your preferred name)
   • Check both access types:
     • ✅ "Programmatic access" (for AWS CLI)
     • ✅ "AWS Management Console access" (for web interface)
   • For console access, choose "Custom password" and set a secure password
   • Uncheck "Require password reset" if you don't want to change it on first login
   • Click "Next: Permissions"
3. Set Permissions (Choose One Option):

   Option A: AWS Managed Policy (Quick Setup)

   • Click "Attach existing policies directly"
   • Search for "AdministratorAccess"
   • Check the box next to "AdministratorAccess"
   • Click "Next: Tags"

   Note: This provides very broad permissions but may cause errors in some regions

   Option B: Custom Policy (Recommended)

   • Click "Create policy" (opens in new tab)
   • Follow the Step 3: Create Custom Policy instructions below
   • Return to this tab and click the refresh button
   • Search for "ModelKnifeAdminPolicy"
   • Check the box next to your custom policy
   • Click "Next: Tags"
4. Add Tags (Optional):
   • Add tags if your organization requires them
   • Example: Key="Purpose", Value="ModelKnife Administration"
   • Click "Next: Review"
5. Review and Create:
   • Review all settings
   • Click "Create user"
   • Important: Download the CSV file with credentials or copy the Access Key ID and Secret Access Key
   • Store these credentials securely - you won't be able to see the secret key again

Step 3: Create Custom Policy (Recommended Option)

If you chose Option B above, follow these detailed steps to create the custom policy:

1. Navigate to Policies:
   • In the IAM console, click "Policies" in the left navigation
   • Click the "Create policy" button
2. Choose JSON Editor:
   • Click the "JSON" tab (not the Visual editor)
   • You'll see a default policy template
3. Replace with ModelKnife Policy:
   • Delete all existing content in the JSON editor
   • Copy the complete policy from the code block in section 5 below
   • Paste it into the JSON editor
   • The policy should start with {"Version": "2012-10-17"...
4. Validate and Continue:
   • Click "Next: Tags" (AWS will validate the JSON automatically)
   • If you see any JSON errors, double-check that you copied the complete policy
5. Add Tags (Optional):
   • Add tags if required by your organization
   • Click "Next: Review"
6. Name and Create Policy:
   • Policy name: ModelKnifeAdminPolicy
   • Description: Minimum required permissions for ModelKnife setup and administration
   • Review the policy summary to ensure it includes IAM permissions
   • Click "Create policy"

Step 4: Attach Policy to Existing User

If you already have an IAM user and need to add ModelKnife permissions:

1. Navigate to Your User:
   • Click "Users" in the left navigation
   • Click on your username from the list
2. Add Permissions:
   • Click the "Permissions" tab
   • Click "Add permissions" button
   • Select "Attach existing policies directly"
3. Select Policy:
   • For AWS managed policy: Search for "AdministratorAccess" and check it
   • For custom policy: Search for "ModelKnifeAdminPolicy" and check it
   • Click "Next: Review"
4. Review and Apply:
   • Review the permissions being added
   • Click "Add permissions"

Step 5: Generate Access Keys (If Needed)

If your user doesn't have programmatic access keys for AWS CLI:

1. Access Security Credentials:
   • In your user's details page, click the "Security credentials" tab
   • Scroll down to "Access keys" section
2. Create Access Key:
   • Click "Create access key"
   • Select "Command Line Interface (CLI)" as the use case
   • Check the confirmation checkbox
   • Click "Next"
3. Add Description (Optional):
   • Add a description like "ModelKnife CLI access"
   • Click "Create access key"
4. Save Credentials:
   • Important: Copy both the Access Key ID and Secret Access Key
   • Or click "Download .csv file" to save them
   • Store these securely - you won't be able to see the secret key again
   • Click "Done"

Step 6: Verify Console Setup

After completing the console setup, verify everything is configured correctly:

Test your setup with these commands:

# Test AWS connection
aws sts get-caller-identity

# Test IAM permissions
aws iam get-user

# Test policy listing (should not give permission errors)
aws iam list-policies --max-items 1

Console Setup Troubleshooting

3. AWS CLI Configuration

Configure AWS CLI with your IAM user credentials:

# Configure AWS CLI
aws configure

# Or configure a specific profile
aws configure --profile modelknife-admin

You'll need to provide:

• AWS Access Key ID: From your IAM user
• AWS Secret Access Key: From your IAM user
• Default region: Your preferred AWS region (e.g., us-east-1)
• Default output format: json (recommended)

4. Required IAM Permissions

The admin user needs comprehensive IAM permissions to run mk setup init. This section provides the complete list of required permissions organized by category, along with explanations for why each permission is needed.

Complete IAM Permissions Policy

Use this complete policy for your admin user. You can either copy the JSON below or download the ready-to-use policy file:

You can download the policy file directly to use in the AWS Console:

Download Policy JSON

Or copy and paste this JSON directly into a custom IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "IAMRoleManagement",
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:GetRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:PutRolePolicy",
                "iam:GetRolePolicy",
                "iam:DeleteRolePolicy",
                "iam:ListAttachedRolePolicies",
                "iam:ListRolePolicies",
                "iam:PassRole"
            ],
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "iam:RoleName": "mlknife-*"
                }
            }
        },
        {
            "Sid": "IAMGroupManagement",
            "Effect": "Allow",
            "Action": [
                "iam:CreateGroup",
                "iam:GetGroup",
                "iam:AttachGroupPolicy",
                "iam:DetachGroupPolicy",
                "iam:AddUserToGroup",
                "iam:RemoveUserFromGroup",
                "iam:ListGroupsForUser"
            ],
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "iam:GroupName": "mlknife-*"
                }
            }
        },
        {
            "Sid": "IAMPolicyManagement",
            "Effect": "Allow",
            "Action": [
                "iam:CreatePolicy",
                "iam:GetPolicy",
                "iam:GetPolicyVersion"
            ],
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "iam:PolicyName": "MLKnife*"
                }
            }
        },
        {
            "Sid": "IAMReadOnlyOperations",
            "Effect": "Allow",
            "Action": [
                "iam:GetUser",
                "iam:GetAccountSummary",
                "iam:ListUsers",
                "iam:ListGroups",
                "iam:ListPolicies",
                "iam:ListRoles"
            ],
            "Resource": "*"
        },
        {
            "Sid": "STSOperations",
            "Effect": "Allow",
            "Action": [
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        }
    ]
}

Permission Categories Explained

Alternative: Using AWS Managed Policies

If you prefer to use AWS managed policies instead of the custom policy above, you can attach these policies to your admin user:

# Option 1: Full administrative access (broadest permissions)
arn:aws:iam::aws:policy/AdministratorAccess

# Option 2: IAM-specific administrative access (more restrictive)
arn:aws:iam::aws:policy/IAMFullAccess

Additional Policy Examples

For specific organizational requirements, here are additional policy examples you can use:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:GetRole",
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:PassRole",
                "iam:CreateGroup",
                "iam:GetGroup",
                "iam:AttachGroupPolicy",
                "iam:CreatePolicy",
                "iam:GetPolicy",
                "iam:GetUser",
                "iam:AddUserToGroup",
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:GetRole",
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:PassRole"
            ],
            "Resource": "arn:aws:iam::*:role/mlknife-*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateGroup",
                "iam:GetGroup",
                "iam:AttachGroupPolicy"
            ],
            "Resource": "arn:aws:iam::*:group/mlknife-*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreatePolicy",
                "iam:GetPolicy"
            ],
            "Resource": "arn:aws:iam::*:policy/MLKnife*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:GetUser",
                "iam:AddUserToGroup",
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        }
    ]
}

6. Permission Verification Steps

Before running mk setup init, verify that your IAM permissions are correctly configured using these validation commands:

Basic AWS Access Verification

# 1. Verify AWS connection and identity
aws sts get-caller-identity

# 2. Check your current IAM user details
aws iam get-user

# 3. Verify AWS region configuration
aws configure get region

IAM Permission Validation

Test specific IAM permissions required for ModelKnife setup:

# Test role management permissions
aws iam list-roles --max-items 1

# Test group management permissions  
aws iam list-groups --max-items 1

# Test policy management permissions
aws iam list-policies --scope Local --max-items 1

# Test user management permissions
aws iam list-users --max-items 1

Advanced Permission Testing

For more thorough validation, test actual resource creation (these commands create and immediately delete test resources):

# Test role creation (creates and deletes a test role)
aws iam create-role --role-name mlknife-test-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "lambda.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }' && aws iam delete-role --role-name mlknife-test-role

# Test group creation (creates and deletes a test group)
aws iam create-group --group-name mlknife-test-group && \
aws iam delete-group --group-name mlknife-test-group

Expected Verification Results

All verification commands should complete successfully:

Troubleshooting Permission Issues

# Validate policy JSON syntax (if you have the file locally)
aws iam validate-policy-document --policy-document file://modelknife-admin-policy.json

# Test specific IAM permissions
aws iam simulate-principal-policy \
    --policy-source-arn $(aws sts get-caller-identity --query Arn --output text) \
    --action-names iam:CreateRole iam:CreateGroup iam:CreatePolicy \
    --resource-arns "*"

# Quick permission check - should return without errors
aws iam get-account-summary --query 'SummaryMap.{Users:Users,Groups:Groups,Roles:Roles}' --output table

# List policies attached to your user
aws iam list-attached-user-policies --user-name $(aws sts get-caller-identity --query 'Arn' --output text | cut -d'/' -f2)

# Get the policy document to verify it matches
aws iam get-policy --policy-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/ModelKnifeAdminPolicy \
    --query 'Policy.{PolicyName:PolicyName,Description:Description}' --output table

# Test the policy allows basic operations
aws iam list-roles --max-items 1 --query 'Roles[0].RoleName' --output text