iam-manager

A Kubernetes operator that manages AWS IAM roles for namespaces and service accounts using custom resources.

Table of Contents

• Overview
• Requirements
• Features
• Architecture
• Quick Start
• Usage
• Documentation
• Version Compatibility
• Contributing

Overview

iam-manager simplifies AWS IAM role management within Kubernetes clusters by providing a declarative approach through custom resources. It enables namespace-scoped IAM role creation, enforces security best practices, and integrates with AWS IAM Role for Service Accounts (IRSA).

Originally developed at Intuit to manage IAM roles across 200+ clusters and 8000+ namespaces, iam-manager allows application teams to create and update IAM roles as part of their GitOps deployment pipelines, eliminating manual IAM policy management. This enables a "single manifest" approach where teams can manage both Kubernetes resources and IAM permissions together. For more details on the design principles and origin story, see the Managing IAM Roles as K8s Resources article.

Requirements

• Kubernetes cluster 1.16+
• AWS IAM permissions to create/update/delete roles
• AWS account with permission boundary policy configured
• Cert-manager (for webhook validation, optional)

Features

iam-manager provides a comprehensive set of features for IAM role management:

• IAM Roles Management - Create, update, and delete IAM roles through Kubernetes resources
• IAM Role for Service Accounts (IRSA) - Integration with AWS IAM Roles for Service Accounts
• AWS Service-Linked Roles - Support for service-linked roles
• Default Trust Policy for All Roles - Enforce consistent trust policies
• Maximum Number of Roles per Namespace - Governance controls
• Attaching Managed IAM Policies for All Roles - Simplified policy management
• Multiple Trust policies - Flexible trust relationship configuration

Architecture

iam-manager follows a Kubernetes operator pattern that watches for Iamrole custom resources and manages the corresponding IAM roles in AWS.

The controller reconciles Kubernetes resources with AWS IAM roles, ensuring that:

• Each valid Iamrole CR has a corresponding IAM role in AWS
• Changes to Iamrole CRs are reflected in the AWS IAM roles
• Deleted Iamrole CRs result in cleanup of the corresponding AWS resources

For a more detailed view of the architecture including component interactions and workflows, see the Architecture Documentation.

Quick Start

The fastest way to install iam-manager is to use the provided installation script:

git clone https://github.com/keikoproj/iam-manager.git
cd iam-manager
./hack/install.sh [cluster_name] [aws_region] [aws_profile]

For detailed installation instructions, configuration options, and prerequisites, see the Installation Guide.

Usage

Here's a minimal example of an IAM role for accessing S3:

apiVersion: iammanager.keikoproj.io/v1alpha1
kind: Iamrole
metadata:
  name: s3-reader-role
  namespace: default
spec:
  PolicyDocument:
    Statement:
      - Effect: "Allow"
        Action:
          - "s3:GetObject"
          - "s3:ListBucket"
        Resource:
          - "arn:aws:s3:::your-bucket-name/*"
          - "arn:aws:s3:::your-bucket-name"
        Sid: "AllowS3Access"

For IRSA (IAM Roles for Service Accounts) integration:

apiVersion: iammanager.keikoproj.io/v1alpha1
kind: Iamrole
metadata:
  name: app-role
  namespace: default
  annotations:
    iam.amazonaws.com/irsa-service-account: app-service-account
spec:
  PolicyDocument:
    Statement:
      - Effect: "Allow"
        Action: ["s3:GetObject"]
        Resource: ["arn:aws:s3:::your-bucket-name/*"]

For detailed examples and usage patterns, see the examples directory and the CRD Reference.

Documentation

Comprehensive documentation is available:

• Architecture Documentation
• Quick Start Guide
• Design Documentation
• Configuration Options
• Developer Guide
• AWS Integration
• AWS Security
• Features
• Installation Guide
• CRD Reference
• Troubleshooting Guide

Version Compatibility

iam-manager Version	Kubernetes Version	Go Version	Key Features
current	1.16 - 1.27	1.24+	Upgrade to Go 1.24
v0.22.0	1.16 - 1.25	1.19+	IRSA regional endpoint configuration
v0.21.0	1.16 - 1.24	1.18+	Enhanced security features
v0.20.0	1.16 - 1.23	1.17+	Improved reconciliation controller
v0.19.0	1.16 - 1.22	1.16+	IRSA support improvements
v0.18.0	1.16 - 1.21	1.15+	Custom role naming

For detailed information about each release, see the GitHub Releases page.

Contributing

Please check CONTRIBUTING.md before contributing.