diff --git a/docs-site/content/kagent/main/operations/upgrade-from-0x.md b/docs-site/content/kagent/main/operations/upgrade-from-0x.md index fb6cd5bc..1abfee65 100644 --- a/docs-site/content/kagent/main/operations/upgrade-from-0x.md +++ b/docs-site/content/kagent/main/operations/upgrade-from-0x.md @@ -175,7 +175,7 @@ ModelConfig and RemoteMCPServer keep most of the fields that `v1alpha2` sets. `v kagent 1.0 cannot pass a mounted credential or certificate file to an agent. In place of `tokenExchange`, use an endpoint that accepts a static API key. For what to use in place of a custom certificate authority bundle, see [Credentials that kagent rejects]({{< link path="setup/model-providers/about-model-providers#credentials-that-kagent-rejects" >}}). -`v1alpha3` reshapes ModelProviderConfig. Model discovery accepts only the `OpenAI` type, which covers any OpenAI-compatible endpoint. A ModelProviderConfig of another type does not have a `v1alpha3` equivalent. The `spec.secretRef` field moves to `spec.discoveryAuth.secretRef`, which references both the Secret and the key within it. kagent uses that credential only to list models, never to invoke them. +{{< version include-if="latest,0.x" >}}`v1alpha3` reshapes ModelProviderConfig. Model discovery accepts only the `OpenAI` type, which covers any OpenAI-compatible endpoint. A ModelProviderConfig of another type does not have a `v1alpha3` equivalent. The `spec.secretRef` field moves to `spec.discoveryAuth.secretRef`, which references both the Secret and the key within it. kagent uses that credential only to list models, never to invoke them.{{< /version >}}{{< version exclude-if="latest,0.x" >}}`v1alpha3` reshapes ModelProviderConfig. Model discovery accepts only the `OpenAI` type, which covers any OpenAI-compatible endpoint. A ModelProviderConfig of another type does not have a `v1alpha3` equivalent. The `spec.secretRef` field becomes two explicit credential settings. The `spec.discoveryAuth.secretRef` field authenticates model discovery. The `spec.modelConfigTemplate.auth.secretRef` field sets invocation credentials on the ModelConfigs that discovery creates. Generated ModelConfigs do not inherit discovery credentials for invocation.{{< /version >}} 1. Recreate the Secrets that your ModelConfigs reference. Without them, the ModelConfigs cannot resolve their API keys. ```bash @@ -187,8 +187,9 @@ kagent 1.0 cannot pass a mounted credential or certificate file to an agent. In - Renames the `apiKeyPassthrough` field to `tokenPassthrough`. - Deletes the ModelConfig fields that `v1alpha3` removed. - Removes the metadata that the 0.10.x API server set. - - Moves the ModelProviderConfig Secret name to `spec.discoveryAuth.secretRef`, with a `` placeholder for the key. + {{< version include-if="latest,0.x" >}}- Moves the ModelProviderConfig Secret name to `spec.discoveryAuth.secretRef`, with a `` placeholder for the key.{{< /version >}}{{< version exclude-if="latest,0.x" >}}- Moves the ModelProviderConfig Secret name to `spec.discoveryAuth.secretRef` and `spec.modelConfigTemplate.auth.secretRef`. Adds `` placeholders for both keys.{{< /version >}} - Drops the `kagent-grafana-mcp` RemoteMCPServer, because 1.0 does not deploy the Grafana Model Context Protocol (MCP) server behind it. + {{< version include-if="latest,0.x" >}} ```bash yq '.items |= map(select(.kind == "ModelConfig" or .kind == "RemoteMCPServer" or (.kind == "ModelProviderConfig" and .spec.type == "OpenAI"))) | .items[].apiVersion = "api.kagent.dev/v1alpha3" @@ -199,8 +200,20 @@ kagent 1.0 cannot pass a mounted credential or certificate file to an agent. In | (.items[] | select(.kind == "ModelProviderConfig" and (.spec | has("secretRef"))) | .spec) |= (.discoveryAuth.secretRef = {"name": .secretRef.name, "key": ""} | del(.secretRef))' \ kagent-0.10-resources.yaml > kagent-1.0-resources.yaml ``` + {{< /version >}}{{< version exclude-if="latest,0.x" >}} + ```bash + yq '.items |= map(select(.kind == "ModelConfig" or .kind == "RemoteMCPServer" or (.kind == "ModelProviderConfig" and .spec.type == "OpenAI"))) + | .items[].apiVersion = "api.kagent.dev/v1alpha3" + | del(.items[].status, .items[].metadata.resourceVersion, .items[].metadata.uid, .items[].metadata.creationTimestamp, .items[].metadata.generation, .items[].metadata.managedFields, .items[].metadata.annotations["kubectl.kubernetes.io/last-applied-configuration"]) + | (.items[] | select(.kind == "ModelConfig" and has("spec") and (.spec | has("apiKeyPassthrough"))) | .spec) |= (.tokenPassthrough = .apiKeyPassthrough | del(.apiKeyPassthrough)) + | del(.items[] | select(.kind == "ModelConfig") | (.spec.openAI.tokenExchange, .spec.tls.caCertSecretRef, .spec.tls.caCertSecretKey, .spec.tls.disableSystemCAs)) + | del(.items[] | select(.kind == "RemoteMCPServer" and .metadata.name == "kagent-grafana-mcp")) + | (.items[] | select(.kind == "ModelProviderConfig" and (.spec | has("secretRef"))) | .spec) |= (.discoveryAuth.secretRef = {"name": .secretRef.name, "key": ""} | .modelConfigTemplate.auth.secretRef = {"name": .secretRef.name, "key": ""} | del(.secretRef))' \ + kagent-0.10-resources.yaml > kagent-1.0-resources.yaml + ``` + {{< /version >}} -3. If the converted file includes a ModelProviderConfig with a `` placeholder, replace the placeholder with the key that contains the API key. A 0.10.x discovery Secret contains exactly one key. To find the key, list the keys of the Secret that `discoveryAuth.secretRef.name` references. +{{< version include-if="latest,0.x" >}}3. If the converted file includes a ModelProviderConfig with a `` placeholder, replace the placeholder with the key that contains the API key. A 0.10.x discovery Secret contains exactly one key. To find the key, list the keys of the Secret that `discoveryAuth.secretRef.name` references.{{< /version >}}{{< version exclude-if="latest,0.x" >}}3. If the converted file includes a ModelProviderConfig with `` placeholders, replace both placeholders with the key that contains the API key. A 0.10.x discovery Secret contains exactly one key. List the keys of the Secret that `discoveryAuth.secretRef.name` references.{{< /version >}} ```bash kubectl get secret -n -o go-template='{{range $k, $v := .data}}{{$k}}{{"\n"}}{{end}}' ``` diff --git a/docs-site/content/kagent/main/setup/model-providers/about-model-providers.md b/docs-site/content/kagent/main/setup/model-providers/about-model-providers.md index 76d453a3..d98be961 100644 --- a/docs-site/content/kagent/main/setup/model-providers/about-model-providers.md +++ b/docs-site/content/kagent/main/setup/model-providers/about-model-providers.md @@ -137,6 +137,46 @@ Neither `codex` nor `claude` accepts a ModelConfig that sets `defaultHeaders`, ` For the full matrix, including the per-combination restrictions, see [Agent harness]({{< link path="agents/agent-harness#model-provider-support" >}}). +{{< version exclude-if="latest,0.x" >}} +## Discover models from a provider {#discover-models-from-a-provider} + +A ModelProviderConfig discovers model IDs from an OpenAI-compatible endpoint and creates ModelConfigs in the ModelProviderConfig namespace. Discovery credentials are separate from invocation credentials. The generated ModelConfigs do not inherit the Secret that lists models. + +```yaml +apiVersion: api.kagent.dev/v1alpha3 +kind: ModelProviderConfig +metadata: + name: llm-gateway + namespace: kagent +spec: + type: OpenAI + endpoint: https://llm-gateway.example.com/v1 + discoveryAuth: + secretRef: + name: discovery-token + key: token + modelConfigTemplate: + auth: + secretRef: + name: invocation-token + key: token + allowedNamespaces: + from: Same +``` + +Use these fields to control discovery and the generated ModelConfigs. + +| Field | Description | +| ----- | ----------- | +| `type` | The discovery protocol. Only `OpenAI` is accepted. Use this value for any OpenAI-compatible endpoint. | +| `endpoint` | Optional. The endpoint for model discovery. The URL must start with `http://` or `https://`. The URL can include a path such as `/v1`, and cannot include user information or query parameters. | +| `discoveryAuth.secretRef` | Optional. The Secret and key for the bearer token that kagent uses to list models. If you set `discoveryAuth`, both `name` and `key` are required. The `optional` field cannot be `true`. Omit `discoveryAuth` for unauthenticated discovery. | +| `modelConfigTemplate.auth` | Optional. The invocation credentials for generated ModelConfigs. Set at most one of `actorJwt`, `secretRef`, and `tokenPassthrough`. Discovery credentials are not inherited. | +| `modelConfigTemplate.allowedNamespaces` | Optional. The namespaces that can reference generated ModelConfigs and their invocation credentials. The default admits only the ModelProviderConfig namespace. | + +ModelProviderConfig status reports conditions, observed generation, and model count. It does not store the model inventory, the last discovery time, or Secret hashes. Refresh model discovery to list the provider's models. +{{< /version >}} + ## Use a ModelConfig Reference the ModelConfig by name in an AgentTemplate. When the reference omits `namespace`, kagent looks up the ModelConfig in the AgentTemplate's namespace. To use a ModelConfig from another namespace, see [Share a ModelConfig across namespaces](#share-a-modelconfig-across-namespaces).