|
| 1 | +{{ define "mintlify.install" -}} |
| 2 | +## Installing the chart |
| 3 | + |
| 4 | +To install this chart via the Helm chart repository: |
| 5 | + |
| 6 | +<Steps> |
| 7 | + <Step title="Add the Kosli helm repo"> |
| 8 | + ```shell |
| 9 | + helm repo add kosli https://charts.kosli.com/ && helm repo update |
| 10 | + ``` |
| 11 | + </Step> |
| 12 | + <Step title="Create a secret for the Kosli API token"> |
| 13 | + ```shell |
| 14 | + kubectl create secret generic kosli-api-token --from-literal=key=<your-api-key> |
| 15 | + ``` |
| 16 | + </Step> |
| 17 | + <Step title="Install the helm chart"> |
| 18 | + Configure **reporterConfig.environments** (required). Each entry has required `name` and optional `namespaces`, `namespacesRegex`, `excludeNamespaces`, `excludeNamespacesRegex`. Omit namespace fields for an entry to report the entire cluster to that environment. |
| 19 | + |
| 20 | + **One environment, entire cluster:** |
| 21 | + |
| 22 | + ```yaml |
| 23 | + # values.yaml |
| 24 | + reporterConfig: |
| 25 | + kosliOrg: <your-org> |
| 26 | + environments: |
| 27 | + - name: <your-env-name> |
| 28 | + ``` |
| 29 | + |
| 30 | + **One environment, specific namespaces:** |
| 31 | + |
| 32 | + ```yaml |
| 33 | + reporterConfig: |
| 34 | + kosliOrg: <your-org> |
| 35 | + environments: |
| 36 | + - name: <your-env-name> |
| 37 | + namespaces: [namespace1, namespace2] |
| 38 | + ``` |
| 39 | + |
| 40 | + **Multiple environments with different selectors:** |
| 41 | + |
| 42 | + ```yaml |
| 43 | + reporterConfig: |
| 44 | + kosliOrg: <your-org> |
| 45 | + environments: |
| 46 | + - name: prod-env |
| 47 | + namespaces: [prod-ns1, prod-ns2] |
| 48 | + - name: staging-env |
| 49 | + namespacesRegex: ["^staging-.*"] |
| 50 | + - name: infra-env |
| 51 | + excludeNamespaces: [prod-ns1, prod-ns2, default] |
| 52 | + ``` |
| 53 | + |
| 54 | + ```shell |
| 55 | + helm install kosli-reporter kosli/k8s-reporter -f values.yaml |
| 56 | + ``` |
| 57 | + </Step> |
| 58 | +</Steps> |
| 59 | + |
| 60 | +<Note>Chart source can be found at [GitHub](https://github.com/kosli-dev/cli/tree/main/charts/k8s-reporter).</Note> |
| 61 | + |
| 62 | +<Info>See all available [configuration options](#configurations) below.</Info> |
| 63 | + |
| 64 | +{{- end }} |
| 65 | + |
| 66 | +{{ define "mintlify.customCA" -}} |
| 67 | +## Running behind a TLS-inspecting proxy (corporate / custom CA bundle) |
| 68 | + |
| 69 | +If your network sits behind a TLS-inspecting appliance (Zscaler, Netskope, Palo Alto, etc.) that re-signs HTTPS traffic with a corporate CA certificate, the reporter will fail with `x509: certificate signed by unknown authority`. To fix this, make the appliance's CA bundle available to the reporter. |
| 70 | + |
| 71 | +The chart offers two ways to do this. Use whichever fits your deployment flow. |
| 72 | + |
| 73 | +### Option 1 — customCA convenience wrapper (recommended for the common case) |
| 74 | + |
| 75 | +<Steps> |
| 76 | + <Step title="Create a Secret containing the corporate CA certificate"> |
| 77 | + PEM format, single cert or bundle: |
| 78 | + |
| 79 | + ```shell |
| 80 | + kubectl create secret generic corporate-ca-bundle --from-file=ca.crt=/path/to/corporate-ca.crt |
| 81 | + ``` |
| 82 | + </Step> |
| 83 | + <Step title="Enable the wrapper in values.yaml"> |
| 84 | + ```yaml |
| 85 | + customCA: |
| 86 | + enabled: true |
| 87 | + secretName: corporate-ca-bundle |
| 88 | + key: ca.crt |
| 89 | + ``` |
| 90 | + </Step> |
| 91 | +</Steps> |
| 92 | + |
| 93 | +The chart mounts the certificate as a single file at `/etc/ssl/certs/kosli-custom-ca.crt` using `subPath`. Go's standard library on Linux loads CA roots in two independent passes — it reads the system bundle file (e.g. `/etc/ssl/certs/ca-certificates.crt`) and **also** scans `/etc/ssl/certs/` for additional certificate files. The mounted file is picked up by the directory scan and added to the trust store alongside the system roots, so no `SSL_CERT_FILE` env var is needed. |
| 94 | + |
| 95 | +The wrapper deliberately does **not** set `SSL_CERT_FILE`. Setting it would replace the system bundle entirely with the customer's file, breaking trust for any public CAs the bundle does not include. |
| 96 | + |
| 97 | +### Option 2 — generic extraVolumes / extraVolumeMounts / extraEnvVars |
| 98 | + |
| 99 | +Use these when you need a non-default mount path, a ConfigMap instead of a Secret, multiple volumes, or any other shape the wrapper does not cover: |
| 100 | + |
| 101 | +```yaml |
| 102 | +extraVolumes: |
| 103 | + - name: corporate-ca |
| 104 | + secret: |
| 105 | + secretName: corporate-ca-bundle |
| 106 | +
|
| 107 | +extraVolumeMounts: |
| 108 | + - name: corporate-ca |
| 109 | + mountPath: /etc/ssl/certs/corporate |
| 110 | + readOnly: true |
| 111 | +``` |
| 112 | + |
| 113 | +<Warning> |
| 114 | +If you mount the CA outside `/etc/ssl/certs/` and set `SSL_CERT_FILE` via `extraEnvVars`, your bundle must include the public CAs you also need to trust — Go uses only that file when `SSL_CERT_FILE` is set. |
| 115 | +</Warning> |
| 116 | + |
| 117 | +### Pod Security Standards |
| 118 | + |
| 119 | +Both options use `secret`-backed volumes, which are permitted under the Pod Security Standards `restricted` profile. `hostPath` mounts are not permitted under that profile and should not be used here. |
| 120 | + |
| 121 | +### Cluster-wide alternative |
| 122 | + |
| 123 | +If you already run [cert-manager's trust-manager](https://cert-manager.io/docs/trust/trust-manager/) to distribute a corporate CA bundle into a well-known ConfigMap in every namespace, point `extraVolumes` / `extraVolumeMounts` at that ConfigMap instead of creating a per-namespace Secret. |
| 124 | +{{- end }} |
| 125 | + |
1 | 126 | {{ define "mintlify.versionInfo" -}} |
2 | 127 | <Info> |
3 | 128 | This reference applies to **chart version {{ .Version }}**, which defaults to CLI **{{ .AppVersion }}** via `appVersion`. Override with `image.tag`. |
@@ -92,6 +217,10 @@ This reference applies to **chart version {{ .Version }}**, which defaults to CL |
92 | 217 | {{ define "mintlify.paramField" -}} |
93 | 218 | {{- $d := .Default | trimPrefix "`" | trimSuffix "`" -}} |
94 | 219 | {{- $desc := or .Description .AutoDescription -}} |
| 220 | +{{- if $desc -}} |
| 221 | +{{- $desc = printf "%s%s" (substr 0 1 $desc | upper) (substr 1 -1 $desc) -}} |
| 222 | +{{- if not (hasSuffix "." $desc) -}}{{- $desc = printf "%s." $desc -}}{{- end -}} |
| 223 | +{{- end -}} |
95 | 224 | {{- if or (and (eq .Type "object") (ne $d "{}")) (and (eq .Type "list") (ne $d "[]")) }} |
96 | 225 | <ParamField path="{{ .Key }}" type="{{ .Type }}"> |
97 | 226 | {{ $desc }} |
|
0 commit comments