Provision optional configuration

The following configurations are optional:

AI provider configuration: Optional - Configures the LLM provider and credentials for AI-based capabilities
Redis: Optional - Configures the properties to access own Redis

The following optional bindings are used by Managed Stacks runtimes. See Install runtime for Managed Stacks:

ArgoCD: Configures the properties to access ArgoCD service (this configuration is needed for Application composition projects)
Schema Registry: Configures the connection to Schema Registry (this configuration is needed for Event Support)
Vault: Optional - Configures the properties to access a HashiCorp Vault
Audit binding: Optional - Configure connection to the audit logging collector

⚠warning

In the following "solution-workbench" is the name of the namespace where Cloud Solution Workbench is installed.

AI providers

Use this section to connect the platform to an LLM provider via the k5-ai-credentials secret. That shared connection powers generative AI features for all users, including the Design Assistant, ADR Sidekick, and Diagram Assistant. Alternatively, users can provide a personal API key for OpenAI platform or OpenAI on Azure—see AI key configuration below.

Supported AI providers:

OpenAI platform (openai)
OpenAI on Azure (azure_openai)
Amazon Bedrock (bedrock)
Self-hosted models (OpenAI-compatible API via azure_openai)

Configuration description

Configure the desired provider and connection details in the k5-ai-credentials secret. Only include the keys needed for your provider.

Key	Description
`llm-provider`	The LLM provider to use: `openai` (OpenAI platform), `azure_openai` (OpenAI on Azure or self-hosted OpenAI-compatible API), or `bedrock` (Amazon Bedrock).
`design-assistant-llm-model`	The primary model ID (or Azure deployment name) used by the Design Assistant.
`design-assistant-compaction-llm-model`	Optional. Model ID used by the Design Assistant to summarize older conversation turns into a session digest when the conversation history approaches the context limit. Defaults to `design-assistant-llm-model`.
`cross-project-llm-model`	Optional. Model ID used by the Design Assistant's read-only sub-agent when exploring another project or branch. Defaults to `design-assistant-llm-model`.
`adr-sidekick-llm-model`	The model ID used by ADR Sidekick.
`generic-chat-completion-llm-model`	The model ID used by Diagram Assistant.
`llm-temperature`	Optional. Controls response randomness (`0.0` = deterministic, higher = more creative). Default: `0.0`. Automatically set to `1.0` for OpenAI reasoning models (`gpt-5.6*`, `o1`, `o3`, `o4`).
`llm-reasoning-effort`	Optional. Reasoning effort for OpenAI/Azure reasoning models (`gpt-5.6`, `o1`, `o3`, `o4`): `none`, `low`, `medium`, `high`, `xhigh`, or `max`. Unset uses the provider default (`medium` for `gpt-5.6`). Leave unset for `gpt-5.4`.
`aws-bedrock-prompt-cache-ttl`	Optional. Bedrock prompt cache TTL when `llm-provider` is `bedrock`: `5m` (default), `1h` (supported on Claude 4.5 and newer models), or `off`.

AI key configuration

The Design Assistant, ADR Sidekick, and Diagram Assistant can use the central k5-ai-credentials secret.

In addition, users can provide their own API key for OpenAI platform or OpenAI on Azure in User settings. When a personal key is configured, it takes precedence over the central key. Personal API keys are not supported with Amazon Bedrock.

Model requirements and recommendations

All models in the workbench operate on text only (multimodal image, audio, or video capabilities are not required). Use the subsections below to choose a recommended model or to evaluate alternatives.

Design Assistant (General) — `design-assistant-llm-model`

Purpose & when to configure: Main agent loop: inspects OML schemas, composes GraphQL queries, stages model and diagram changes, and calls MCP tools.
Classification & required capabilities: Frontier agentic / tool-calling. Multi-step & parallel tool calling (~20 tools), strict JSON schema adherence, and prompt caching.
Context window: Min: 128k · Rec: 250k+ (capped by llmMaxInputTokens, default 250k)
Recommended: OpenAI / Azure OpenAI: Min / Default: gpt-5.4 · Frontier upgrade: gpt-5.6-sol (or gpt-5.6-terra)
Recommended: Amazon Bedrock: Min / Default: Claude Sonnet 5.5 (eu.anthropic.claude-sonnet-5-5) · Frontier upgrade: Claude Opus 5.5 (eu.anthropic.claude-opus-5-5)
Self-hosted / open-weight guidance: Min ~30B dense or 100B+ MoE (e.g. Qwen3.8-27B, Qwen3.5-122B-A10B, gpt-oss-120b, DeepSeek-V4-Flash) with ≥128k context. Compare on BFCL, τ-bench, and SWE-bench Verified.

