@@ -21,6 +21,58 @@ This template creates:
2121 - AWS CLI configured with appropriate permissions
2222 - IAM permissions to create roles and policies
2323
24+ 3 . ** For EKS Integration** (optional):
25+ - EKS cluster with OIDC provider enabled
26+ - OIDC provider URL (see [ Getting EKS OIDC URL] ( #getting-eks-oidc-url ) below)
27+
28+ ## Getting EKS OIDC URL
29+
30+ If you're enabling EKS integration, you'll need the OIDC provider URL from your EKS cluster.
31+
32+ ### Method 1: AWS CLI (Recommended)
33+ ``` bash
34+ # Get OIDC URL for your cluster
35+ aws eks describe-cluster --name YOUR_CLUSTER_NAME --query ' cluster.identity.oidc.issuer' --output text
36+
37+ # Remove the https:// prefix for the CloudFormation parameter
38+ aws eks describe-cluster --name YOUR_CLUSTER_NAME --query ' cluster.identity.oidc.issuer' --output text | sed ' s|https://||'
39+ ```
40+
41+ ** Example output:**
42+ ```
43+ https://oidc.eks.us-west-2.amazonaws.com/id/ABCDEF1234567890ABCDEF1234567890
44+ ```
45+
46+ ** For CloudFormation parameter (without https://):**
47+ ```
48+ oidc.eks.us-west-2.amazonaws.com/id/ABCDEF1234567890ABCDEF1234567890
49+ ```
50+
51+ ### Method 2: AWS Console
52+ 1 . Go to ** Amazon EKS** in the AWS Console
53+ 2 . Click on your cluster name
54+ 3 . Go to the ** Configuration** tab
55+ 4 . Under ** Details** , look for ** OpenID Connect provider URL**
56+
57+ ### Method 3: kubectl (if you have cluster access)
58+ ``` bash
59+ kubectl get configmap aws-auth -n kube-system -o yaml | grep " oidc"
60+ ```
61+
62+ ### OIDC URL Format
63+ - ** Full URL format** : ` https://oidc.eks.REGION.amazonaws.com/id/CLUSTER_ID `
64+ - ** For CloudFormation parameter** : Use only the part ** after** ` https:// `
65+ - ** Example** : If full URL is ` https://oidc.eks.us-west-2.amazonaws.com/id/ABC123 ` , use ` oidc.eks.us-west-2.amazonaws.com/id/ABC123 `
66+
67+ ### Enabling OIDC on EKS (if not already enabled)
68+ ``` bash
69+ # Check if OIDC is enabled
70+ aws eks describe-cluster --name YOUR_CLUSTER_NAME --query ' cluster.identity.oidc'
71+
72+ # If null, enable OIDC provider
73+ eksctl utils associate-iam-oidc-provider --cluster YOUR_CLUSTER_NAME --approve
74+ ```
75+
2476## Quick Start
2577
2678### 1. Deploy via AWS Console
@@ -43,7 +95,7 @@ aws cloudformation create-stack \
4395 ParameterKey=CustomerName,ParameterValue=yourcompany \
4496 ParameterKey=ExternalID,ParameterValue=YOUR-EXTERNAL-ID \
4597 ParameterKey=CrossAccountRoleArn,ParameterValue=arn:aws:iam::NULLIFY-ACCOUNT:role/NULLIFY-ROLE \
46- ParameterKey=S3BucketName ,ParameterValue=NULLIFY-BUCKET \
98+ ParameterKey=NullifyS3Bucket ,ParameterValue=NULLIFY-BUCKET \
4799 --capabilities CAPABILITY_NAMED_IAM
48100
49101# Check deployment status
@@ -62,82 +114,31 @@ aws cloudformation describe-stacks \
62114
63115``` bash
64116# For EKS clusters, enable integration
117+ # First, get your OIDC URL (see "Getting EKS OIDC URL" section above)
118+ OIDC_URL=$( aws eks describe-cluster --name YOUR_CLUSTER_NAME --query ' cluster.identity.oidc.issuer' --output text | sed ' s|https://||' )
119+
65120aws cloudformation create-stack \
66121 --stack-name nullify-aws-integration \
67122 --template-body file://nullify-cloudformation-template.json \
68123 --parameters \
69124 ParameterKey=CustomerName,ParameterValue=yourcompany \
70125 ParameterKey=ExternalID,ParameterValue=YOUR-EXTERNAL-ID \
71126 ParameterKey=CrossAccountRoleArn,ParameterValue=arn:aws:iam::NULLIFY-ACCOUNT:role/NULLIFY-ROLE \
72- ParameterKey=S3BucketName ,ParameterValue=NULLIFY-BUCKET \
127+ ParameterKey=NullifyS3Bucket ,ParameterValue=NULLIFY-BUCKET \
73128 ParameterKey=EnableEKSIntegration,ParameterValue=true \
74- ParameterKey=EKSOidcProviderURL,ParameterValue=oidc.eks.us-east-1.amazonaws.com/id/YOUR-OIDC-ID \
129+ ParameterKey=EKSOidcProviderURL,ParameterValue=$OIDC_URL \
75130 --capabilities CAPABILITY_NAMED_IAM
76- ```
77131
78- ## Parameters
79-
80- | Parameter | Type | Required | Description |
81- | -----------| ------| ----------| -------------|
82- | ` CustomerName ` | String | Yes | Your company/customer identifier (1-10 chars) |
83- | ` ExternalID ` | String | Yes | External ID provided by Nullify support |
84- | ` CrossAccountRoleArn ` | String | Yes | Nullify's cross-account role ARN |
85- | ` S3BucketName ` | String | Yes | S3 bucket name for data collection (provided by Nullify support) |
86- | ` AWSRegion ` | String | No | AWS region (default: us-east-1) |
87- | ` EnableEKSIntegration ` | String | No | Enable EKS integration (default: false) |
88- | ` EKSOidcProviderURL ` | String | No* | EKS OIDC provider URL (* required if EKS enabled) |
89-
90- ## Resources Created
91-
92- 1 . ** IAMViewOnlyRole** : Main IAM role for Nullify integration
93- 2 . ** ReadOnlyAccessPolicy** : Part 1 of AWS service permissions
94- 3 . ** ReadOnlyAccessPolicy2** : Part 2 of AWS service permissions
95- 4 . ** S3AccessPolicy** : S3 permissions for data collection
96- 5 . ** DenyActionsPolicy** : Security controls to deny sensitive operations
97-
98- ## Outputs
99-
100- - ` RoleArn ` : ARN of the created IAM role
101- - ` RoleName ` : Name of the created IAM role
102-
103- ## Security Features
104-
105- ### Access Controls
106- - ** Cross-Account Trust** : Only trusts specified Nullify role ARN
107- - ** External ID** : Prevents confused deputy attacks
108- - ** Read-Only Permissions** : Comprehensive read access across AWS services
109- - ** Deny Policy** : Explicitly denies sensitive operations like downloading container images
110-
111- ### EKS Integration
112- - ** OIDC Provider** : Supports EKS service account integration
113- - ** Conditional Logic** : EKS resources only created when enabled
114- - ** Service Account Trust** : Specific trust for ` nullify:nullify-k8s-collector-sa `
115-
116- ## Troubleshooting
117-
118- ### Common Issues
119-
120- 1 . ** Stack Creation Failed - Customer Name Invalid**
121- ```
122- Error: Customer name must start with a letter and can only contain letters, numbers, underscores, and hyphens
123- ```
124- ** Solution** : Use only alphanumeric characters, underscores, and hyphens (1-10 characters)
125-
126- 2 . ** Stack Creation Failed - OIDC Provider Not Found**
127- ```
128- Error: Invalid identity provider
129- ```
130- ** Solution** : Ensure EKS cluster has OIDC provider enabled and URL is correct
131-
132- 3 . ** External ID Mismatch**
133- ```
134- Error: Access denied during role assumption
135- ```
136- ** Solution** : Verify external ID with Nullify support
137-
138- ## Next Steps
139-
140- 1 . ✅ Note the role ARN from stack outputs
141- 2 . ✅ Provide role ARN to Nullify support team
142- 3 . ✅ Verify integration in Nullify dashboard
143- 4 . ✅ Monitor CloudTrail for role assumption events
132+ # Or manually with a specific OIDC URL:
133+ aws cloudformation create-stack \
134+ --stack-name nullify-aws-integration \
135+ --template-body file://nullify-cloudformation-template.json \
136+ --parameters \
137+ ParameterKey=CustomerName,ParameterValue=yourcompany \
138+ ParameterKey=ExternalID,ParameterValue=YOUR-EXTERNAL-ID \
139+ ParameterKey=CrossAccountRoleArn,ParameterValue=arn:aws:iam::NULLIFY-ACCOUNT:role/NULLIFY-ROLE \
140+ ParameterKey=NullifyS3Bucket,ParameterValue=NULLIFY-BUCKET \
141+ ParameterKey=EnableEKSIntegration,ParameterValue=true \
142+ ParameterKey=EKSOidcProviderURL,ParameterValue=A78D8794A06CAE5791C5812CDB164C7D.gr7.ap-southeast-2.eks.amazonaws.com \
143+ --capabilities CAPABILITY_NAMED_IAM
144+ ```
0 commit comments