From 06e67b8cc4897ab48d733330ed9137e34ced0449 Mon Sep 17 00:00:00 2001 From: zlc Date: Thu, 9 Jul 2026 08:14:17 +0000 Subject: [PATCH 1/5] docs: update install guide to match current plugin form The install page still documented the v1.2.0 flow. Verified against the smart-doc chart (charts/smart-doc/scripts/plugin-config.yaml, templates/, files/init-database.sh) and a live v1.5.0 deployment: - Drop the manual database-dump prepare/import sections: since v1.2.1 an init container bootstraps the knowledge base from the built-in dump selected in the form (Built-in KnowledgeBase File). - Fix the upload script: replace undefined AI_CLUSTER_OPERATOR_NAME / CLUSTER (copied from the Alauda AI docs) with PACKAGE_FILE and --clusters=global. - Fix the external PostgreSQL secret example: uri scheme is postgresql+psycopg, not pg8000. - Document the current install form: built-in PGVector/Redis toggles and external-secret formats, credentials Secret reference (llm-api-key/cohere-api-key/api-key), reranker, tool approval strategy, Expose as MCP Server, extra MCP/CA ConfigMaps, Skills, rate and quota limits, RAG tuning. - Remove form fields that no longer exist (Enable Agent Mode, MCP K8s API Server Address) and add a post-install verification section. Co-Authored-By: Claude Fable 5 --- docs/en/install.mdx | 191 +++++++++++++++++++++++++++++--------------- 1 file changed, 127 insertions(+), 64 deletions(-) diff --git a/docs/en/install.mdx b/docs/en/install.mdx index 8411c80..bbf18bb 100644 --- a/docs/en/install.mdx +++ b/docs/en/install.mdx @@ -12,12 +12,12 @@ The downloaded package is a tarball file named `alauda-hyperflux-.tar.g Download the `violet` command line tool if it is not present on the machine: 1. Log into the ACP Web Console and switch to the **Administrator** view. -1. In **Marketplace / Upload Packages**, click **Download Packaging and Listing Tool**. -2. Select the right OS/CPU arch, and click **Download**. -3. Run `chmod +x ${PATH_TO_THE_VIOLET_TOOL}` to make the tool executable. +2. In **Marketplace / Upload Packages**, click **Download Packaging and Listing Tool**. +3. Select the right OS/CPU arch, and click **Download**. +4. Run `chmod +x ${PATH_TO_THE_VIOLET_TOOL}` to make the tool executable. Save the following script in `upload.sh`, -then edit the file to fill in the correct configuration values acording to the comments. +then edit the file to fill in the correct configuration values according to the comments. ```bash #!/usr/bin/env bash @@ -46,13 +46,14 @@ if [[ "${IS_EXTERNAL_REGISTRY}" == "true" ]]; then ) fi -# Push **Alauda AI Cluster** operator package to destination cluster +# Push the Alauda Hyperflux plugin package to the `global` cluster +# (Alauda Hyperflux MUST be installed in the `global` cluster) violet push \ - ${AI_CLUSTER_OPERATOR_NAME} \ + ${PACKAGE_FILE} \ --platform-address=${PLATFORM_ADDRESS} \ --platform-username=${PLATFORM_ADMIN_USER} \ --platform-password=${PLATFORM_ADMIN_PASSWORD} \ - --clusters=${CLUSTER} \ + --clusters=global \ ${VIOLET_EXTRA_ARGS[@]} ``` @@ -66,11 +67,9 @@ You will use the LLM service endpoint, model name and API key in the Alauda Hype Optionally, if you want to enable the rerank feature in Alauda Hyperflux, you also need to prepare a rerank service that supports Cohere Reranker API v2. -## Prepare the database dump file (ONLY needed for v1.2.0) - -Download the database dump file like `docvec_acp_4_1.dump` for your current ACP version. -You **MUST** use the file name like `docvec_acp_4_1` as the database name during installation. - +> **NOTE:** The knowledge base is initialized automatically from a built-in database dump file +> selected during installation. Manually preparing and importing a database dump file is no longer +> needed (it was only required for v1.2.0). ## Install Alauda Hyperflux cluster plugin @@ -78,15 +77,20 @@ Go to **Administrator / Marketplace / Cluster Plugins** page, select "global" cluster from the cluster dropdown list, then find the `Alauda Hyperflux` plugin and click **Install**. -> **NOTE:** Alauda Hyperflux **MUST** be installed in the `Global` cluster. +> **NOTE:** Alauda Hyperflux **MUST** be installed in the `global` cluster. Fill in the configurations below: -- Built-in PG database: - - Enabled: will install a single PostgreSQL instance in the cluster for Alauda Hyperflux to use. You need to set: - - storage size: the storage size for PostgreSQL data. - - storage class name: Kubernetes storage class name, e.g. `sc-topolvm` - - Disabled: create a secret below to provide external PostgreSQL connection info. +### Knowledge base and databases + +- **Built-in KnowledgeBase File**: the built-in database dump file used to initialize the knowledge base + on first startup. Select the file matching your ACP version, e.g. `docvec_gte_acp_4_3_.dump` for ACP 4.3. +- **Enable builtin PGVector**: + - Enabled: a single PostgreSQL (with pgvector) instance will be installed in the cluster for Alauda Hyperflux to use. You need to set: + - **PGVector Storage Size**: the storage size for PostgreSQL data, e.g. `10Gi`. + - **PGVector StorageClass name**: Kubernetes storage class name, e.g. `sc-topolvm`. + - Disabled: provide the connection info of an external PostgreSQL (pgvector extension required) via a secret, + and fill the secret name in **pg database secret name**: ```yaml apiVersion: v1 kind: Secret @@ -99,62 +103,121 @@ Fill in the configurations below: port: username: password: - uri: "postgresql+pg8000://:@:" + uri: "postgresql+psycopg://:@:" + ``` +- **PG database name**: the PostgreSQL database name for storing conversation history. +- **PG collection name**: the collection name for storing document vectors. + **MUST** be the same as the selected built-in knowledge base file name without the `.dump` suffix. +- **Enable builtin Redis**: Redis is used by the rate limiter and caching. + - Enabled: a single Redis instance will be installed in the cluster. + - Disabled: provide the connection info of an external Redis via a secret, + and fill the secret name in **redis database secret name**: + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: redis-secret + namespace: cpaas-system + type: Opaque + stringData: + REDIS_HOST: + REDIS_PORT: + REDIS_PASSWORD: + REDIS_DB: "0" ``` -- PG database name: the database name for Alauda Hyperflux to use. **MUST** be the same as the database dump file name without the `.dump` suffix. -- Node Selector(Optional): set the node selector for Alauda Hyperflux pods if needed. -- LLM Model Type: Azure or OpenAI. -- LLM Base URL: the base URL for LLM API calls. When using On-Premise deployment of LLM service like vllm, the url should like `http://:/v1`. -- Model Name: the model name for LLM API calls. -- API Key: the API key for LLM API calls. -- Azure API Version(Optional): when using Azure OpenAI service, set the API version here. -- Azure Deployment Name(Optional): when using Azure OpenAI service, set the deployment name here. -- Enable Rerank: whether to enable the rerank feature in Alauda Hyperflux using **Cohere API**. Set below values if enabled: - - Cohere Reranker BaseURL: the base URL for Cohere Reranker API calls. - - Cohere Reranker Model: the model name for Cohere Reranker API calls. - - Cohere API Key: the API key for Cohere Reranker API calls. -- Enable Agent Mode: whether to enable Agent mode to leverage MCP tools to retrieve real-time cluster information. - - **NOTE**: Agent mode is an experimental feature, please use with caution. -- MCP K8s API Server Address: the K8s API server address of the MCP cluster. - - **IMPORTANT:** You should set this url to erebus address like `https://erebus.cpaas-system:443/kubernetes/`. - - **IMPORTANT:** the `cluster-name` should be set to the cluster name you want MCP tools to access. -- Admin User Names: the comma-separated admin user list. Admin users can manage Audit logs in Alauda Hyperflux. - +### LLM service + +- **LLM Model type**: `azure` (Azure OpenAI) or `openai` (OpenAI-compatible API, e.g. vllm). +- **LLM Base URL**: the base URL for LLM API calls. When using an On-Premise deployment of LLM service + like vllm, the URL should look like `http://:/v1`. +- **LLM Model Name**: the model name for LLM API calls. +- **Use an existing credentials Secret**: + - Disabled (default): enter the API keys directly in the form below; a secret is created automatically. + - **LLM API Key**: the API key for LLM API calls. + - **Cohere Reranker API key**: shown when the reranker is enabled. + - Enabled: reference a pre-existing secret in **Existing credentials Secret**. + The secret must contain the keys `llm-api-key`, `cohere-api-key` and `api-key`. +- **Azure API Version** (Azure only): the Azure OpenAI API version, e.g. `2024-12-01-preview`. +- **Azure Deployment Name** (Azure only): the Azure OpenAI deployment name. +- **Model Context Window** (Optional): context window size of the LLM model (e.g. `128000`). + Leave empty to auto-detect by model name. + +### Reranker (Optional) + +- **Enable Reranker**: whether to enable the reranking feature, which improves the relevance of + retrieved documents. Only Cohere Reranker API is supported currently. Set below values if enabled: + - **Cohere Reranker BaseUrl**: the base URL for Cohere Reranker API calls. + - **Cohere Reranker Model**: the model name for Cohere Reranker API calls, e.g. `rerank-v3.5`. + - **Cohere Reranker API key**: the API key for Cohere Reranker API calls + (hidden when using an existing credentials secret). + +### Agent tools (MCP) + +- **Expose MCP**: whether to access the built-in MCP server via Ingress. +- **Tool Approval Strategy**: decide which agent tool calls require human approval: + - `disabled` (default): write tools are filtered out of the LLM tool set, so the LLM cannot call them at all. + - `tool_annotations`: write tools (MCP `readOnlyHint=false`) require interactive approval. + - `always`: every tool call requires interactive approval. + - `never`: no approval, the LLM can call any tool unattended. **Use with caution in production.** +- **Expose as MCP Server**: expose Alauda Hyperflux itself as an MCP server at `/mcp`, so IDEs and + agents can call it as a tool. Read operations are always allowed; write actions require + interactive approval. Default off. + - **MCP Write-Approval Timeout (s)**: max seconds to wait for a write-approval response before + treating it as a decline. Default `300`. +- **Extra MCP Servers ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) holding + extra MCP server definitions; each ConfigMap's `*.yaml`/`*.yml`/`*.json` entries are scanned at startup. + +### Skills + +- **Enable Skills**: auto-load admin-configured procedural skills (mounted from ConfigMaps) when a query matches. + - **Skills Match Threshold**: cosine threshold (0-1) for matching a query to a skill. + Higher is stricter. Default `0.35`. + - **Skills ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) whose `*.md` + entries are loaded as skills. + +### Rate and quota limits + +- **Enable Rate Limiter**: whether to enable per-user rate limiting and daily token quotas. + Set below values if enabled: + - **Max Requests Per Minute (RPM)**: default `5`. + - **RPM Window Time (Minute)**: default `5`. + - **Max Total Tokens Per Day**: default `1000000`. + - **Max Input Tokens Per Day**: default `200000`. + - **Max Output Tokens Per Day**: default `1000000`. + +### RAG tuning + +The defaults work for most cases; adjust only if needed. + +- **Total Search K**: total number of search results to retrieve from the knowledge base. Default `20`. +- **RAG Similarity Threshold**: similarity threshold for retrieving relevant documents. Default `0.8`. +- **Cohere Reranker Top N**: number of top documents to keep after reranking. Default `6`. +- **Max History Number**: number of previous interactions to retain in chat history. Default `1`. + +### Other settings + +- **Node Selector** (Optional): set the node label key/value terms for Alauda Hyperflux pods if needed. +- **Admin Users**: comma-separated admin user names, e.g. `admin@cpaas.io,user1`. + Admin users can manage audit logs in Alauda Hyperflux. +- **Extra CA ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) holding + internal / self-signed CA certificates (PEM). The certificates are appended to the outbound TLS + trust bundle, so LLM / MCP / reranker endpoints using such certificates can be accessed. Click **Install** to start installation. -## Import database dump to initialize knowledge base (ONLY needed for v1.2.0) +## Verify the installation + +The knowledge base is initialized automatically on the first startup: an init container creates the +databases and restores the selected built-in dump file. This may take a few minutes. -After the Alauda Hyperflux installation is complete, you need to import the database dump file to initialize the knowledge base. -Use the following command to import the database dump file: +Check that the pods are running: ```bash -# Get the PostgreSQL pod name -kubectl -n cpaas-system get pod | grep postgre-vec -# Copy the dump file to the PostgreSQL pod -kubectl -n cpaas-system cp docvec_acp_4_1.dump :/tmp/docvec_acp_4_1.dump -# Temporarily stop the Alauda Hyperflux deployment to avoid connection issues during database import -kubectl -n cpaas-system scale deployment smart-doc --replicas=0 -# Exec into the PostgreSQL pod -kubectl -n cpaas-system exec -it -- /bin/bash -# Import the database dump file -# NOTE: change the database name docvec_acp_4_1 to the actual database name -psql -U postgres -W -c "DROP DATABASE docvec_acp_4_1;" -psql -U postgres -W -c "CREATE DATABASE docvec_acp_4_1;" -pg_restore -U postgres -W -d docvec_acp_4_1 /tmp/docvec_acp_4_1.dump -# Enter the password when prompted -# Exit the pod -exit - -# Restart the Alauda Hyperflux deployment -kubectl -n cpaas-system scale deployment smart-doc --replicas=1 -# execute db_orm.py to re-init database schema -kubectl -n cpaas-system exec -it -- python /workspace/db_orm.py +kubectl -n cpaas-system get pod | grep smart-doc ``` -> **NOTE:** when using built-in PostgreSQL database, the default password is `alauda-test`. - +Once the `smart-doc` pod is ready, open the ACP Web Console and the Alauda Hyperflux chat panel is available. ## Troubleshooting From fa568a1353295c21428df9133330ae95b822a859 Mon Sep 17 00:00:00 2001 From: zlc Date: Thu, 9 Jul 2026 08:38:28 +0000 Subject: [PATCH 2/5] docs: add how-to guides for external MCP, custom skills, TLS, and IDE MCP usage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four task guides under a new How To section, each verified against the smart-doc source (server/src/extra_mcp.py, skills.py, certificates.py, mcp_server.py, auth.py and the chart) and, where possible, against a live deployment: - Configure External MCP Servers: ConfigMap schema (name/url/transport/ headers/tls_verify), registration, tool-name prefixing, and the approval-strategy gotcha where unannotated tools are filtered out under the default `disabled` strategy. - Create Custom Skills: frontmatter format, cosine matching against name+description with the 0.35 threshold, built-in skill overrides, and load/match verification via logs. - Configure TLS: Extra CA ConfigMaps as the main path (process-wide trust for LLM/MCP/reranker, PG excluded), plus the MiConfig-only advanced knobs and the llmSkipSslVerify warning. - Use Hyperflux as an MCP Server in Your IDE: endpoint (trailing slash required — verified live: /mcp without it returns a 307 the ingress strips the Location from), bearer/API-key auth, client config examples, and the elicitation-based write-approval flow. The full handshake and tools/list were exercised against a live deployment. Install guide now cross-links each of the four guides. Co-Authored-By: Claude Fable 5 --- docs/en/how-to/configure-external-mcp.mdx | 114 +++++++++++++++++ docs/en/how-to/configure-tls.mdx | 107 ++++++++++++++++ docs/en/how-to/custom-skills.mdx | 126 +++++++++++++++++++ docs/en/how-to/index.mdx | 7 ++ docs/en/how-to/use-mcp-in-ide.mdx | 145 ++++++++++++++++++++++ docs/en/install.mdx | 7 +- 6 files changed, 504 insertions(+), 2 deletions(-) create mode 100644 docs/en/how-to/configure-external-mcp.mdx create mode 100644 docs/en/how-to/configure-tls.mdx create mode 100644 docs/en/how-to/custom-skills.mdx create mode 100644 docs/en/how-to/index.mdx create mode 100644 docs/en/how-to/use-mcp-in-ide.mdx diff --git a/docs/en/how-to/configure-external-mcp.mdx b/docs/en/how-to/configure-external-mcp.mdx new file mode 100644 index 0000000..8738cd4 --- /dev/null +++ b/docs/en/how-to/configure-external-mcp.mdx @@ -0,0 +1,114 @@ +--- +weight: 10 +--- + +# Configure External MCP Servers + +Alauda Hyperflux ships with a built-in MCP server that provides cluster-aware tools. +You can extend the agent's tool set with your own (external) MCP servers — for example an +internal wiki search, a CMDB query service, or any other MCP-compatible endpoint. + +External MCP servers are declared in ConfigMaps and registered through the installation form. +At startup, Alauda Hyperflux connects to each server, lists its tools, and makes them available +to the agent alongside the built-in tools. + +## Declare the MCP servers in a ConfigMap + +Create a ConfigMap **in the namespace where Alauda Hyperflux is installed** (`cpaas-system`). +Every data key with a `.yaml`, `.yml` or `.json` extension is parsed; the content of each file +must be a **list** of server entries: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-org-mcp-servers + namespace: cpaas-system +data: + servers.yaml: | + - name: corp-wiki + url: https://wiki-mcp.example.com/mcp + transport: streamable_http + headers: + Authorization: "Bearer " + - name: cmdb + url: https://cmdb-mcp.example.com/sse + transport: sse + tls_verify: false +``` + +Fields per server entry: + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | Unique server name matching `^[a-z][a-z0-9_-]*$`. The name `acp_mcp_server` is reserved. | +| `url` | Yes | The MCP endpoint URL. | +| `transport` | No | `streamable_http` (default) or `sse`. | +| `headers` | No | Static HTTP headers sent on every request, e.g. for token auth. `${VAR}` placeholders are substituted from the container environment if the variable exists. | +| `tls_verify` | No | Whether to verify the server's TLS certificate. Default `true`. For endpoints using an internal CA, prefer keeping this `true` and adding the CA via **Extra CA ConfigMaps** (see [Configure TLS](./configure-tls.mdx)). | + +Invalid entries (bad name, missing url, unknown transport, duplicate name) are skipped with an +ERROR log; they never prevent the other servers or the service itself from starting. + +> **NOTE:** ConfigMap values are stored in plain text. Avoid putting long-lived secrets directly +> in `headers`; rotate any token you place there as you would any shared credential. + +## Register the ConfigMap + +In **Administrator / Marketplace / Cluster Plugins**, install or update the `Alauda Hyperflux` +plugin and add the ConfigMap name under **Extra MCP Servers ConfigMaps**. + +Each listed ConfigMap is mounted read-only at `/opt/extra-mcp//` and scanned +**once at startup**: + +- Adding or removing a ConfigMap name in the form triggers a rolling restart automatically. +- Editing the *content* of an already-registered ConfigMap does **not** — restart manually: + + ```bash + kubectl -n cpaas-system rollout restart deploy/smart-doc + ``` + +## Tool naming and approval + +Tools from an external server are exposed to the agent with the server name as a prefix, +e.g. `corp-wiki__search_pages`, so they can never collide with built-in tool names. + +External tools are subject to the same **Tool Approval Strategy** as built-in tools: + +- With the default strategy `disabled`, any tool **not** annotated `readOnlyHint: true` by its + MCP server is filtered out of the agent's tool set entirely. Many MCP servers do not annotate + their tools — in that case none of their tools will be visible until you either switch the + strategy to `tool_annotations` (write tools then require interactive approval) or have the + MCP server annotate its read-only tools. +- With `tool_annotations`, read-only tools run freely and all other tools prompt the user for + approval before each call. + +## Verify + +Check the startup logs: + +```bash +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep -i "extra mcp\|MCP tools" +``` + +Expected lines: + +``` +Loading extra MCP servers from file /opt/extra-mcp/my-org-mcp-servers/servers.yaml +Loading extra MCP server name=corp-wiki url=https://wiki-mcp.example.com/mcp transport=streamable_http headers={'Authorization': ''} +Extra MCP corp-wiki loaded 3 tools: ['corp-wiki__search_pages', ...] +Loaded 15 MCP tools (acp=12, extra=3) +``` + +Common failure modes: + +| Log message | Cause | +|---|---| +| `Extra MCP timed out after 10.0s; skipped` | The endpoint is unreachable or slow; each server has a 10-second connection budget and is skipped without affecting the others. | +| `Extra MCP failed to load: ...; skipped` | Connection or protocol error — check the URL, transport and TLS trust. | +| ` is not valid YAML` / `must be a list` | The ConfigMap file content is malformed. | +| `extra MCP header placeholder ${VAR} not in environment; leaving as-is` | A `${VAR}` header referenced an environment variable that does not exist in the container. | +| `AGENT_APPROVAL_STRATEGY=disabled — filtered out N write/unannotated tools` | Tools without `readOnlyHint: true` were removed under the default approval strategy (see above). | + +Sensitive header values (`Authorization`, `X-API-Key`, cookies, and any value longer than +16 characters) are always redacted in logs. diff --git a/docs/en/how-to/configure-tls.mdx b/docs/en/how-to/configure-tls.mdx new file mode 100644 index 0000000..85c1896 --- /dev/null +++ b/docs/en/how-to/configure-tls.mdx @@ -0,0 +1,107 @@ +--- +weight: 30 +--- + +# Configure TLS + +This guide covers the TLS-related configuration of Alauda Hyperflux for its outbound +connections: the LLM service, the reranker, MCP servers and PostgreSQL. + +The most common need — trusting an LLM or MCP endpoint that uses an internal or self-signed +certificate — is solved with **Extra CA ConfigMaps**, available directly in the installation +form. The remaining knobs are advanced settings applied by patching the plugin configuration. + +## Trust an internal / self-signed CA (Extra CA ConfigMaps) + +If your LLM, reranker or MCP endpoint presents a certificate signed by an internal CA, requests +fail with `CERTIFICATE_VERIFY_FAILED`. Add the CA certificate to the trust bundle: + +1. Create a ConfigMap holding the CA certificate (PEM) **in the namespace where Alauda + Hyperflux is installed** (`cpaas-system`). CA certificates are public, so a ConfigMap — not + a Secret — is appropriate. One ConfigMap can hold multiple `*.pem` keys: + + ```bash + kubectl create configmap my-org-internal-ca -n cpaas-system \ + --from-file=ca.pem=/path/to/internal-ca.pem + ``` + +2. In **Administrator / Marketplace / Cluster Plugins**, install or update the + `Alauda Hyperflux` plugin and add the ConfigMap name under **Extra CA ConfigMaps**. + The service restarts automatically. + +Each listed ConfigMap is mounted read-only at `/opt/extra-ca//`. At startup the +certificates are merged with the default CA bundle and the merged bundle is applied +process-wide, so it covers **LLM, reranker and MCP** connections. + +> **NOTE:** PostgreSQL is the exception — it does not use this bundle. For TLS to an external +> PostgreSQL, see the `pgSSLMode` / `pgSSLRootCert` settings below. + +Updating the *content* of an already-registered ConfigMap (e.g. rotating the CA) requires a +manual restart: + +```bash +kubectl -n cpaas-system rollout restart deploy/smart-doc +``` + +### Verify + +```bash +# The mounted CA and the merged bundle +kubectl -n cpaas-system exec deploy/smart-doc -c serve -- ls /opt/extra-ca/my-org-internal-ca/ +kubectl -n cpaas-system exec deploy/smart-doc -c serve -- grep -c 'BEGIN CERTIFICATE' /tmp/smart-doc-ca.pem + +# The startup log line +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep extra_ca +``` + +Expected log line: + +``` +extra_ca: merged 1/1 CA file(s) into /tmp/smart-doc-ca.pem +``` + +Then ask a question in the chat panel — requests to the endpoint that previously failed with +`CERTIFICATE_VERIFY_FAILED` should now succeed. + +## Advanced TLS settings + +The following settings have **no installation form field**. They are applied by patching the +plugin configuration (`ModuleInfo`) directly: + +```bash +# Find the ModuleInfo of the Hyperflux plugin (cluster-scoped, name like global-) +MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}') + +# Example: enforce the Intermediate TLS profile for outbound connections +kubectl patch moduleinfo "$MI" --type=merge -p \ + '{"spec":{"config":{"smartdoc":{"tlsProfileType":"IntermediateType"}}}}' +``` + +The platform reconciles the change and rolls the pods automatically. + +| Setting | Default | Description | +|---|---|---| +| `tlsProfileType` | `""` | Outbound TLS profile for LLM / MCP / PostgreSQL clients. `""` = library default; `IntermediateType` = TLS 1.2+, Mozilla intermediate ciphers; `ModernType` = TLS 1.3 only; `Custom` = use `tlsMinVersion` / `tlsCiphers` below. | +| `tlsMinVersion` | `""` | Minimum TLS version (`VersionTLS12` / `VersionTLS13`). Versions below TLS 1.2 are rejected. | +| `tlsCiphers` | `""` | Comma-separated OpenSSL cipher list, applied for non-TLS-1.3 profiles with `tlsProfileType: Custom`. | +| `pgSSLMode` | `""` | libpq `sslmode` for the PostgreSQL connection, e.g. `require`, `verify-ca`, `verify-full`. `""` leaves the connection string unchanged. | +| `pgSSLRootCert` | `""` | libpq `sslrootcert` — path to the CA file for PostgreSQL server verification. Must be a path readable inside the pod. | +| `securityHeadersEnabled` | `true` | Adds security response headers to the Alauda Hyperflux API. | +| `securityHSTSEnabled` | `true` | Adds the HSTS header (appropriate behind the TLS-terminating ingress). | + +### Skipping certificate verification (not recommended) + +`llmSkipSslVerify: true` disables TLS certificate verification for **LLM calls only** +(reranker, MCP and PostgreSQL are not affected). It overrides both the TLS profile and any +extra CA trust, and exposes the LLM connection to man-in-the-middle attacks — which is why it +is deliberately not offered in the installation form. Use it for test/development environments +only; the production-safe path for internal certificates is **Extra CA ConfigMaps** above. + +When enabled, every startup logs a warning: + +``` +LLM_SKIP_SSL_VERIFY=true — LLM TLS certificate verification is DISABLED (verify=False) +``` + +For external MCP servers there is an equivalent per-server `tls_verify: false` field — see +[Configure External MCP Servers](./configure-external-mcp.mdx), with the same caveat. diff --git a/docs/en/how-to/custom-skills.mdx b/docs/en/how-to/custom-skills.mdx new file mode 100644 index 0000000..a4ebc79 --- /dev/null +++ b/docs/en/how-to/custom-skills.mdx @@ -0,0 +1,126 @@ +--- +weight: 20 +--- + +# Create Custom Skills + +Skills are procedural prompts — step-by-step expert playbooks — that Alauda Hyperflux +automatically loads when a user's question matches. When a query hits a skill, the skill body is +injected into the agent's context so the answer follows your organization's procedure instead of +a generic one. + +Alauda Hyperflux ships with built-in troubleshooting skills (pod failure diagnosis, node +NotReady, ingress 5xx triage, PVC binding failure, routine inspection), active out of the box. +You can add your own skills via ConfigMaps; a custom skill with the same `name` as a built-in +one overrides it. + +## How matching works + +Each skill declares a `name` and a `description`. At startup they are embedded with the same +embedding model used by the knowledge base; at query time the user's question is compared +against them by cosine similarity. The single best match at or above the **Skills Match +Threshold** (default `0.35`) is injected; below the threshold nothing happens. + +Write the `description` accordingly: it is the matching surface. State what the skill diagnoses +and mention the phrases users are likely to use. + +## Write a skill file + +A skill is a Markdown file with YAML frontmatter: + +```markdown +--- +name: etcd-degraded +description: Diagnose an etcd cluster reporting degraded or unhealthy members. Use when the user reports etcd alerts, slow API server, or a control-plane node showing etcd errors. +--- + +# etcd Degraded Diagnosis + +1. List the etcd pods in `kube-system` and check their status and recent events. +2. Check member health: report which member is unhealthy and the specific error. +3. Correlate with node disk pressure or clock skew; cite the exact log line. +4. Recommend the remediation matching the identified cause; do not guess. +``` + +Rules: + +- `name` (required): must match `^[a-z][a-z0-9_-]*$`. Duplicate names within one scan: the first + file wins; a custom skill overrides a built-in skill of the same name. +- `description` (required): non-empty; drives matching. +- Body (required): everything after the frontmatter. Keep it under 4 KB — larger bodies still + load but log a warning and consume context on every match. +- Files that fail these rules are skipped with a WARN log; they never break the service. + +## Deploy skills via a ConfigMap + +Create a ConfigMap **in the namespace where Alauda Hyperflux is installed** (`cpaas-system`). +Every `*.md` data key is loaded as one skill: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-org-skills-sre + namespace: cpaas-system +data: + etcd-degraded.md: | + --- + name: etcd-degraded + description: Diagnose an etcd cluster reporting degraded or unhealthy members. Use when the user reports etcd alerts, slow API server, or a control-plane node showing etcd errors. + --- + + # etcd Degraded Diagnosis + + 1. List the etcd pods in `kube-system` and check their status and recent events. + 2. Check member health: report which member is unhealthy and the specific error. + 3. Correlate with node disk pressure or clock skew; cite the exact log line. + 4. Recommend the remediation matching the identified cause; do not guess. +``` + +Then in **Administrator / Marketplace / Cluster Plugins**, install or update the +`Alauda Hyperflux` plugin: + +- **Enable Skills**: on (default). +- **Skills Match Threshold**: keep `0.35` unless skills fire too eagerly (raise it) or never + match (lower it). +- **Skills ConfigMaps**: add the ConfigMap name, e.g. `my-org-skills-sre`. + +Each listed ConfigMap is mounted read-only at `/opt/skills//` and scanned +**once at startup**. Adding or removing a ConfigMap name in the form restarts the service +automatically; editing the content of an already-registered ConfigMap requires a manual restart: + +```bash +kubectl -n cpaas-system rollout restart deploy/smart-doc +``` + +## Verify + +Check the startup logs: + +```bash +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep '\[skills\]' +``` + +Expected on load: + +``` +[skills] loaded 6 skill(s) (built-in=5, admin=1 from /opt/skills), threshold=0.35, vec_dim=768 +``` + +Then ask a question in the chat panel that is semantically close to your skill's description. +On a hit the log shows the selected skill and its score: + +``` +[skills] selected name=etcd-degraded team=my-org-skills-sre score=0.62 query='...' +``` + +If a skill never matches, compare the logged scores against the threshold and rewrite the +`description` to be closer to how users actually phrase the question. + +Other notable log lines: + +| Log message | Meaning | +|---|---| +| `[skills] feature disabled (ENABLE_SKILLS=false)` | The Enable Skills toggle is off. | +| `[skills] enabled but no skills loaded` | No valid skill files were found — check WARN lines above it for per-file reasons. | +| `[skills] admin skill(s) override built-in: [...]` | Your custom skills replaced built-in skills of the same name. | diff --git a/docs/en/how-to/index.mdx b/docs/en/how-to/index.mdx new file mode 100644 index 0000000..58368ab --- /dev/null +++ b/docs/en/how-to/index.mdx @@ -0,0 +1,7 @@ +--- +weight: 17 +--- + +# How To + + diff --git a/docs/en/how-to/use-mcp-in-ide.mdx b/docs/en/how-to/use-mcp-in-ide.mdx new file mode 100644 index 0000000..232847d --- /dev/null +++ b/docs/en/how-to/use-mcp-in-ide.mdx @@ -0,0 +1,145 @@ +--- +weight: 40 +--- + +# Use Hyperflux as an MCP Server in Your IDE + +Alauda Hyperflux can expose itself as an MCP (Model Context Protocol) server, so AI coding +assistants — Claude Code, Cursor, VS Code Copilot, or any MCP-compatible agent — can ask it +Alauda product questions and inspect (or, with approval, operate) ACP clusters, directly from +the IDE. + +The MCP server exposes a single tool, `hyperflux_agent`, which delegates to the full Hyperflux +agent: knowledge-base retrieval plus cluster tools (clusters, projects, namespaces, nodes, pods, +resources, events, pod logs, metrics, alerts). It returns a grounded answer with citations. + +## Enable the MCP server + +In **Administrator / Marketplace / Cluster Plugins**, install or update the `Alauda Hyperflux` +plugin: + +- **Expose as MCP Server**: on (default off). +- **MCP Write-Approval Timeout (s)**: how long a mutating action waits for your approval in the + IDE before being treated as declined. Default `300`. Keep it below your ingress idle timeout, + otherwise the connection may be severed while waiting for approval. + +## The endpoint + +The MCP endpoint uses the streamable HTTP transport, at: + +``` +https:///smart-doc/mcp/ +``` + +> **NOTE:** The trailing slash matters. Requests to `/smart-doc/mcp` (without the slash) are +> answered with an HTTP 307 redirect that some MCP clients do not follow. + +## Authentication + +Two options; unauthenticated requests are rejected with HTTP 403. + +### Option A: ACP token (recommended) + +Send your ACP identity token as a bearer header: `Authorization: Bearer `. +You can obtain the token from a logged-in ACP Web Console session: open the browser developer +tools and copy the value of the `cpaas_id_token` cookie (strip the surrounding quotes and the +leading `Bearer ` prefix). + +This identifies you as a real user: with an MCP client that supports elicitation, mutating +actions become available behind interactive approval (see below). The token expires with your +ACP session, so refresh it when you start getting 403 responses. + +### Option B: API key (read-only, service-to-service) + +If an API key is configured in the Hyperflux credentials secret (`api-key` key), clients can +authenticate with the `x-api-key` header. The value is a self-signed HMAC token: + +``` +:: +``` + +where the signature is HMAC-SHA256 over the string `:` using the +shared API key: + +```bash +USER=; TS=$(date +%s) +SIG=$(printf '%s:%s' "$USER" "$TS" | openssl dgst -sha256 -hmac "$API_KEY" -hex | sed 's/^.* //') +echo "$USER:$TS:$SIG" +``` + +Tokens are only valid within 300 seconds of their timestamp, so they must be generated per +session — this scheme suits scripted/automated callers more than an IDE config file. +API-key sessions are **always read-only**: mutating actions are declined regardless of the +approval settings. + +## Configure your IDE + +Claude Code: + +```bash +claude mcp add --transport http hyperflux \ + "https:///smart-doc/mcp/" \ + --header "Authorization: Bearer " +``` + +Generic `mcp.json` (Cursor, VS Code, and most other MCP clients): + +```json +{ + "mcpServers": { + "hyperflux": { + "type": "http", + "url": "https:///smart-doc/mcp/", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +Then ask your assistant something like *"Using the hyperflux tool, check why pods in namespace +foo are not ready"*. The tool accepts a `question` plus optional `session_id` (to continue a +previous conversation), `cluster`, `namespace` and `project` hints. + +## Read-only vs. write actions + +What the agent may do through the IDE depends on the plugin's **Tool Approval Strategy** and +your MCP client: + +- With the default strategy `disabled`, the MCP tool is read-only for everyone — write tools + are removed from the agent entirely. +- With other strategies, mutating actions (create / update / delete / scale resources) are + available **only** when both hold: you authenticated with an ACP token (not an API key), and + your MCP client supports *elicitation*. Before executing a write, Hyperflux sends an approval + request that your IDE shows as a confirmation prompt; no answer within the configured timeout + counts as a decline, and a declined action is not re-asked within the same session. +- Clients without elicitation support (and all API-key sessions) get read-only behavior: write + attempts are declined with a "read-only MCP session" message, while reads keep working. + +## Troubleshooting + +Verify the endpoint end-to-end with curl: + +```bash +curl -sk -X POST "https:///smart-doc/mcp/" \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -H "Authorization: Bearer " \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' +``` + +A healthy server answers with `"serverInfo":{"name":"hyperflux",...}`. + +| Symptom | Cause | +|---|---| +| HTTP 403 | Authentication failed: missing/expired ACP token, or an API-key token outside its 300-second window / signed with the wrong key. | +| HTTP 404 | **Expose as MCP Server** is off, or the setting was changed without the pods restarting. | +| HTTP 307 | Missing trailing slash — use `/smart-doc/mcp/`. | +| Writes always declined | You authenticated with an API key, your client does not support elicitation, or the approval strategy is `disabled`. | +| Approval prompt disappears / connection drops during approval | The ingress idle timeout is shorter than the **MCP Write-Approval Timeout** — lower the timeout or raise the ingress limit. | + +Server-side logs (`kubectl -n cpaas-system logs -l app=smart-doc -c serve`) show +`Outbound MCP server mounted at /mcp` at startup when the feature is enabled, and +`MCP read-only session — blocked write tool ` when a write was declined due to a +read-only session. diff --git a/docs/en/install.mdx b/docs/en/install.mdx index bbf18bb..7f57f1b 100644 --- a/docs/en/install.mdx +++ b/docs/en/install.mdx @@ -162,11 +162,13 @@ Fill in the configurations below: - `never`: no approval, the LLM can call any tool unattended. **Use with caution in production.** - **Expose as MCP Server**: expose Alauda Hyperflux itself as an MCP server at `/mcp`, so IDEs and agents can call it as a tool. Read operations are always allowed; write actions require - interactive approval. Default off. + interactive approval. Default off. See + [Use Hyperflux as an MCP Server in Your IDE](./how-to/use-mcp-in-ide.mdx). - **MCP Write-Approval Timeout (s)**: max seconds to wait for a write-approval response before treating it as a decline. Default `300`. - **Extra MCP Servers ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) holding extra MCP server definitions; each ConfigMap's `*.yaml`/`*.yml`/`*.json` entries are scanned at startup. + See [Configure External MCP Servers](./how-to/configure-external-mcp.mdx). ### Skills @@ -174,7 +176,7 @@ Fill in the configurations below: - **Skills Match Threshold**: cosine threshold (0-1) for matching a query to a skill. Higher is stricter. Default `0.35`. - **Skills ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) whose `*.md` - entries are loaded as skills. + entries are loaded as skills. See [Create Custom Skills](./how-to/custom-skills.mdx). ### Rate and quota limits @@ -203,6 +205,7 @@ The defaults work for most cases; adjust only if needed. - **Extra CA ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) holding internal / self-signed CA certificates (PEM). The certificates are appended to the outbound TLS trust bundle, so LLM / MCP / reranker endpoints using such certificates can be accessed. + See [Configure TLS](./how-to/configure-tls.mdx). Click **Install** to start installation. From 700de86b86afe36bfe7bb74631e0f1da4bb26453 Mon Sep 17 00:00:00 2001 From: zlc Date: Thu, 9 Jul 2026 10:30:35 +0000 Subject: [PATCH 3/5] docs: add data redaction how-to guide Covers the three redaction parts, verified against server/src (regex_filter.py, redaction_audit.py, config.py) and the chart, with the audit endpoint exercised on a live deployment: - queryRedactionFilters value rules: schema (name/pattern/mode/ replace_with/applies_to), redact vs tokenize modes, MiConfig-only configuration with a ModuleInfo patch example, fail-fast validation and fail-closed application, rule-writing guidance. - toolArgRedactKeys key-name masking with the built-in safe set and its replace-not-extend override semantics. - Redaction audit: metadata-only records (values never stored), the admin-only /api/admin/redaction_audit query API (response shape verified live), best-effort writes and the missing-retention caveat. Co-Authored-By: Claude Fable 5 --- docs/en/how-to/configure-redaction.mdx | 144 +++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/en/how-to/configure-redaction.mdx diff --git a/docs/en/how-to/configure-redaction.mdx b/docs/en/how-to/configure-redaction.mdx new file mode 100644 index 0000000..40c24bd --- /dev/null +++ b/docs/en/how-to/configure-redaction.mdx @@ -0,0 +1,144 @@ +--- +weight: 50 +--- + +# Configure Data Redaction + +Alauda Hyperflux can redact sensitive values — internal IPs, tokens, passwords — before they +leave the service or get persisted. Redaction is opt-in and has three parts: + +- **Value rules** (`queryRedactionFilters`): regex rules applied to the user's question and + attachments, and to agent tool results, *before* the text is sent to the LLM and *before* it + is written to the conversation history. +- **Key-name redaction** (`toolArgRedactKeys`): tool-call arguments whose key name looks like a + credential (`password`, `token`, `api_key`, ...) are masked on approval cards and in the + approval audit records. +- **Redaction audit**: every rule hit is recorded (rule name and hit count — never the value + itself) and is queryable by platform administrators. + +> **NOTE:** Redaction is an input-side filter with the precision of your regex rules. A value +> that no rule matches still flows to the LLM and may appear in answers. Do not treat it as a +> guaranteed output filter. + +Both settings are **not** in the installation form. They are applied by patching the plugin +configuration (`ModuleInfo`), and take effect after the pods restart (the platform rolls them +automatically after a patch). + +## Value rules (`queryRedactionFilters`) + +Each rule is an object: + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | Rule label; shows up in logs and the audit records. | +| `pattern` | Yes | Regular expression (Python `re` syntax). | +| `mode` | No | `redact` (default) — replace the match with `replace_with`; or `tokenize` — replace the match with an opaque per-request token that is substituted back only when the value is passed to an actual tool execution, so the LLM never sees it but tools still receive the real value. | +| `replace_with` | For `redact` | Literal replacement text, e.g. `[REDACTED_IP]`. | +| `applies_to` | No | Surfaces the rule runs on: `query` (the user's question and attachments — the default) and/or `tool_result` (agent tool outputs before they are fed back to the LLM). | + +Example rule set: + +```json +[ + { + "name": "internal_ip", + "pattern": "\\b(?:10|127)\\.(?:\\d{1,3}\\.){2}\\d{1,3}\\b", + "replace_with": "[REDACTED_IP]", + "applies_to": ["query"] + }, + { + "name": "jwt", + "pattern": "eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+", + "replace_with": "[REDACTED_JWT]", + "applies_to": ["query", "tool_result"] + } +] +``` + +Apply it (the value is the JSON array as a **string**): + +```bash +MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}') +kubectl patch moduleinfo "$MI" --type=merge -p '{ + "spec": {"config": {"smartdoc": { + "queryRedactionFilters": "[{\"name\":\"internal_ip\",\"pattern\":\"\\\\b(?:10|127)\\\\.(?:\\\\d{1,3}\\\\.){2}\\\\d{1,3}\\\\b\",\"replace_with\":\"[REDACTED_IP]\",\"applies_to\":[\"query\"]}]" + }}} +}' +``` + +Validation is strict: a malformed JSON string fails the deployment render, and an invalid +individual rule (missing `name`/`pattern`, unknown `mode` or `applies_to`, uncompilable regex) +prevents the service from starting. Redaction itself is fail-closed — if applying the rules to +a request errors out, the turn is aborted rather than letting the raw text through. + +Writing rules well: + +- Rules run **sequentially in list order** on every request; an earlier rule's replacement text + is visible to later rules. Put broad rules last. +- Keep patterns narrow and anchored. Regex syntax is validated at startup, but catastrophic + backtracking is not — avoid nested quantifiers. +- Over-broad rules silently degrade answer quality (the LLM sees `[REDACTED_...]` instead of + the real value), which is why the feature ships empty by default. + +## Key-name redaction (`toolArgRedactKeys`) + +Independent of the value rules, tool-call arguments shown on approval cards and stored in the +approval audit are masked when the argument's key name contains one of the configured +substrings (case-insensitive). The tool itself still receives the real value. + +When unset, a built-in safe set applies: + +``` +password, passwd, secret, token, api_key, apikey, api-key, +authorization, credential, private_key, access_key, secret_key +``` + +Setting `toolArgRedactKeys` (comma-separated substrings) **replaces** this set — include the +defaults you want to keep. Setting it to an empty string does not disable the feature; the +default set applies again. + +## Redaction audit + +As soon as either setting above is configured, every rule hit is recorded in the +`redaction_audit` table of the conversation-history database: request id, session, username, +surface (`query` / `attachment` / `tool_result` / `tool_args`), rule name, mode, and hit count. +**The matched value is never stored.** + +Platform administrators (see **Admin Users** in the installation form) can query the records: + +``` +GET https:///smart-doc/api/admin/redaction_audit +``` + +Supported query parameters (all optional, ANDed): `username`, `session_id`, `request_id`, +`surface`, `rule_name`, `from`, `to`, plus `limit` (default 100, max 1000) and `offset`. +Non-admin callers receive 403. + +Two operational notes: + +- Audit writes are best-effort: a failed write is logged and dropped, never failing the user's + request. Do not treat the table as a guaranteed-complete compliance ledger. +- There is no automatic retention/cleanup for `redaction_audit` — prune it externally if your + deployment handles large volumes. + +## Verify + +Send a question containing a value your rule matches, then check the logs: + +```bash +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep 'redaction hits' +``` + +Expected (rule names and counts only, never values): + +``` +query redaction hits: {'internal_ip': 2} +tool-result redaction hits: {'jwt': 1} +``` + +And query the audit as an admin: + +```bash +curl -sk "https:///smart-doc/api/admin/redaction_audit?rule_name=internal_ip" \ + -H "Authorization: Bearer " +``` From 840b9e8f68d220516964086ce91dff7d0eee2ba6 Mon Sep 17 00:00:00 2001 From: zlc Date: Thu, 9 Jul 2026 15:09:31 +0000 Subject: [PATCH 4/5] docs(tls): replace advanced-settings table with a dedicated skip-TLS section Drop the Advanced TLS settings table (tlsProfileType/tlsMinVersion/ tlsCiphers/pgSSLMode/pgSSLRootCert/securityHeaders) and promote skipping certificate verification (llmSkipSslVerify) to its own section with the full ModuleInfo patch procedure, the LLM-only scope warning, and the revert step. External-PG TLS keeps a one-line pointer to pgSSLMode/ pgSSLRootCert in the extra-CA note. Co-Authored-By: Claude Fable 5 --- docs/en/how-to/configure-tls.mdx | 50 ++++++++++++++------------------ 1 file changed, 21 insertions(+), 29 deletions(-) diff --git a/docs/en/how-to/configure-tls.mdx b/docs/en/how-to/configure-tls.mdx index 85c1896..1d6d5b2 100644 --- a/docs/en/how-to/configure-tls.mdx +++ b/docs/en/how-to/configure-tls.mdx @@ -9,7 +9,8 @@ connections: the LLM service, the reranker, MCP servers and PostgreSQL. The most common need — trusting an LLM or MCP endpoint that uses an internal or self-signed certificate — is solved with **Extra CA ConfigMaps**, available directly in the installation -form. The remaining knobs are advanced settings applied by patching the plugin configuration. +form. For test environments, certificate verification for LLM calls can also be skipped +entirely (see the last section). ## Trust an internal / self-signed CA (Extra CA ConfigMaps) @@ -33,8 +34,9 @@ Each listed ConfigMap is mounted read-only at `/opt/extra-ca//`. certificates are merged with the default CA bundle and the merged bundle is applied process-wide, so it covers **LLM, reranker and MCP** connections. -> **NOTE:** PostgreSQL is the exception — it does not use this bundle. For TLS to an external -> PostgreSQL, see the `pgSSLMode` / `pgSSLRootCert` settings below. +> **NOTE:** PostgreSQL is the exception — it does not use this bundle. TLS to an external +> PostgreSQL is configured separately via the `pgSSLMode` / `pgSSLRootCert` values of the +> plugin configuration. Updating the *content* of an already-registered ConfigMap (e.g. rotating the CA) requires a manual restart: @@ -63,45 +65,35 @@ extra_ca: merged 1/1 CA file(s) into /tmp/smart-doc-ca.pem Then ask a question in the chat panel — requests to the endpoint that previously failed with `CERTIFICATE_VERIFY_FAILED` should now succeed. -## Advanced TLS settings +## Skip TLS certificate verification (not recommended) -The following settings have **no installation form field**. They are applied by patching the -plugin configuration (`ModuleInfo`) directly: +For test or development environments where importing the CA is not practical, TLS certificate +verification for **LLM calls** can be switched off entirely with `llmSkipSslVerify`. + +> **WARNING:** This exposes the LLM connection to man-in-the-middle attacks, and it overrides +> both the TLS profile and any extra CA trust — which is why it is deliberately not offered in +> the installation form. The production-safe path for internal certificates is +> **Extra CA ConfigMaps** above. The setting affects LLM calls only; reranker, MCP and +> PostgreSQL connections are not touched. + +Apply it by patching the plugin configuration (`ModuleInfo`) directly: ```bash # Find the ModuleInfo of the Hyperflux plugin (cluster-scoped, name like global-) MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}') -# Example: enforce the Intermediate TLS profile for outbound connections kubectl patch moduleinfo "$MI" --type=merge -p \ - '{"spec":{"config":{"smartdoc":{"tlsProfileType":"IntermediateType"}}}}' + '{"spec":{"config":{"smartdoc":{"llmSkipSslVerify":true}}}}' ``` -The platform reconciles the change and rolls the pods automatically. - -| Setting | Default | Description | -|---|---|---| -| `tlsProfileType` | `""` | Outbound TLS profile for LLM / MCP / PostgreSQL clients. `""` = library default; `IntermediateType` = TLS 1.2+, Mozilla intermediate ciphers; `ModernType` = TLS 1.3 only; `Custom` = use `tlsMinVersion` / `tlsCiphers` below. | -| `tlsMinVersion` | `""` | Minimum TLS version (`VersionTLS12` / `VersionTLS13`). Versions below TLS 1.2 are rejected. | -| `tlsCiphers` | `""` | Comma-separated OpenSSL cipher list, applied for non-TLS-1.3 profiles with `tlsProfileType: Custom`. | -| `pgSSLMode` | `""` | libpq `sslmode` for the PostgreSQL connection, e.g. `require`, `verify-ca`, `verify-full`. `""` leaves the connection string unchanged. | -| `pgSSLRootCert` | `""` | libpq `sslrootcert` — path to the CA file for PostgreSQL server verification. Must be a path readable inside the pod. | -| `securityHeadersEnabled` | `true` | Adds security response headers to the Alauda Hyperflux API. | -| `securityHSTSEnabled` | `true` | Adds the HSTS header (appropriate behind the TLS-terminating ingress). | - -### Skipping certificate verification (not recommended) - -`llmSkipSslVerify: true` disables TLS certificate verification for **LLM calls only** -(reranker, MCP and PostgreSQL are not affected). It overrides both the TLS profile and any -extra CA trust, and exposes the LLM connection to man-in-the-middle attacks — which is why it -is deliberately not offered in the installation form. Use it for test/development environments -only; the production-safe path for internal certificates is **Extra CA ConfigMaps** above. - -When enabled, every startup logs a warning: +The platform reconciles the change and rolls the pods automatically. When enabled, every +startup logs a warning: ``` LLM_SKIP_SSL_VERIFY=true — LLM TLS certificate verification is DISABLED (verify=False) ``` +To revert, patch the value back to `false`. + For external MCP servers there is an equivalent per-server `tls_verify: false` field — see [Configure External MCP Servers](./configure-external-mcp.mdx), with the same caveat. From e4bbcf7cd353ce94d7d06fbbb0e34faf62315ece Mon Sep 17 00:00:00 2001 From: zlc Date: Thu, 9 Jul 2026 15:28:31 +0000 Subject: [PATCH 5/5] docs(ide-mcp): drop the API-key auth option Remove the x-api-key HMAC scheme from the IDE guide (its 300-second token freshness makes it impractical for IDE config files, and it was the one path not exercised on a live deployment). ACP bearer token is now the single documented auth method; read-only/write and troubleshooting sections updated accordingly. Co-Authored-By: Claude Fable 5 --- docs/en/how-to/use-mcp-in-ide.mdx | 43 +++++++------------------------ 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/docs/en/how-to/use-mcp-in-ide.mdx b/docs/en/how-to/use-mcp-in-ide.mdx index 232847d..47bad5c 100644 --- a/docs/en/how-to/use-mcp-in-ide.mdx +++ b/docs/en/how-to/use-mcp-in-ide.mdx @@ -36,9 +36,7 @@ https:///smart-doc/mcp/ ## Authentication -Two options; unauthenticated requests are rejected with HTTP 403. - -### Option A: ACP token (recommended) +Unauthenticated requests are rejected with HTTP 403. Send your ACP identity token as a bearer header: `Authorization: Bearer `. You can obtain the token from a logged-in ACP Web Console session: open the browser developer @@ -49,29 +47,6 @@ This identifies you as a real user: with an MCP client that supports elicitation actions become available behind interactive approval (see below). The token expires with your ACP session, so refresh it when you start getting 403 responses. -### Option B: API key (read-only, service-to-service) - -If an API key is configured in the Hyperflux credentials secret (`api-key` key), clients can -authenticate with the `x-api-key` header. The value is a self-signed HMAC token: - -``` -:: -``` - -where the signature is HMAC-SHA256 over the string `:` using the -shared API key: - -```bash -USER=; TS=$(date +%s) -SIG=$(printf '%s:%s' "$USER" "$TS" | openssl dgst -sha256 -hmac "$API_KEY" -hex | sed 's/^.* //') -echo "$USER:$TS:$SIG" -``` - -Tokens are only valid within 300 seconds of their timestamp, so they must be generated per -session — this scheme suits scripted/automated callers more than an IDE config file. -API-key sessions are **always read-only**: mutating actions are declined regardless of the -approval settings. - ## Configure your IDE Claude Code: @@ -110,12 +85,12 @@ your MCP client: - With the default strategy `disabled`, the MCP tool is read-only for everyone — write tools are removed from the agent entirely. - With other strategies, mutating actions (create / update / delete / scale resources) are - available **only** when both hold: you authenticated with an ACP token (not an API key), and - your MCP client supports *elicitation*. Before executing a write, Hyperflux sends an approval - request that your IDE shows as a confirmation prompt; no answer within the configured timeout - counts as a decline, and a declined action is not re-asked within the same session. -- Clients without elicitation support (and all API-key sessions) get read-only behavior: write - attempts are declined with a "read-only MCP session" message, while reads keep working. + available **only** when your MCP client supports *elicitation*. Before executing a write, + Hyperflux sends an approval request that your IDE shows as a confirmation prompt; no answer + within the configured timeout counts as a decline, and a declined action is not re-asked + within the same session. +- Clients without elicitation support get read-only behavior: write attempts are declined with + a "read-only MCP session" message, while reads keep working. ## Troubleshooting @@ -133,10 +108,10 @@ A healthy server answers with `"serverInfo":{"name":"hyperflux",...}`. | Symptom | Cause | |---|---| -| HTTP 403 | Authentication failed: missing/expired ACP token, or an API-key token outside its 300-second window / signed with the wrong key. | +| HTTP 403 | Authentication failed: missing or expired ACP token. | | HTTP 404 | **Expose as MCP Server** is off, or the setting was changed without the pods restarting. | | HTTP 307 | Missing trailing slash — use `/smart-doc/mcp/`. | -| Writes always declined | You authenticated with an API key, your client does not support elicitation, or the approval strategy is `disabled`. | +| Writes always declined | Your client does not support elicitation, or the approval strategy is `disabled`. | | Approval prompt disappears / connection drops during approval | The ingress idle timeout is shorter than the **MCP Write-Approval Timeout** — lower the timeout or raise the ingress limit. | Server-side logs (`kubectl -n cpaas-system logs -l app=smart-doc -c serve`) show