Design Assistant (Cross-project) — `cross-project-llm-model`

Purpose & when to configure: Optional. Runs a read-only sub-agent (6 read tools) when a prompt references another project or branch. Configure this when using a heavier frontier model (such as gpt-5.6-sol or Claude Opus 5.5) as the general model so cross-project lookups stay fast and cost-effective. Defaults to design-assistant-llm-model.
Classification & required capabilities: High-throughput agentic / tool-calling. Reliable read-only tool calling, GraphQL query composition, and structured summarization.
Context window: Min: 128k · Rec: 200k+
Recommended: OpenAI / Azure OpenAI: gpt-5.4 (or leave unset if general model is already gpt-5.4)
Recommended: Amazon Bedrock: Claude Sonnet 5.5 (eu.anthropic.claude-sonnet-5-5) (or leave unset if general model is already Sonnet 5.5)
Self-hosted / open-weight guidance: Same requirements as General (30B+ dense or 100B+ MoE, ≥128k context).

Design Assistant (Compaction) — `design-assistant-compaction-llm-model`

Purpose & when to configure: Optional. Summarizes older conversation turns into a structured session briefing when history reaches 60% of the input token cap. Defaults to design-assistant-llm-model.
Classification & required capabilities: Cost-optimized long-context reasoning. Faithful long-transcript summarization and exact retention of technical IDs. No tool calling required. (Note: gpt-5.4-mini is not recommended due to lower summarization fidelity.)
Context window: Min: 128k · Rec: 200k+
Recommended: OpenAI / Azure OpenAI: gpt-5.6-luna (or leave unset to reuse general model)
Recommended: Amazon Bedrock: Claude Haiku 5.5 (eu.anthropic.claude-haiku-5-5) (or leave unset to reuse general model)
Self-hosted / open-weight guidance: 20B–30B+ reasoning model (e.g. Qwen3.8-27B, gpt-oss-20b) with ≥128k context.

ADR Sidekick & Diagram Assistant — `adr-sidekick-llm-model` / `generic-chat-completion-llm-model`

Purpose & when to configure: Single-turn text and diagram generation in ADR Sidekick and Diagram Assistant.
Classification & required capabilities: General chat completion
Context window: —
Recommended: OpenAI / Azure OpenAI: gpt-4o or gpt-5.1
Recommended: Amazon Bedrock: Amazon Nova 2 Lite (eu.amazon.nova-2-lite-v1:0) or Claude Haiku 5.5
Self-hosted / open-weight guidance: gpt-oss-20b or comparable

💡Context window cap (k5-design-assistant.llmMaxInputTokens)

The Helm parameter k5-design-assistant.llmMaxInputTokens (default 250000) caps how many input tokens the Design Assistant sends in a single request before compacting the conversation:

On cloud models with 1M-token windows (gpt-5.4, gpt-5.6*, Claude 5.5), keeping the default 250000 avoids long-context pricing tiers while providing ample working memory.
On custom Azure deployment names or self-hosted models whose context window cannot be detected from the model name, set k5-design-assistant.llmMaxInputTokens to match your model's actual maximum input tokens (for example 128000).

OpenAI platform

Secret configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-ai-credentials
  namespace: <solution-workbench>
stringData:
  llm-provider: "openai"
  openaiapi.key: "<your-openai-api-key>"
  # General model: "gpt-5.4" (minimum recommended) or "gpt-5.6-sol" (frontier reasoning)
  design-assistant-llm-model: "gpt-5.4"
  # Compaction model (optional, defaults to design-assistant-llm-model)
  design-assistant-compaction-llm-model: "gpt-5.6-luna"
  # Cross-project model (optional; set to "gpt-5.4" when using "gpt-5.6-sol" above)
  # cross-project-llm-model: "gpt-5.4"
  # ADR Sidekick and Diagram Assistant models
  adr-sidekick-llm-model: "gpt-5.1"
  generic-chat-completion-llm-model: "gpt-5.1"
  # Optional sampling and reasoning configuration
  llm-temperature: "0.0"
  # llm-reasoning-effort: "medium" # Optional; for gpt-5.6* / o-series models only

