From 05a7533f7faa611ea3ecf7dd58afecc7ae53984c Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 29 Apr 2026 09:34:42 -0400 Subject: [PATCH 1/2] v0.9 doc updates for bedrock embeddings, gorm, and rbac Signed-off-by: Art Berger --- .../kagent/concepts/agent-memory/page.mdx | 36 +++++++++++++ .../examples/human-in-the-loop/page.mdx | 4 +- src/app/docs/kagent/examples/skills/page.mdx | 2 +- .../operational-considerations/page.mdx | 40 +++++++++------ .../docs/kagent/operations/upgrade/page.mdx | 2 +- .../kagent/resources/release-notes/page.mdx | 50 +++++++++++++++++-- 6 files changed, 110 insertions(+), 24 deletions(-) diff --git a/src/app/docs/kagent/concepts/agent-memory/page.mdx b/src/app/docs/kagent/concepts/agent-memory/page.mdx index ddc5bc29..4b809afe 100644 --- a/src/app/docs/kagent/concepts/agent-memory/page.mdx +++ b/src/app/docs/kagent/concepts/agent-memory/page.mdx @@ -72,6 +72,42 @@ spec: modelConfig: default-model-config # References the embedding provider ``` +The embedding `ModelConfig` does not have to use the same provider as the agent's main LLM. Kagent supports several embedding providers, including Amazon Bedrock as shown in the following section. + +### ModelConfig example: Amazon Bedrock + +To use [Amazon Bedrock Titan embedding models](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html), create a `ModelConfig` with `provider: Bedrock`. + +The Bedrock provider uses the standard AWS credential chain, so no API key secret is required. The agent's pod must have AWS credentials with `bedrock:InvokeModel` permission for the chosen model. On Kubernetes, the recommended setup is [EKS IRSA on the agent ServiceAccount](/docs/kagent/supported-providers/amazon-bedrock#step-3-configure-the-agent-to-use-an-iam-role). + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: ModelConfig +metadata: + name: bedrock-embed + namespace: kagent +spec: + provider: Bedrock + model: amazon.titan-embed-text-v2:0 + bedrock: + region: us-east-1 +``` + +| Setting | Description | +| --- | --- | +| `provider` | Set to `Bedrock`. | +| `model` | The Bedrock embedding model ID, such as `amazon.titan-embed-text-v2:0` or `amazon.titan-embed-text-v1` Note that Titan v1 produces 1536-dimensional vectors and Titan v2 produces 1024-dimensional vectors. Kagent truncates and L2-normalizes both to the 768-dimensional vector store, so no model-specific dimension setting is required. | +| `bedrock.region` | The AWS region where the model is available, for example `us-east-1`. | + +Reference the embedding `ModelConfig` from the agent's `memory.modelConfig` field: + +```yaml +spec: + declarative: + memory: + modelConfig: bedrock-embed +``` + ### Optional: Custom TTL To change the default memory retention period of 15 days, set the `ttlDays` field. diff --git a/src/app/docs/kagent/examples/human-in-the-loop/page.mdx b/src/app/docs/kagent/examples/human-in-the-loop/page.mdx index c572258e..9e6c54d3 100644 --- a/src/app/docs/kagent/examples/human-in-the-loop/page.mdx +++ b/src/app/docs/kagent/examples/human-in-the-loop/page.mdx @@ -96,7 +96,9 @@ Once all pods report `condition met`, move on. ## Step 3 — Deploy the Agent -This is the core of the tutorial. You'll create an agent that uses kagent's **built-in Kubernetes tools** (served via the kagent tool server), with **approval gates** on the destructive ones. +HITL is just additional configuration on the agent's tool references. You can enable HITL on a new agent, or add the `requireApproval` list to an existing agent's `spec.declarative.tools` entries to gate specific tools without changing anything else about the agent. + +This step is the core of the tutorial. You create an agent that uses kagent's built-in Kubernetes tools (served via the kagent tool server), with approval gates on the destructive ones. Save this as `hitl-agent.yaml`: diff --git a/src/app/docs/kagent/examples/skills/page.mdx b/src/app/docs/kagent/examples/skills/page.mdx index 89d912a5..6853dc46 100644 --- a/src/app/docs/kagent/examples/skills/page.mdx +++ b/src/app/docs/kagent/examples/skills/page.mdx @@ -32,7 +32,7 @@ Container-based skills are executable skill implementations packaged as containe ### Step 1: Build a skill container -To create a container-based skill, package your skill files into a container image. This example creates a skill that deploys simple applications to Kubernetes. +To create a container-based skill, package your skill files into a container image. This example creates a skill named `k8s-deploy-skill` that can deploy simple applications to Kubernetes. The skill takes an app name and container image (and optional replica count and port) from the user, runs a Python script that generates a combined Deployment and Service manifest, and then applies the generated manifest to the cluster. 1. Create a skill directory with your skill files. diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx index 8a0df343..6e529a0a 100644 --- a/src/app/docs/kagent/operations/operational-considerations/page.mdx +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -99,22 +99,30 @@ urlFile > url > bundled connection string The bundled PostgreSQL instance is deployed by default (`database.postgres.bundled.enabled: true`). The database name, username, and password are all hardcoded to `kagent`. Credentials are stored in a Kubernetes Secret. -You can customize the storage size and image: - -**Helm values file:** - -```yaml -database: - postgres: - bundled: - enabled: true # default - storage: 500Mi - image: - registry: docker.io - repository: library - name: postgres - tag: "18" -``` +You can customize the storage size and image of the bundled instance when you [install](/docs/kagent/introduction/installation) or upgrade kagent. + +1. Add the bundled database settings to your Helm values file for kagent. + + ```yaml + database: + postgres: + bundled: + enabled: true # default + storage: 500Mi + image: + registry: docker.io + repository: library + name: postgres + tag: "18" + ``` + +2. Apply the values to the kagent Helm release. + + ```bash + helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --namespace kagent \ + --values kagent.yaml + ``` ### External PostgreSQL diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index fe3caa59..d50f195e 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -27,7 +27,7 @@ Follow these steps to upgrade kagent to the latest version and keep your cluster - Any custom settings - PostgreSQL database -4. **v0.9.0 and later**: You must be running at least v0.8.0 before upgrading to v0.9.0. +4. **v0.9.0 and later**: You must be running at least v0.8.0 before upgrading to v0.9.0. Check the [release notes](/docs/kagent/resources/release-notes#v09) for 0.9 specific upgrades related to database migrations and RBAC scope. ## Upgrade kagent diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index eb255754..df686a6a 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -87,7 +87,51 @@ oauth2-proxy: You can now use [SAP AI Core](https://help.sap.com/docs/sap-ai-core) as a model provider via the Orchestration Service. Configure a ModelConfig resource with the SAP AI Core provider to use SAP-hosted models with your agents. -## Additional Changes +## Database migrations + +v0.9.0 replaces GORM `AutoMigrate` with versioned SQL migrations managed by [golang-migrate](https://github.com/golang-migrate/migrate) and [sqlc](https://sqlc.dev/). Migration history is tracked in two new tables, `schema_migrations` and `vector_schema_migrations`. + +Review the following before upgrading: + +- **Minimum prior version**: You must be on v0.8.0 or later. Upgrades from earlier versions are not supported. +- **Existing data is preserved**: Tables created by GORM are reused +- **Back up first**: Take a snapshot or backup of your database before upgrading. A fresh install on a fresh database is the cleanest path. Restore from your backup if anything goes wrong. +- **Automatic rollback on failure**: If a migration fails partway through, changes are rolled back before the controller exits non-zero. On the initial run from a GORM database, rollback to version 0 is skipped to protect pre-existing tables. +- **pgvector pre-check**: When `database.postgres.vectorEnabled: true`, the migration runner verifies that the `pgvector` extension is available before running any migrations. A missing extension cannot leave core tables in a partial state. +- **Safe with multiple replicas**: Migrations use a PostgreSQL session-level advisory lock, so only one controller instance applies migrations at a time. The lock releases automatically if the process crashes. If a crash leaves a dirty migration state, the next startup detects it and rolls back before retrying. + +## RBAC scope + +The `rbac.clusterScoped` Helm value was removed in v0.9.0. RBAC scope is now derived from `rbac.namespaces`: + +| `rbac.namespaces` | Resulting RBAC | Watched namespaces | +| --- | --- | --- | +| `[]` (empty, default) | Cluster-scoped `ClusterRole` and `ClusterRoleBinding` | All namespaces | +| Non-empty list | Namespaced `Role` and `RoleBinding` per listed namespace | The same list, unless `controller.watchNamespaces` is set explicitly | + +The empty-list default is unchanged from previous releases that used `rbac.clusterScoped: true`. When `controller.watchNamespaces` is set, it always takes precedence over the auto-derived list. + +The chart fails in the following cases: + +- You still have `rbac.clusterScoped` in your Helm values. +- `rbac.namespaces` is non-empty but does not include the install namespace. + +Before you upgrade: + +1. Remove `rbac.clusterScoped` from your Helm values. +2. If you previously set `rbac.clusterScoped: false` with a custom namespace list, make sure `rbac.namespaces` includes your install namespace (typically `kagent`): + + ```yaml + rbac: + namespaces: + - kagent + - team-a + - team-b + ``` + +3. To keep cluster-scoped RBAC, leave `rbac.namespaces` empty (the default). No values change is required. + +## Additional changes in v0.9 * **Default model update** — the retired `claude-3-5-haiku-20241022` model is replaced with `claude-haiku-4-5`. * **Bedrock embedding support** — native Bedrock embedding models are now available for agent memory, extending the existing AWS Bedrock provider. @@ -95,15 +139,11 @@ You can now use [SAP AI Core](https://help.sap.com/docs/sap-ai-core) as a model * **Prompt templates in UI** — prompt templates are now manageable directly in the UI. * **Require approval toggle in UI** — you can now enable or disable the `requireApproval` setting for tools directly in the UI. * **Enhanced Go ADK model config** — broader model and provider support in the Go runtime. -* **RBAC scope changes** — the `rbac.clusterScoped` Helm value is removed. RBAC scope is now derived from `rbac.namespaces`. * **IPv6/dual-stack support** — agent bind host and UI probes now support IPv6 and dual-stack configurations. * **AWS LoadBalancer annotations** — the UI Service now supports AWS LoadBalancer service annotations for easier AWS deployment. -* **Database migration tooling** — the database backend is refactored from GORM + AutoMigrate to golang-migrate + sqlc for more reliable schema migrations. * **SSH auth for git-based skills** — fixed SSH authentication when loading skills from private Git repositories. * **MCP connection error handling** — MCP connection errors are now returned to the LLM as context instead of raising exceptions. - - # v0.8 Review this summary of significant changes from kagent version 0.7 to v0.8. From c5e881e762ccab6ae2ed651b28608bdc68f25132 Mon Sep 17 00:00:00 2001 From: Art Date: Wed, 29 Apr 2026 12:30:48 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Rachael Graham Signed-off-by: Art --- src/app/docs/kagent/concepts/agent-memory/page.mdx | 4 ++-- src/app/docs/kagent/operations/upgrade/page.mdx | 2 +- src/app/docs/kagent/resources/release-notes/page.mdx | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/app/docs/kagent/concepts/agent-memory/page.mdx b/src/app/docs/kagent/concepts/agent-memory/page.mdx index 4b809afe..a6c14320 100644 --- a/src/app/docs/kagent/concepts/agent-memory/page.mdx +++ b/src/app/docs/kagent/concepts/agent-memory/page.mdx @@ -78,7 +78,7 @@ The embedding `ModelConfig` does not have to use the same provider as the agent' To use [Amazon Bedrock Titan embedding models](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html), create a `ModelConfig` with `provider: Bedrock`. -The Bedrock provider uses the standard AWS credential chain, so no API key secret is required. The agent's pod must have AWS credentials with `bedrock:InvokeModel` permission for the chosen model. On Kubernetes, the recommended setup is [EKS IRSA on the agent ServiceAccount](/docs/kagent/supported-providers/amazon-bedrock#step-3-configure-the-agent-to-use-an-iam-role). +The Bedrock provider uses the standard AWS credential chain, so no API key secret is required. The agent's pod must have AWS credentials with the `bedrock:InvokeModel` permission for the chosen model. On Kubernetes, the recommended setup is [EKS IRSA on the agent ServiceAccount](/docs/kagent/supported-providers/amazon-bedrock#step-3-configure-the-agent-to-use-an-iam-role). ```yaml apiVersion: kagent.dev/v1alpha2 @@ -96,7 +96,7 @@ spec: | Setting | Description | | --- | --- | | `provider` | Set to `Bedrock`. | -| `model` | The Bedrock embedding model ID, such as `amazon.titan-embed-text-v2:0` or `amazon.titan-embed-text-v1` Note that Titan v1 produces 1536-dimensional vectors and Titan v2 produces 1024-dimensional vectors. Kagent truncates and L2-normalizes both to the 768-dimensional vector store, so no model-specific dimension setting is required. | +| `model` | The Bedrock embedding model ID, such as `amazon.titan-embed-text-v2:0` or `amazon.titan-embed-text-v1`. Note that Titan v1 produces 1536-dimensional vectors and Titan v2 produces 1024-dimensional vectors. Kagent truncates and L2-normalizes both to the 768-dimensional vector store, so no model-specific dimension setting is required. | | `bedrock.region` | The AWS region where the model is available, for example `us-east-1`. | Reference the embedding `ModelConfig` from the agent's `memory.modelConfig` field: diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index d50f195e..06c8c3a2 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -27,7 +27,7 @@ Follow these steps to upgrade kagent to the latest version and keep your cluster - Any custom settings - PostgreSQL database -4. **v0.9.0 and later**: You must be running at least v0.8.0 before upgrading to v0.9.0. Check the [release notes](/docs/kagent/resources/release-notes#v09) for 0.9 specific upgrades related to database migrations and RBAC scope. +4. **v0.9.0 and later**: You must be running at least v0.8.0 before upgrading to v0.9.0. Check the [release notes](/docs/kagent/resources/release-notes#v09) for 0.9-specific upgrades related to database migrations and RBAC scope. ## Upgrade kagent diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index df686a6a..298fcf07 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -97,7 +97,7 @@ Review the following before upgrading: - **Existing data is preserved**: Tables created by GORM are reused - **Back up first**: Take a snapshot or backup of your database before upgrading. A fresh install on a fresh database is the cleanest path. Restore from your backup if anything goes wrong. - **Automatic rollback on failure**: If a migration fails partway through, changes are rolled back before the controller exits non-zero. On the initial run from a GORM database, rollback to version 0 is skipped to protect pre-existing tables. -- **pgvector pre-check**: When `database.postgres.vectorEnabled: true`, the migration runner verifies that the `pgvector` extension is available before running any migrations. A missing extension cannot leave core tables in a partial state. +- **pgvector pre-check**: When `database.postgres.vectorEnabled: true` is set, the migration runner verifies that the `pgvector` extension is available before running any migrations. A missing extension cannot leave core tables in a partial state. - **Safe with multiple replicas**: Migrations use a PostgreSQL session-level advisory lock, so only one controller instance applies migrations at a time. The lock releases automatically if the process crashes. If a crash leaves a dirty migration state, the next startup detects it and rolls back before retrying. ## RBAC scope