feat(mcpserver): add ServiceAccount annotations and labels support (#95)

# Add ServiceAccount customization support for MCPServer

## Overview
This PR adds support for customizing ServiceAccount annotations and
labels in MCPServer resources, enabling cloud provider integrations such
as AWS IRSA (IAM Roles for Service Accounts).

## Motivation
Currently, MCPServers create ServiceAccounts with only basic metadata.
To enable cloud provider integrations (AWS IRSA, GCP Workload Identity,
Azure Managed Identity), users need the ability to add custom
annotations and labels to these ServiceAccounts.

## Changes

### 1. API Changes (`api/v1alpha1/mcpserver_types.go`)
- Added `ServiceAccountConfig` type with:
- `Annotations map[string]string` - for cloud provider annotations
(e.g., AWS IRSA role ARN)
- `Labels map[string]string` - for resource organization and policy
enforcement
- Added `ServiceAccount *ServiceAccountConfig` field to
`MCPServerDeployment`
- Comprehensive documentation with examples

### 2. Controller Changes
(`pkg/controller/transportadapter/transportadapter_translator.go`)
- Modified `translateTransportAdapterServiceAccount()` to apply custom
annotations and labels
- Maintains backward compatibility (defaults when not specified)

### 3. CRD Updates
- Generated updated CRD with new fields and validation
- Updated deepcopy code

### 4. Documentation
- Added example file:
`config/samples/mcpserver-serviceaccount-irsa.yaml`
- Shows complete AWS IRSA configuration example

## Use Cases

### AWS IRSA (IAM Roles for Service Accounts)
```yaml
spec:
  deployment:
    serviceAccount:
      annotations:
        eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/my-role"
        eks.amazonaws.com/sts-regional-endpoints: "true"
      labels:
        team: platform
        environment: production
```

Enables MCPServer pods to:
- Access AWS services (S3, DynamoDB, Secrets Manager, etc.) without
managing credentials
- Use temporary IAM credentials automatically refreshed by AWS
- Follow AWS security best practices (no long-lived credentials)

## Backward Compatibility
✅ **Fully backward compatible**:
- All new fields are optional (`omitempty`)
- Existing MCPServer resources continue working unchanged
- Default behavior preserved when fields not specified

## Testing
- [x] Code compiles successfully
- [x] `make generate` updates deepcopy code
- [x] `make manifests` generates valid CRDs
- [x] `make test` passes all unit tests
- [x] Example manifest validates configuration

## Checklist
- [x] API changes documented with clear comments
- [x] Controller implementation tested
- [x] CRDs regenerated
- [x] Example file provided
- [x] Backward compatibility maintained
- [x] Commit signed with DCO

## Migration Notes
No migration required. This is an additive change that does not affect
existing MCPServer resources.

Signed-off-by: skhedim <sebastien.khedim@gmail.com>
Signed-off-by: sebastien_khedim <Sebastien_KHEDIM@ext.connect-tech.sncf>

Author: skhedim

api/v1alpha1/mcpserver_types.go

@@ -236,6 +236,10 @@ type MCPServerDeployment struct {
 	// the transport adapter binary. This is used for stdio transport type.
 	// +optional
 	InitContainer *InitContainerConfig `json:"initContainer,omitempty"`
+
+	// ServiceAccount defines the configuration for the ServiceAccount.
+	// +optional
+	ServiceAccount *ServiceAccountConfig `json:"serviceAccount,omitempty"`
 }
 
 // InitContainerConfig defines the configuration for the init container.
@@ -252,6 +256,20 @@ type InitContainerConfig struct {
 	ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`
 }
 
+// ServiceAccountConfig defines the configuration for the ServiceAccount.
+type ServiceAccountConfig struct {
+	// Annotations to add to the ServiceAccount.
+	// This is useful for configuring AWS IRSA (IAM Roles for Service Accounts)
+	// or other cloud provider integrations.
+	// Example: {"eks.amazonaws.com/role-arn": "arn:aws:iam::123456789012:role/my-role"}
+	// +optional
+	Annotations map[string]string `json:"annotations,omitempty"`
+
+	// Labels to add to the ServiceAccount.
+	// +optional
+	Labels map[string]string `json:"labels,omitempty"`
+}
+
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:shortName=mcps;mcp

api/v1alpha1/zz_generated.deepcopy.go

@@ -138,6 +138,25 @@ spec:
                       type: object
                       x-kubernetes-map-type: atomic
                     type: array
+                  serviceAccount:
+                    description: ServiceAccount defines the configuration for the
+                      ServiceAccount.
+                    properties:
+                      annotations:
+                        additionalProperties:
+                          type: string
+                        description: |-
+                          Annotations to add to the ServiceAccount.
+                          This is useful for configuring AWS IRSA (IAM Roles for Service Accounts)
+                          or other cloud provider integrations.
+                          Example: {"eks.amazonaws.com/role-arn": "arn:aws:iam::123456789012:role/my-role"}
+                        type: object
+                      labels:
+                        additionalProperties:
+                          type: string
+                        description: Labels to add to the ServiceAccount.
+                        type: object
+                    type: object
                   volumeMounts:
                     description: |-
                       VolumeMounts defines the list of volume mounts for the MCP server container.

config/crd/bases/kagent.dev_mcpservers.yaml

@@ -0,0 +1,35 @@
+---
+# Example MCPServer with ServiceAccount configuration for AWS IRSA
+# This demonstrates how to configure annotations and labels on the
+# ServiceAccount created by the MCPServer controller.
+#
+# Use case: AWS IRSA (IAM Roles for Service Accounts) authentication
+# The eks.amazonaws.com/role-arn annotation allows pods using this
+# ServiceAccount to assume an IAM role without requiring AWS credentials.
+apiVersion: kagent.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: mcpserver-irsa-example
+  namespace: default
+spec:
+  deployment:
+    image: ghcr.io/modelcontextprotocol/servers/filesystem:latest
+    port: 3000
+    cmd: /usr/local/bin/mcp-server-filesystem
+    args:
+      - /data
+    # ServiceAccount configuration for AWS IRSA
+    serviceAccount:
+      annotations:
+        # AWS IRSA annotation - replace with your IAM role ARN
+        eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/my-mcp-server-role"
+        # Optional: use regional STS endpoints
+        eks.amazonaws.com/sts-regional-endpoints: "true"
+      labels:
+        # Custom labels for organization and policy enforcement
+        team: platform
+        component: mcp-server
+        environment: production
+        managed-by: kmcp
+  transportType: stdio
+  stdioTransport: {}

config/samples/mcpserver-serviceaccount-irsa.yaml

@@ -286,15 +286,27 @@ func (t *transportAdapterTranslator) addMCPServerConfigHashAnnotation(
 func (t *transportAdapterTranslator) translateTransportAdapterServiceAccount(
 	server *v1alpha1.MCPServer,
 ) (*corev1.ServiceAccount, error) {
+	objectMeta := metav1.ObjectMeta{
+		Name:      server.Name,
+		Namespace: server.Namespace,
+	}
+
+	// Apply custom annotations and labels if provided
+	if server.Spec.Deployment.ServiceAccount != nil {
+		if server.Spec.Deployment.ServiceAccount.Annotations != nil {
+			objectMeta.Annotations = server.Spec.Deployment.ServiceAccount.Annotations
+		}
+		if server.Spec.Deployment.ServiceAccount.Labels != nil {
+			objectMeta.Labels = server.Spec.Deployment.ServiceAccount.Labels
+		}
+	}
+
 	serviceAccount := &corev1.ServiceAccount{
 		TypeMeta: metav1.TypeMeta{
 			Kind:       "ServiceAccount",
 			APIVersion: corev1.SchemeGroupVersion.String(),
 		},
-		ObjectMeta: metav1.ObjectMeta{
-			Name:      server.Name,
-			Namespace: server.Namespace,
-		},
+		ObjectMeta: objectMeta,
 	}
 	return serviceAccount, controllerutil.SetOwnerReference(server, serviceAccount, t.scheme)
 }