Adjust metadata.namespace and stringData, then apply the secret:

oc apply -f secret.yaml

OpenAI on Azure

On Azure OpenAI, set the -llm-model keys to your Azure deployment names. If you deploy a gpt-5.6* model on Azure, include gpt-5.6 in the deployment name so the Design Assistant automatically enables the Responses API.

Secret configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-ai-credentials
  namespace: <solution-workbench>
stringData:
  llm-provider: "azure_openai"
  azure-openai-endpoint: "https://<resource-name>.openai.azure.com/openai/v1"
  openaiapi.key: "<your-azure-openai-api-key>"
  # Set model keys to your Azure deployment names
  design-assistant-llm-model: "gpt-5.4"
  design-assistant-compaction-llm-model: "gpt-5.6-luna"
  # cross-project-llm-model: "gpt-5.4"
  adr-sidekick-llm-model: "gpt-5.1"
  generic-chat-completion-llm-model: "gpt-5.1"
  llm-temperature: "0.0"

Adjust metadata.namespace and stringData, then apply the secret:

oc apply -f secret.yaml

Amazon Bedrock

For Amazon Bedrock, authenticate using one of the following: an IAM role for the service account (IRSA, recommended on AWS—omit static keys), a Bedrock API key (aws-bedrock-api-key), or IAM access keys (aws-access-key-id and aws-secret-access-key). Use the regional or global inference profile prefix matching your setup (for example eu., us., or global.).

Secret configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-ai-credentials
  namespace: <solution-workbench>
stringData:
  llm-provider: "bedrock"
  aws-default-region: "<aws-region>"
  # Option 1: Bedrock API key
  aws-bedrock-api-key: "<aws-bedrock-api-key>"
  # Option 2: IAM access keys (use instead of aws-bedrock-api-key, or omit both for IRSA)
  # aws-access-key-id: "<access-key-id>"
  # aws-secret-access-key: "<secret-access-key>"
  # General model: Claude Sonnet 5.5 (recommended) or Claude Opus 5.5 (frontier)
  design-assistant-llm-model: "eu.anthropic.claude-sonnet-5-5"
  # Compaction model (optional, defaults to design-assistant-llm-model)
  design-assistant-compaction-llm-model: "eu.anthropic.claude-haiku-5-5"
  # Cross-project model (optional; set to Sonnet 5.5 when using Opus 5.5 above)
  # cross-project-llm-model: "eu.anthropic.claude-sonnet-5-5"
  # ADR Sidekick and Diagram Assistant models
  adr-sidekick-llm-model: "eu.amazon.nova-2-lite-v1:0"
  generic-chat-completion-llm-model: "eu.amazon.nova-2-lite-v1:0"
  # Optional temperature and prompt cache TTL ("5m", "1h", or "off")
  llm-temperature: "0.0"
  aws-bedrock-prompt-cache-ttl: "5m"

Adjust metadata.namespace and stringData, then apply the secret:

oc apply -f secret.yaml

Self-hosted models

You can connect the platform to a self-hosted inference server that exposes an OpenAI-compatible API (such as vLLM or Ollama). Set llm-provider: "azure_openai" and point azure-openai-endpoint to your server's /v1 base URL.

⚠warning

Verify that your self-hosted model and serving runtime support OpenAI-compatible tool calling (for example --enable-auto-tool-choice and the appropriate --tool-call-parser in vLLM) and provide at least a 128k context window. Also set the Helm parameter k5-design-assistant.llmMaxInputTokens to match the served context window (for example 128000).

Secret configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-ai-credentials
  namespace: <solution-workbench>
stringData:
  llm-provider: "azure_openai"
  azure-openai-endpoint: "https://<host, e.g. ollama:11434>/v1"
  openaiapi.key: "<your-api-key>"
  design-assistant-llm-model: "qwen3.8:27b"
  design-assistant-compaction-llm-model: "qwen3.8:27b"
  adr-sidekick-llm-model: "gpt-oss:20b"
  generic-chat-completion-llm-model: "gpt-oss:20b"
  llm-temperature: "0.0"

