[FEATURE | API DESIGN] Use nested structure for ModelConfig ApiKey CRD

[inFocus7]

📋 Prerequisites

• I have searched the existing issues to avoid creating a duplicate
• By submitting this issue, you agree to follow our Code of Conduct

📝 Feature Summary

Update the CRD for ModelConfig to nest the ApiKey Secret

❓ Problem Statement / Motivation

We have implemented a new secret ref for ModelConfigs - TLS CA certs, which follow a nested approach modelconfig.spec.tls.(secret). Setting up a api key which also is a secret follows a different approach modelconfig.spec.(secret).

For anyone new to kagent this could be confusing and easy to forget that both follow different structure to set their secrets. We should match their definitions to avoid confusion.

💡 Proposed Solution

Update ModelConfig CRD from:

spec:
  apiKeySecret: xyz
  apiKeySecretKey: xyz

to

spec:
  apiKey:
    secretRef: xyz
    secretKey: xyz

Then:

1. Mark existing apiKey config as deprecated.
2. During translation use the new setup, falling back to old if unset.
3. If the user is using old ModelConfig, log a warning.

🔄 Alternatives Considered

No response

🎯 Affected Service(s)

None

📚 Additional Context

This would be a breaking change, but we can mark the existing CRD fields as Deprecated (with a planned removal) and log so that users know to move to new definition.

While we may want to avoid breaking changes (although technically not breaking if we deprecate it first), it's better to get this in sooner so less users are impacted as the userbase grows.

🙋 Are you willing to contribute?

• I am willing to submit a PR for this feature