From 05495df87fffba337b0bb3d8688852e0b4dcc3a6 Mon Sep 17 00:00:00 2001 From: artberger <20074219+artberger@users.noreply.github.com> Date: Tue, 11 Aug 2026 06:48:32 +0000 Subject: [PATCH] docs: Update kagent and kmcp API reference docs Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs-site/content/kagent/resources/api-ref.md | 22 +++++++++++++++++-- docs-site/content/kagent/resources/helm.md | 16 ++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/docs-site/content/kagent/resources/api-ref.md b/docs-site/content/kagent/resources/api-ref.md index 5c65f6a3..f4eb0bfd 100644 --- a/docs-site/content/kagent/resources/api-ref.md +++ b/docs-site/content/kagent/resources/api-ref.md @@ -333,7 +333,7 @@ _Appears in:_ | `documentationUrl` _string_ | DocumentationURL is a URL to human-readable documentation for the agent. It
is surfaced on the agent's A2A AgentCard. | | Format: uri
| | `version` _string_ | Version is the agent's version string, surfaced on the A2A AgentCard. | | | | `provider` _[AgentProvider](#agentprovider)_ | Provider identifies the organization responsible for the agent. It is
surfaced on the agent's A2A AgentCard. | | | -| `skills` _[SkillForAgent](#skillforagent)_ | Skills to load into the agent. They will be pulled from the specified container images.
and made available to the agent under the `/skills` folder. | | | +| `skills` _[SkillForAgent](#skillforagent)_ | Skills to load into the agent. They will be pulled from OCI images, git repos,
and/or S3, and made available to the agent under the `/skills` folder. | | | | `sandbox` _[SandboxConfig](#sandboxconfig)_ | Sandbox configures sandboxed execution behavior shared across runtimes.
This is intended for sandboxed declarative execution today, and can also
be consumed by BYO agents. | | | | `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this Agent as a tool.
This field only applies when this Agent is used as a tool by another Agent.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | | | @@ -1046,6 +1046,23 @@ _Appears in:_ | `discoveredTools` _[MCPTool](#mcptool) array_ | | | | | `secretHash` _string_ | SecretHash stores a hash of the TLS Secret referenced by spec.tls so
agents that consume this RemoteMCPServer can detect cert rotation and
roll on the next reconcile. Empty when spec.tls.caCertSecretRef is unset. | | | +#### S3SkillRef + +S3SkillRef specifies a skill bundle in an S3 bucket. + +Two bundle shapes are supported: + - Prefix: s3://bucket/path/to/skill/ containing SKILL.md (and siblings); synced recursively + - Archive: a single .zip / .tgz / .tar.gz object; downloaded and extracted + +_Appears in:_ +- [SkillForAgent](#skillforagent) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `uri` _string_ | S3 URI of the skill: s3://bucket/key-or-prefix | | MinLength: 1
Pattern: `^s3://.+`
| +| `region` _string_ | AWS region for the bucket. Optional when AWS_REGION / AWS_DEFAULT_REGION is set
on the skills-init container (e.g. via initContainer.env). | | | +| `name` _string_ | Name for the skill directory under /skills. If omitted, defaults to the last
non-empty path segment of the URI (archive extension stripped). | | | + #### SAPAICoreConfig SAPAICoreConfig contains SAP AI Core-specific configuration options. @@ -1088,7 +1105,7 @@ _Appears in:_ | `documentationUrl` _string_ | DocumentationURL is a URL to human-readable documentation for the agent. It
is surfaced on the agent's A2A AgentCard. | | Format: uri
| | `version` _string_ | Version is the agent's version string, surfaced on the A2A AgentCard. | | | | `provider` _[AgentProvider](#agentprovider)_ | Provider identifies the organization responsible for the agent. It is
surfaced on the agent's A2A AgentCard. | | | -| `skills` _[SkillForAgent](#skillforagent)_ | Skills to load into the agent. They will be pulled from the specified container images.
and made available to the agent under the `/skills` folder. | | | +| `skills` _[SkillForAgent](#skillforagent)_ | Skills to load into the agent. They will be pulled from OCI images, git repos,
and/or S3, and made available to the agent under the `/skills` folder. | | | | `sandbox` _[SandboxConfig](#sandboxconfig)_ | Sandbox configures sandboxed execution behavior shared across runtimes.
This is intended for sandboxed declarative execution today, and can also
be consumed by BYO agents. | | | | `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this Agent as a tool.
This field only applies when this Agent is used as a tool by another Agent.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | | | | `substrate` _[SandboxSubstrateSpec](#sandboxsubstratespec)_ | Substrate is optional Agent Substrate-specific settings. | | | @@ -1184,6 +1201,7 @@ _Appears in:_ | `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | ImagePullSecrets is a list of references to secrets in the same namespace to use for
pulling skill images from private registries. Each referenced secret must be of type
kubernetes.io/dockerconfigjson. The credentials from all secrets are merged and made
available to the skills-init container at /.kagent/.docker/config.json; krane will
use them automatically when pulling images. | | MaxItems: 20
| | `gitAuthSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core)_ | Reference to a Secret containing git credentials.
Applied to all gitRefs entries.
The secret should contain a `token` key for HTTPS auth,
or `ssh-privatekey` for SSH auth. | | | | `gitRefs` _[GitRepo](#gitrepo) array_ | Git repositories to fetch skills from. | | MaxItems: 20
MinItems: 1
| +| `s3Refs` _[S3SkillRef](#s3skillref) array_ | S3 object prefixes or archives to fetch skills from.
Auth uses the AWS SDK default credential chain (typically static keys via
skills.initContainer.env: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION). | | MaxItems: 20
MinItems: 1
| | `initContainer` _[SkillsInitContainer](#skillsinitcontainer)_ | Configuration for the skills-init init container. | | | #### SkillsInitContainer diff --git a/docs-site/content/kagent/resources/helm.md b/docs-site/content/kagent/resources/helm.md index 822f3d57..e3198127 100644 --- a/docs-site/content/kagent/resources/helm.md +++ b/docs-site/content/kagent/resources/helm.md @@ -93,6 +93,13 @@ A Helm chart for kagent, built with Google ADK | controller.mcpEgressPlaintext | bool | `false` | Rewrite RemoteMCPServer tool URLs and the controller's tool-discovery dial from `https://host[:port]` to `http://host:` so MCP traffic egresses in plaintext to a proxy that originates TLS upstream off by default. | | controller.metrics | object | disabled | Prometheus-style /metrics endpoint for the controller manager. When enabled, provisions a dedicated metrics Service plus the ClusterRoles required for authenticated scrapes. Bind `-metrics-reader` to your Prometheus ServiceAccount to grant scrape access. Use `bindAddress` for any port change: the Service `targetPort` and the pod `containerPort` are derived from it at template time, so overriding `METRICS_BIND_ADDRESS` via `controller.env` shifts only the runtime listener and leaves the rendered Service pointing at the chart-time port. Setting `bindAddress: "0"` (or empty) is treated as a disable signal — equivalent to `enabled: false` — to keep faith with the controller binary's documented contract for `--metrics-bind-address`. | | controller.nodeSelector | object | `{}` | Node labels to match for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). | +| controller.pdb | object | `{"annotations":{},"enabled":false,"labels":{},"maxUnavailable":1,"minAvailable":null,"unhealthyPodEvictionPolicy":""}` | [PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the controller pods. Disabled by default: `controller.replicas` is 1, and a `minAvailable: 1` budget on a single-replica Deployment blocks every voluntary eviction, so node drains and cluster upgrades hang indefinitely. Raise `controller.replicas` before switching to `minAvailable`. | +| controller.pdb.annotations | object | `{}` | Annotations for the controller PodDisruptionBudget. | +| controller.pdb.enabled | bool | `false` | Set to true to create the PodDisruptionBudget. | +| controller.pdb.labels | object | `{}` | Additional labels for the controller PodDisruptionBudget. | +| controller.pdb.maxUnavailable | int | `1` | Maximum number of pods that may be unavailable. Int or percentage string (e.g. `1` or `"50%"`). Mutually exclusive with `minAvailable`. | +| controller.pdb.minAvailable | string | unset (`maxUnavailable` is used instead) | Minimum number of pods that must remain available. Int or percentage string (e.g. `1` or `"50%"`). Mutually exclusive with `maxUnavailable`. | +| controller.pdb.unhealthyPodEvictionPolicy | string | "" (defer to the Kubernetes default) | `spec.unhealthyPodEvictionPolicy`, one of `IfHealthyBudget` (the Kubernetes default) or `AlwaysAllow`. `AlwaysAllow` lets unhealthy pods be evicted even when the budget is exhausted, which avoids drains wedging on a crash-looping pod. Requires Kubernetes >= 1.27. Omitted from the manifest when empty. | | controller.podAnnotations | object | `{}` | | | controller.podLabels | object | `{}` | Additional labels for the controller pod template, merged over the global `podLabels` (per-key; component keys win). Selector labels can never be overridden. | | controller.readinessProbe | object | httpGet /health on port http, periodSeconds=30 | Custom readiness probe for the controller container. Setting a value replaces the default probe entirely — include a handler (httpGet / exec / tcpSocket / grpc) when overriding. | @@ -138,6 +145,8 @@ A Helm chart for kagent, built with Google ADK | database.postgres.bundled.securityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]}}` | Container-level security context for the bundled PostgreSQL container. | | database.postgres.bundled.storage | string | `"500Mi"` | PersistentVolumeClaim size for demo PostgreSQL data | | database.postgres.bundled.storageClassName | string | `""` | StorageClass for the PostgreSQL PVC. Defaults to the cluster default when empty. | +| database.postgres.pool | object | `{"maxConnIdleTime":"","maxConnLifetime":"","maxConns":null,"minConns":null}` | Optional pgxpool settings. Leave unset/null to keep pgx library defaults (MaxConns≈max(4,NumCPU), MinConns=0, MaxConnIdleTime=30m, MaxConnLifetime=1h). | +| database.postgres.sessionRetentionDays | int | `0` | Hard-delete idle sessions (and cascaded events/tasks/checkpoints/shares) after N days of no activity. Uses session.updated_at as a sliding idle clock (writes refresh it). 0 disables cleanup (default, existing installs unchanged). | | database.postgres.skipMigrations | bool | `false` | Skip running database migrations at controller startup. The controller instead verifies the database is already migrated and fails if it is not. Migrations must be applied out-of-band (e.g. from a CI/CD pipeline) before install/upgrade. | | database.postgres.url | string | `""` | External PostgreSQL connection string. Is always used if set regardless of the `.bundled.enabled` field. | | database.postgres.urlFile | string | `""` | Path to a file containing the database URL. Takes precedence over url when set. Is always used if set regardless of the `.bundled.enabled` field. | @@ -338,6 +347,13 @@ A Helm chart for kagent, built with Google ADK | ui.nginx.proxySendTimeout | string | `"1800s"` | proxy_send_timeout: max time between two successive writes to the upstream. | | ui.nodeSelector | object | `{}` | Node labels to match for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). | | ui.openshiftRoute.annotations."haproxy.router.openshift.io/timeout" | string | `"120m"` | | +| ui.pdb | object | `{"annotations":{},"enabled":false,"labels":{},"maxUnavailable":1,"minAvailable":null,"unhealthyPodEvictionPolicy":""}` | [PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the UI pods. Disabled by default: `ui.replicas` is 1, and a `minAvailable: 1` budget on a single-replica Deployment blocks every voluntary eviction, so node drains and cluster upgrades hang indefinitely. Raise `ui.replicas` before switching to `minAvailable`. | +| ui.pdb.annotations | object | `{}` | Annotations for the UI PodDisruptionBudget. | +| ui.pdb.enabled | bool | `false` | Set to true to create the PodDisruptionBudget. | +| ui.pdb.labels | object | `{}` | Additional labels for the UI PodDisruptionBudget. | +| ui.pdb.maxUnavailable | int | `1` | Maximum number of pods that may be unavailable. Int or percentage string (e.g. `1` or `"50%"`). Mutually exclusive with `minAvailable`. | +| ui.pdb.minAvailable | string | unset (`maxUnavailable` is used instead) | Minimum number of pods that must remain available. Int or percentage string (e.g. `1` or `"50%"`). Mutually exclusive with `maxUnavailable`. | +| ui.pdb.unhealthyPodEvictionPolicy | string | "" (defer to the Kubernetes default) | `spec.unhealthyPodEvictionPolicy`, one of `IfHealthyBudget` (the Kubernetes default) or `AlwaysAllow`. `AlwaysAllow` lets unhealthy pods be evicted even when the budget is exhausted, which avoids drains wedging on a crash-looping pod. Requires Kubernetes >= 1.27. Omitted from the manifest when empty. | | ui.podAnnotations | object | `{}` | | | ui.podLabels | object | `{}` | Additional labels for the UI pod template, merged over the global `podLabels` (per-key; component keys win). Selector labels can never be overridden. | | ui.podSecurityContext | object | (uses global podSecurityContext) | Pod-level security context for the UI pod. Overrides the global podSecurityContext. |