Description

This PR adds support for customizing the init container image in MCPServer resources, allowing users to specify a custom registry or image for the transport adapter init container.

Motivation

Currently, the init container image for stdio transport type is hardcoded to ghcr.io/agentgateway/agentgateway:0.9.0-musl. This creates challenges for:

• Air-gapped environments: Organizations that cannot directly access public registries like ghcr.io
• Private registries: Teams that mirror images to their internal registries for security/compliance
• Registry proxies: Environments that route all container image pulls through a proxy registry
• Custom builds: Developers testing custom transport adapter builds

Changes

API Changes

Added an optional initContainer field to MCPServerDeployment:

type InitContainerConfig struct {
    // Image defines the full image reference for the init container
    Image string `json:"image,omitempty"`
    
    // ImagePullPolicy defines the pull policy for the init container image
    ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`
}

Behavior

• If spec.deployment.initContainer.image is specified, it overrides the default image
• If not specified, falls back to the default transport adapter image (backward compatible)
• imagePullPolicy defaults to IfNotPresent if not specified

Example Usage

apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
  name: my-mcp-server
spec:
  transportType: stdio
  deployment:
    image: python:3.12-slim
    cmd: python
    args: ["-m", "http.server"]
    
    # Override init container image
    initContainer:
      image: myregistry.com/agentgateway/agentgateway:0.9.0-musl
      imagePullPolicy: IfNotPresent

Files Modified

• go/api/v1alpha1/mcpserver_types.go - Added InitContainerConfig type
• go/internal/controller/translator/mcp/translator_adapter.go - Updated translator logic
• helm/kagent-crds/templates/kagent.dev_mcpservers.yaml - Generated CRD
• go/config/crd/bases/kagent.dev_mcpservers.yaml - Generated base CRD
• contrib/tools/mcpserver-custom-registry-example.yaml - Example usage

Testing

Manual Testing

# Apply the updated CRD
kubectl apply -f helm/kagent-crds/templates/kagent.dev_mcpservers.yaml

# Create a test MCPServer with custom registry
kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
  name: test-custom-registry
  namespace: kagent
spec:
  transportType: stdio
  deployment:
    image: python:3.12-slim
    cmd: python
    args: ["-m", "http.server"]
    initContainer:
      image: myregistry.com/agentgateway/agentgateway:0.9.0-musl
      imagePullPolicy: IfNotPresent
EOF

# Verify the init container uses the custom image
kubectl get deployment test-custom-registry -n kagent \
  -o jsonpath='{.spec.template.spec.initContainers[0].image}'

Expected output: myregistry.com/agentgateway/agentgateway:0.9.0-musl

Backward Compatibility

Existing MCPServer resources without the initContainer field continue to work as before:

# Create MCPServer without initContainer field
kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
  name: test-default
  namespace: kagent
spec:
  transportType: stdio
  deployment:
    image: python:3.12-slim
    cmd: python
    args: ["-m", "http.server"]
EOF

# Verify it uses the default image
kubectl get deployment test-default -n kagent \
  -o jsonpath='{.spec.template.spec.initContainers[0].image}'

Expected output: ghcr.io/agentgateway/agentgateway:0.9.0-musl

Checklist

• Code follows the project's coding standards
• Changes are backward compatible
• CRD and generated code updated (make generate manifests)
• Example usage provided
• Commit message follows conventional commits
• All tests pass locally (go build ./...)

Related Issues

Closes #[issue-number] (if applicable)

Additional Notes

This change only affects MCPServer resources with transportType: stdio. HTTP transport type servers do not use an init container and are not affected by this change.