Internal CA

The certificate core serves — terminated by native TLS or by a reverse proxy/Ingress in front of it — is already trusted by browsers once your organization's CA is distributed there. But three clients don't use the operating system's trust store and can't verify that certificate on their own: the agent (runs inside the cluster), Shell (the toolbox shell opened from the browser, and the kubectl/helm inside it), and the CLI (yeke login/port-forward). For these three, the only way to skip verification used to be a flag like -k/--insecure/ NODE_TLS_REJECT_UNAUTHORIZED=0; this page describes what replaces it.

As long as YEKE_PUBLIC_CA_FILE is not set, behavior is byte-for-byte unchanged from today: core distributes no CA, and the install manifest, the shell preamble and the install command are all unchanged.

The value is a file path — not the PEM itself, the same pattern as YEKE_LICENSE_PATH. Mount the file read-only into compose, readable by the user core runs as (65532):

    environment:
      YEKE_PUBLIC_CA_FILE: /etc/yeke/public-ca.crt
    volumes:
      - ./yeke-ca.crt:/etc/yeke/public-ca.crt:ro

• One or more PEM certificates — at least one must be self-signed (a root). A file that only carries an intermediate certificate makes core fail to start: Node.js clients (the agent, the CLI) cannot anchor trust on an intermediate. A self-signed server certificate is its own root and can be placed in the file directly.
• Up to 16 roots are accepted — the tunnel protocol's wire limit. A larger file (typically the operating system's full public certificate bundle) is also rejected.
• If the mount is missing or the permissions don't match, core does not start; the error names the file path, the environment variable, and the expected user (65532).

Core does not obtain or renew this file — like the certificate, your organization provides the CA. The same variable applies in a Kubernetes/HA install too; the difference there is mounting the file via a ConfigMap (that path was not measured, see below).

• 1 · A "Download the CA" link appears above the command box — GET /api/public-ca, which requires a session (not because the CA is secret, but so install configuration isn't served from an unauthenticated endpoint); the file downloads as yeke-ca.crt.
• 2 · The command on screen switches to the piped-ca form — curl verifies core's certificate against the CA while downloading the manifest; verification is never skipped at any step:
  curl -fsSL --cacert yeke-ca.crt "<the ticket URL shown on screen>" | kubectl apply -f -

  Download the CA file into the directory you'll run the command from before running it.
• 3 · piped-insecure no longer appears on screen. Offering a form that skips verification when a verified path already exists would hand the user a security decision through the "easy" option.

The direct form (kubectl apply -f <URL>) stays on screen: it works if your operating system already trusts the CA (common with corporate GPO/MDM); if it doesn't, kubectl says x509: certificate signed by unknown authority — use piped-ca instead.

Once core restarts and starts distributing the CA, any agent that doesn't yet carry it shows an agent · core CA missing chip on its inventory row — this is not a version warning, it can appear even when versions already match. If more than one cluster is affected, an "Update agents (N)" button appears above the inventory.

The button builds a three-step plan under one approval card:

• ClusterRole — if permissions are already current, this step says "no change".
• ConfigMap/yeke-core-ca — carries core's CA; created if missing, its content updated if it already exists (during rotation).
• Deployment — adds a YEKE_CORE_CA_FILE=/etc/yeke/core-ca/ca.crt environment variable to the agent container and a volume that mounts the ConfigMap read-only.

After you apply, the pod restarts (a rollout), the tunnel drops for a moment and comes back with the CA added to its trusted roots, and the chip clears on its own.

You don't configure Shell separately: while opening a shell session, core delivers the CA to the shell itself, over the same verified channel as the ticket — the terminal's preamble — and the shell writes it into that session's own kubeconfig. The script that reads this mechanism shipped with the v4 toolbox image: a v3-based image still opens the shell, but the kubectl/helm inside it keeps giving an x509 error as it does today.

If you build your own toolbox image for persistent tools or an air-gapped setup, use FROM nairotech/yeke-toolbox:v4. You don't need to add anything to the image for core's own CA — it's written into the session, not the image; adding a CA to the image only matters for other internal endpoints reached from the shell (a Helm repository, an artifact server).

yeke login https://yeke.example.com --ca-file root-ca.pem

The file's content (not its path) is written to ~/.config/yeke/config.json; later commands (port-forward included) read it from there — nothing breaks if the file is later moved or deleted. Running login without a CA, against a core whose certificate is signed by your organization's CA, now names the cause and the fix instead of today's unclear error:

Cannot verify the certificate of https://yeke.example.com: SELF_SIGNED_CERT_IN_CHAIN.
If YEKE uses a certificate signed by your organization's CA, run: yeke login https://yeke.example.com --ca-file <root-ca.pem>

A CA is added to each client's trusted roots, never replaces them. That's why, once the CA is distributed, clients keep connecting even while core still serves the old certificate; change the certificate before distributing the CA, and the agent tunnel drops, Shell won't open, and the install command gives an x509 error.

• 1 · Write the old and new root into the file together, then restart core. The CA file is only read at startup — there's no live reload. Every affected cluster's inventory row shows a chip and "Update agents (N)" appears.
• 2 · Apply with "Update agents (N)". This step only changes the ConfigMap — the Deployment isn't touched, so the pod doesn't restart. Kubernetes delivers a ConfigMap update to the pod with a delay (anywhere from 30 seconds to a few minutes); change the certificate only after that.
• 3 · Move the certificate to the new root. The tunnel drops for a moment and comes back; the chip clears on its own. If you change the certificate too early, the agent gives a brief x509 error and recovers on its own, since it re-reads the file on every connection attempt.
• 4 · Once every chip has cleared, remove the old root from the file and restart core again. The old root left behind in agents' ConfigMaps is harmless — the agent skips it once it expires.

The first migration from a public certificate to a corporate CA follows the same order. If you did it in the wrong order and dropped the tunnel, the way back is to regenerate the agent's install manifest (via a token rotation) and run kubectl apply again.

Clusters in restricted-access mode can't be assumed to grant ConfigMap write access, so neither the CA-missing chip nor the update button appears — the same is already true for version updates today. Here the path is manual: after giving core a CA, rotate the agent's token; the regenerated install manifest (it still carries the ConfigMap, environment variable and mount) is applied by the cluster's administrator with kubectl apply, and the agent connects with the new token and the CA. The certificate is changed only after that — rotation follows the same path.

• Hook and AI provider egress are not carried by this variable. Trusting core's own certificate and core's trust in third parties (ITSM, an AI provider) are separate subjects.
• Not measured: the repository's compose file itself; combined use with native TLS; mounting the CA file via a ConfigMap in a Kubernetes/HA install; Windows clients; whether the direct install form works with a CA installed in the operating system's own certificate store.