Adjust metadata.namespace and stringData, then apply the secret:

oc apply -f secret.yaml

ArgoCD

These configurations are required to connect to the ArgoCD service.

Configuration description:

Key	Description
url	The url of the ArgoCD service
username	The username to login into the ArgoCD service
password	The password to login into the ArgoCD service
namespace	The namespace (or OpenShift project) of the ArgoCD installation

⚠warning

Please use the public route URL as url or ensure that all certificates (whole chain) of the ArgoCD Service are included in the Truststore.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-argocd-binding
  namespace: <solution-workbench>
stringData:
  url: "https://openshift-gitops-server.apps.openshift-cluster.mydomain.cloud"
  username: "user"
  password: "pw123"
  namespace: "openshift-gitops"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Redis

These configurations are required to connect to the Redis service.

Configuration description:

Key	Description
host	The host of the Redis service
password	The password to login into the Redis service
port	The port of the Redis service

⚠warning

Please use the internal service URL as host, e.g. redis-master.redis-namespace.svc.cluster.local.

⚠warning

If you have configured a Redis service you can enable Horizontal Pod Autoscaling for k5-diagram-modelling service, see Extended configuration

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-redis-binding
  namespace: <solution-workbench>
stringData:
  host: "redis-master.redis-namespace.svc.cluster.local"
  password: "pw123"
  port: "6379"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Schema Registry

This configuration is necessary to connect to the Schema Registry.

Configuration description:

Parameter	Description
cleanUpTaskTime (optional)	The time when the clean up job should be run. Please use cron schedule expressions. (Default: `0 0 20 * * Saturday`)
cleanUpTaskTimeZone (optional)	The timezone you're in. Example: `Europe/Berlin` (Default timezone: `UTC`)
url	Url of the Schema Registry.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-schema-registry-binding
  namespace: <solution-workbench>
stringData:
  url: "https://schema-registry.apps.openshift-cluster.mydomain.cloud"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Vault

Configures properties to access a HashiCorp Vault. This configuration is not mandatory!

Configuration description:

Parameter	Description
url	The url of the HashiCorp Vault
role	The name of the role you configured in your vault. You can find information how to do that here.

⚠warning

Losing/changing the vault configuration can cause errors and secrets need to be recreated.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-vault-binding
  namespace: <solution-workbench>
  labels:
    k5-configuration: 'true'
stringData:
  url: "string"
  role: "string"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Audit Binding

This configuration is necessary to connect to your audit logging collector (e.g. Fluentd). By default, the audit logging is disabled since it is not meant to be used without a connection to an audit logging collector. If you do not wish Audit Logging, you can skip this configuration.

Configuration description:

Parameter	Description
auditEnabled	Enables or disables the Audit logging.
connectionString	The Fluentd connectionString for Audit logging.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-auditlog-settings
  namespace: <solution-workbench>
  labels:
    k5-configuration: 'true'
stringData:
  auditEnabled: "boolean"
  connectionString: "string"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

AI providers​

Configuration description​

AI key configuration​

Model requirements and recommendations​

Design Assistant (General) — design-assistant-llm-model​

Design Assistant (Cross-project) — cross-project-llm-model​

Design Assistant (Compaction) — design-assistant-compaction-llm-model​

ADR Sidekick & Diagram Assistant — adr-sidekick-llm-model / generic-chat-completion-llm-model​

OpenAI platform​

OpenAI on Azure​

Amazon Bedrock​

Self-hosted models​

ArgoCD​

Redis​

Schema Registry​

Vault​

Audit Binding​

AI providers

Configuration description

AI key configuration

Model requirements and recommendations

Design Assistant (General) — `design-assistant-llm-model`

Design Assistant (Cross-project) — `cross-project-llm-model`

Design Assistant (Compaction) — `design-assistant-compaction-llm-model`

ADR Sidekick & Diagram Assistant — `adr-sidekick-llm-model` / `generic-chat-completion-llm-model`

OpenAI platform

OpenAI on Azure

Amazon Bedrock

Self-hosted models

ArgoCD

Redis

Schema Registry

Vault

Audit Binding