Allow wildcard matching of service account subject (#8629)

* Allow wildcard matching for service account subject

* Add subjectPattern property to iamserviceaccounts.md

* Remove misleading comment in iamserviceaccount.go

Author: avoidik

pkg/apis/eksctl.io/v1alpha5/assets/schema.json

@@ -975,6 +975,11 @@
         "status": {
           "$ref": "#/definitions/ClusterIAMServiceAccountStatus"
         },
+        "subjectPattern": {
+          "type": "string",
+          "description": "Subject pattern to use in the trust policy condition. When set, this pattern is used instead of the service account name, and StringLike is used instead of StringEquals to allow wildcard matching.",
+          "x-intellij-html-description": "Subject pattern to use in the trust policy condition. When set, this pattern is used instead of the service account name, and StringLike is used instead of StringEquals to allow wildcard matching."
+        },
         "tags": {
           "additionalProperties": {
             "type": "string"
@@ -998,7 +1003,8 @@
         "status",
         "roleName",
         "roleOnly",
-        "tags"
+        "tags",
+        "subjectPattern"
       ],
       "additionalProperties": false,
       "description": "holds an IAM service account metadata and configuration",

pkg/apis/eksctl.io/v1alpha5/iam.go

@@ -124,6 +124,12 @@ type ClusterIAMServiceAccount struct {
 	// AWS tags for the service account
 	// +optional
 	Tags map[string]string `json:"tags,omitempty"`
+
+	// Subject pattern to use in the trust policy condition. When set, this pattern is used
+	// instead of the service account name, and StringLike is used instead of StringEquals
+	// to allow wildcard matching.
+	// +optional
+	SubjectPattern string `json:"subjectPattern,omitempty"`
 }
 
 // ClusterIAMServiceAccountStatus holds status of the IAM service account

pkg/cfn/builder/iam.go

@@ -344,6 +344,7 @@ func NewIAMRoleResourceSetForServiceAccount(spec *api.ClusterIAMServiceAccount,
 		wellKnownPolicies:   spec.WellKnownPolicies,
 		roleName:            spec.RoleName,
 		permissionsBoundary: spec.PermissionsBoundary,
+		subjectPattern:      spec.SubjectPattern,
 		description: fmt.Sprintf(
 			"IAM role for serviceaccount %q %s",
 			spec.NameString(),
@@ -427,6 +428,7 @@ type IAMRoleResourceSet struct {
 	namespace           string
 	permissionsBoundary string
 	description         string
+	subjectPattern      string
 }
 
 // NewIAMRoleResourceSetWithAttachPolicyARNs builds IAM Role stack from the give spec
@@ -525,6 +527,9 @@ func (rs *IAMRoleResourceSet) makeAssumeRolePolicyDocument() cft.MapOfInterfaces
 	}
 	if rs.serviceAccount != "" && rs.namespace != "" {
 		logger.Debug("service account location provided: %s/%s, adding sub condition", api.AWSNodeMeta.Namespace, api.AWSNodeMeta.Name)
+		if rs.subjectPattern != "" {
+			return rs.oidc.MakeAssumeRolePolicyDocumentWithServiceAccountConditionsAllowingWildcard(rs.namespace, rs.subjectPattern)
+		}
 		return rs.oidc.MakeAssumeRolePolicyDocumentWithServiceAccountConditions(rs.namespace, rs.serviceAccount)
 	}
 	return rs.oidc.MakeAssumeRolePolicyDocument()

pkg/cfn/builder/iam_test.go

@@ -254,6 +254,42 @@ var _ = Describe("template builder for IAM", func() {
 			Expect(t).To(HaveOutputWithValue(outputs.IAMServiceAccountRoleName, `{ "Fn::GetAtt": "Role1.Arn" }`))
 		})
 
+		It("can construct an iamserviceaccount addon template with subject pattern using wildcards", func() {
+			serviceAccount := &api.ClusterIAMServiceAccount{}
+
+			serviceAccount.Name = "sa-1"
+			serviceAccount.SubjectPattern = "app-*"
+
+			serviceAccount.AttachPolicyARNs = []string{"arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"}
+
+			appendServiceAccountToClusterConfig(cfg, serviceAccount)
+
+			rs := builder.NewIAMRoleResourceSetForServiceAccount(serviceAccount, oidc)
+
+			templateBody := []byte{}
+
+			Expect(rs).To(RenderWithoutErrors(&templateBody))
+
+			t := cft.NewTemplate()
+
+			Expect(t).To(LoadBytesWithoutErrors(templateBody))
+
+			Expect(t.Description).To(Equal("IAM role for serviceaccount \"default/sa-1\" [created and managed by eksctl]"))
+
+			Expect(t.Resources).To(HaveLen(1))
+			Expect(t.Outputs).To(HaveLen(1))
+
+			Expect(t).To(HaveResource(outputs.IAMServiceAccountRoleName, "AWS::IAM::Role"))
+
+			// Verify that the assume role policy uses StringLike for subject pattern
+			Expect(t).To(HaveResourceWithPropertyValue(outputs.IAMServiceAccountRoleName, "AssumeRolePolicyDocument", expectedServiceAccountAssumeRolePolicyDocumentWithWildcard))
+			Expect(t).To(HaveResourceWithPropertyValue(outputs.IAMServiceAccountRoleName, "ManagedPolicyArns", `[
+			"arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
+		]`))
+
+			Expect(t).To(HaveOutputWithValue(outputs.IAMServiceAccountRoleName, `{ "Fn::GetAtt": "Role1.Arn" }`))
+		})
+
 		It("can construct an iamserviceaccount addon template with all the wellKnownPolicies", func() {
 			serviceAccount := &api.ClusterIAMServiceAccount{}
 
@@ -450,6 +486,29 @@ const expectedServiceAccountAssumeRolePolicyDocument = `{
 	"Version": "2012-10-17"
 }`
 
+const expectedServiceAccountAssumeRolePolicyDocumentWithWildcard = `{
+	"Statement": [
+	  {
+		"Action": [
+		  "sts:AssumeRoleWithWebIdentity"
+		],
+		"Condition": {
+		  "StringEquals": {
+			"oidc.eks.us-west-2.amazonaws.com/id/A39A2842863C47208955D753DE205E6E:aud": "sts.amazonaws.com"
+		  },
+		  "StringLike": {
+			"oidc.eks.us-west-2.amazonaws.com/id/A39A2842863C47208955D753DE205E6E:sub": "system:serviceaccount:default:app-*"
+		  }
+		},
+		"Effect": "Allow",
+		"Principal": {
+		  "Federated": "arn:aws:iam::456123987123:oidc-provider/oidc.eks.us-west-2.amazonaws.com/id/A39A2842863C47208955D753DE205E6E"
+		}
+	  }
+	],
+	"Version": "2012-10-17"
+}`
+
 const expectedAssumeRolePolicyDocument = `{
 	"Statement": [
 	  {

pkg/ctl/cmdutils/configfile.go

@@ -868,6 +868,7 @@ func NewCreateIAMServiceAccountLoader(cmd *Cmd, saFilter *filter.IAMServiceAccou
 
 	l.flagsIncompatibleWithConfigFile.Insert(
 		"policy-arn",
+		"subject-pattern",
 	)
 
 	l.validateWithConfigFile = func() error {

pkg/ctl/cmdutils/configfile_test.go

@@ -649,6 +649,59 @@ var _ = Describe("cmdutils configfile", func() {
 		})
 	})
 
+	Describe("NewCreateIAMServiceAccountLoader", func() {
+		When("subject-pattern flag is used with config file", func() {
+			It("should return an error", func() {
+				cfg := api.NewClusterConfig()
+				cobraCmd := newCmd()
+				cobraCmd.Flags().String("subject-pattern", "", "")
+				cobraCmd.Flags().String("cluster", "", "")
+				Expect(cobraCmd.ParseFlags([]string{"--subject-pattern", "app-*"})).To(Succeed())
+
+				cmd := &Cmd{
+					ClusterConfig:     cfg,
+					CobraCommand:      cobraCmd,
+					ClusterConfigFile: examplesDir + "01-simple-cluster.yaml",
+					ProviderConfig:    api.ProviderConfig{},
+				}
+
+				err := NewCreateIAMServiceAccountLoader(cmd, filter.NewIAMServiceAccountFilter()).Load()
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(ContainSubstring("--subject-pattern"))
+				Expect(err.Error()).To(ContainSubstring("cannot use --subject-pattern when --config-file/-f is set"))
+			})
+		})
+
+		When("subject-pattern flag is used without config file", func() {
+			It("should succeed", func() {
+				cfg := api.NewClusterConfig()
+				cfg.Metadata.Name = "test-cluster"
+				serviceAccount := &api.ClusterIAMServiceAccount{
+					ClusterIAMMeta: api.ClusterIAMMeta{
+						Name:      "test-sa",
+						Namespace: "default",
+					},
+					AttachPolicyARNs: []string{"arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"},
+					SubjectPattern:   "app-*",
+				}
+				cfg.IAM.ServiceAccounts = []*api.ClusterIAMServiceAccount{serviceAccount}
+
+				cobraCmd := newCmd()
+				cobraCmd.Flags().String("cluster", "", "")
+				cobraCmd.Flags().String("subject-pattern", "", "")
+
+				cmd := &Cmd{
+					ClusterConfig:  cfg,
+					CobraCommand:   cobraCmd,
+					ProviderConfig: api.ProviderConfig{},
+				}
+
+				err := NewCreateIAMServiceAccountLoader(cmd, filter.NewIAMServiceAccountFilter()).Load()
+				Expect(err).NotTo(HaveOccurred())
+			})
+		})
+	})
+
 	Context("makeManagedNodegroup with node repair config", func() {
 		var (
 			ng      *api.NodeGroup

pkg/ctl/create/iamserviceaccount.go

@@ -57,6 +57,8 @@ func createIAMServiceAccountCmdWithRunFunc(cmd *cmdutils.Cmd, runFunc func(cmd *
 
 		fs.BoolVar(&overrideExistingServiceAccounts, "override-existing-serviceaccounts", false, "create IAM roles for existing serviceaccounts and update the serviceaccount")
 
+		fs.StringVar(&serviceAccount.SubjectPattern, "subject-pattern", "", "subject pattern to use in the trust policy (supports wildcards like '*' with StringLike condition)")
+
 		cmdutils.AddIAMServiceAccountFilterFlags(fs, &cmd.Include, &cmd.Exclude)
 		cmdutils.AddApproveFlag(fs, cmd)
 		cmdutils.AddRegionFlag(fs, &cmd.ProviderConfig)

pkg/ctl/create/iamserviceaccount_test.go

@@ -30,6 +30,28 @@ var _ = Describe("create iamserviceaccount", func() {
 		Entry("with optional flags", "--cluster", "clusterName", "--name", "serviceAccountName", "--attach-policy-arn", "dummyPolicyArn", "--override-existing-serviceaccounts", "--role-name", "custom-role-name"),
 	)
 
+	DescribeTable("create service account with subject pattern",
+		func(args ...string) {
+			commandArgs := append([]string{"iamserviceaccount"}, args...)
+			cmd := newMockEmptyCmd(commandArgs...)
+			count := 0
+			cmdutils.AddResourceCmd(cmdutils.NewGrouping(), cmd.parentCmd, func(cmd *cmdutils.Cmd) {
+				createIAMServiceAccountCmdWithRunFunc(cmd, func(cmd *cmdutils.Cmd, _, _ bool) error {
+					Expect(cmd.ClusterConfig.Metadata.Name).To(Equal("clusterName"))
+					Expect(cmd.ClusterConfig.IAM.ServiceAccounts[0].Name).To(Equal("serviceAccountName"))
+					Expect(cmd.ClusterConfig.IAM.ServiceAccounts[0].SubjectPattern).To(Equal("app-*"))
+					Expect(cmd.ClusterConfig.IAM.ServiceAccounts[0].AttachPolicyARNs).To(ContainElement("dummyPolicyArn"))
+					count++
+					return nil
+				})
+			})
+			_, err := cmd.execute()
+			Expect(err).To(Not(HaveOccurred()))
+			Expect(count).To(Equal(1))
+		},
+		Entry("with subject-pattern flag", "--cluster", "clusterName", "--name", "serviceAccountName", "--attach-policy-arn", "dummyPolicyArn", "--subject-pattern", "app-*"),
+	)
+
 	DescribeTable("invalid flags or arguments",
 		func(c invalidParamsCase) {
 			cmd := newDefaultCmd(c.args...)

pkg/iam/oidc/api.go

@@ -180,6 +180,21 @@ func (m *OpenIDConnectManager) MakeAssumeRolePolicyDocumentWithServiceAccountCon
 	})
 }
 
+// MakeAssumeRolePolicyDocumentWithServiceAccountConditionsAllowingWildcard constructs a trust policy document
+// that allows wildcard pattern matching in the subject condition. The subjectPattern should be in the format
+// "system:serviceaccount:namespace:name-pattern" where name-pattern can include wildcards like "*".
+func (m *OpenIDConnectManager) MakeAssumeRolePolicyDocumentWithServiceAccountConditionsAllowingWildcard(serviceAccountNamespace, subjectPattern string) cft.MapOfInterfaces {
+	subject := fmt.Sprintf("system:serviceaccount:%s:%s", serviceAccountNamespace, subjectPattern)
+	return cft.MakeAssumeRoleWithWebIdentityPolicyDocument(m.ProviderARN, cft.MapOfInterfaces{
+		"StringLike": map[string]string{
+			m.hostnameAndPath() + ":sub": subject,
+		},
+		"StringEquals": map[string]string{
+			m.hostnameAndPath() + ":aud": m.audience,
+		},
+	})
+}
+
 func (m *OpenIDConnectManager) MakeAssumeRolePolicyDocument() cft.MapOfInterfaces {
 	return cft.MakeAssumeRoleWithWebIdentityPolicyDocument(m.ProviderARN, cft.MapOfInterfaces{
 		"StringEquals": map[string]string{

userdocs/src/usage/iamserviceaccounts.md

@@ -91,6 +91,50 @@ To update a service accounts roles permissions you can run `eksctl update iamser
 ???+ note
     `eksctl delete iamserviceaccount` deletes Kubernetes `ServiceAccounts` even if they were not created by `eksctl`.
 
+#### Using wildcard patterns with `--subject-pattern`
+
+When you need to grant IAM permissions to multiple service accounts that follow a naming pattern, you can use the `--subject-pattern` flag to create an IAM role that trusts service accounts matching a wildcard pattern.
+
+This is useful for scenarios such as:
+- Multiple deployment replicas with dynamic service account names
+- Applications that create service accounts with predictable prefixes
+- Multi-tenant environments where service accounts share a naming convention
+
+When using `--subject-pattern`, the IAM trust policy will use the `StringLike` condition operator instead of `StringEquals`, allowing wildcards like `*` to match multiple service accounts:
+
+```console
+eksctl create iamserviceaccount \
+  --cluster=<clusterName> \
+  --name=<serviceAccountName> \
+  --namespace=<serviceAccountNamespace> \
+  --attach-policy-arn=<policyARN> \
+  --subject-pattern="app-*"
+```
+
+For example, to allow all service accounts starting with `app-` in the `default` namespace to assume the role:
+
+```console
+eksctl create iamserviceaccount \
+  --cluster=<clusterName> \
+  --name=app-base \
+  --namespace=default \
+  --attach-policy-arn=arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
+  --subject-pattern="app-*"
+```
+
+This creates an IAM trust policy condition like:
+
+```json
+"StringLike": {
+  "oidc.eks.region.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E:sub": "system:serviceaccount:default:app-*"
+}
+```
+
+???+ warning "Security Considerations"
+    Use wildcard patterns carefully. A broad pattern like `*` would allow any service account in the namespace to assume the IAM role. Always use the most restrictive pattern possible for your use case.
+
+The Subject Pattern property can be defined in the configuration file.
+
 ### Usage with config files
 
 To manage `iamserviceaccounts` using config file, you will be looking to set `iam.withOIDC: true` and list account you want under `iam.serviceAccount`.
@@ -140,6 +184,7 @@ iam:
     tags:
       Owner: "John Doe"
       Team: "Some Team"
+    subjectPattern: "app-*"
   - metadata:
       name: cache-access
       namespace: backend-apps