# Repo map — Istio

Ground truth for the course. Paths are from the repo root. Line numbers drift — treat them as
"look near here." **Istio version pinned: 1.18.5** (`deployments/helm/platforms/istio/skaffold.yaml`).

---

## 0. The one fact that reframes the course

This mesh is used for **traffic routing + edge TLS + telemetry** — *not* in-mesh
mTLS/zero-trust. Specifically (survey-verified):
- **No `PeerAuthentication`** anywhere; **no backend `AuthorizationPolicy`/`RequestAuthentication`**.
- `enableAutoMtls: false` in base/stag/prod (`istiod-values.yaml:13`; only local = true).
- `outboundTrafficPolicy.mode: ALLOW_ANY` (egress to unknown hosts allowed).
- Auth is done **in-app** (token → gRPC metadata), at the edge, not by Istio.

So Part 3 teaches mTLS/AuthorizationPolicy as *Istio capabilities* (cert-relevant) while being
honest that this repo opts out — a real, defensible architecture.

---

## 1. VirtualService — the object factory *(Lesson 4)*
All backend Istio objects come from macros in **one file**:
<span class="filepath">deployments/helm/libs/util/templates/_hosts.tpl</span> (VS + DR + CORS).
- `virtualservice.api.tpl` <span class="filepath">_hosts.tpl:96-112</span> — `kind: VirtualService`
  named `<Chart>-api`, `hosts: .Values.global.dnsNames.api`, `gateways:
  istio-system/<env>-<vendor>-gateway` (`:105`), dumps `.Values.apiHttp` under `http:`.
- `virtualservice.web.tpl` <span class="filepath">_hosts.tpl:114-145</span> — grpc-web, adds
  per-route `corsPolicy`; `virtualservice.admin.tpl` `:147-182` (supports `mirror`, `rewrite`).
- CORS: `corsPolicy` `_hosts.tpl:1-29`, `adminCorsPolicy` `:31-66`.
- **Wiring:** `util.app` gates on the values — <span class="filepath">deployments/helm/backend/tom/templates/util/_app.tpl:26-33</span>
  (`virtualservice.api.tpl` if `.Values.apiHttp`, `.web.tpl` if `.Values.webHttp`). Every backend
  service does this. (There's a *separate* standalone `virtualservice-0.1.0.tgz` chart used only
  by a few platform/frontend services — not backend.)

**Route tables (values):** <span class="filepath">deployments/helm/backend/bob/values.yaml</span>
— `apiHttp:` `:41-96` (routes with `match.uri.prefix`/`exact`, `route.destination.host: bob`
port 5050, a cross-service route to `notificationmgmt:6950`, and a `fault.abort` returning 403
@100% to block Internal RPCs from the edge, `:42-46`); `webHttp:` `:168+`; `adminHttp:` `:1-17`
→ `bob-hasura:8080`, `adminHttpV2:` with `rewrite.uri: /` `:22-23`. **No `timeout`/`retries`**
in the route tables — they rely on Envoy defaults.

## 2. Gateway — the ingress edge *(Lesson 5)*
<span class="filepath">deployments/helm/platforms/gateway/templates/gateway.yaml</span> —
`selector: istio: ingressgateway` (`:8-9`), name `<env>-<vendor>-gateway` (helper
<span class="filepath">gateway/templates/_helpers.tpl:13-24</span>) = the exact ref backend VSes
point at. `servers` per domain, all `HTTPS`, `tls.mode: SIMPLE`, `credentialName: cert-*`, SDS:
web-api ports 31400+443 (`:12-40`), grpc-api 31500+443 (`:42-71`), admin 31600+443 (`:73-102`),
plus backoffice/teacher/learner/grafana/kiali/… blocks. Cloudflare front:
`gateway-cloudflare.yaml:32-72` (HTTP:80 `httpsRedirect: true` → HTTPS:443). **TLS terminates at
the ingress gateway** (cert-manager `Certificate` + SDS). LB Service ports (80/443/31400/31500/
31600 + 15021) in <span class="filepath">platforms/istio/gateway-values.yaml:5-38</span>.

## 3. DestinationRule *(Lesson 6)*
- `util.destinationrule.api.tpl` <span class="filepath">_hosts.tpl:68-80</span> — `host:
  .Values.service.grpcHost`, `trafficPolicy.portLevelSettings[…].port.number: .Values.service.port`,
  splices `.Values.trafficPolicy` (`:79`). Web variant `:82-94`.
- **Hand-written consumer:** <span class="filepath">deployments/helm/backend/tom/templates/destinationrule.yaml:1-3</span>
  (`include "util.destinationrule.api.tpl"`). Tom is nearly the only backend service that ships
  one. It sets `trafficPolicy.loadBalancer.consistentHash.httpHeaderName: x-chat-userhash`
  (<span class="filepath">tom/values.yaml:67-70</span>) → **session affinity by chat-user hash**
  (tom holds websocket/chat state). No connectionPool/outlierDetection/tls set.

## 4. mTLS / security — what's NOT here *(Lessons 9–10)*
- **No `PeerAuthentication`, no backend `AuthorizationPolicy`/`RequestAuthentication`** (grep = 0).
- Mesh mTLS off: <span class="filepath">platforms/istio/istiod-values.yaml:13</span>
  `enableAutoMtls: false` (base/stag/prod; only `istiod-local-values.yaml:22` = true).
- The only Authz/ReqAuth objects are **platform/monitoring**, not backend:
  `platforms/atlantis/authz.yaml` (RequestAuthentication + AuthorizationPolicy) and
  `platforms/monitoring/{env}-gateway.yaml` (JWT guarding Grafana/monitoring ingress).

## 5. EnvoyFilter — the Lua escape hatch *(Lesson 8)*
Generated by util macros, included by every service:
- `util.http.envoyfilter.salesforce` <span class="filepath">libs/util/templates/_app_envoyfilter_salesforce.tpl:1-92</span>
  — a `SIDECAR_INBOUND` **Lua** filter: for requests with `X-Salesforce-Domain`, calls
  `auth` `/auth/api/v1/exchange_named_credential_jwt` and swaps the `Authorization` header
  (`:59-82`); adds security headers on response. Wired via `_app.tpl:24`.
- `util.hasura.envoyfilter` <span class="filepath">libs/util/templates/_hasura_envoyfilter.tpl</span>
  — Lua on the hasura sidecar for activity-log capture. Plus a Salesforce hasura variant.

## 6. Sidecar injection — revision-based *(Lesson 2)*
- **No `istio-injection=enabled` label** anywhere. Injection is **revision-based**: istiod
  `revision: 1-18-5` with `revisionTags: stable` (prod
  <span class="filepath">istiod-prod-values.yaml:62-63</span>) / `local`; `defaultRevision:
  1-18-5` on istio-base (<span class="filepath">platforms/istio/skaffold.yaml:16</span>). A
  namespace opts in via `istio.io/rev=stable`.
- **Sidecar tuning** via pod annotations <span class="filepath">libs/util/templates/_workload_metadata.tpl:16-17</span>
  (`sidecar.istio.io/proxyCPU: 10m`, `proxyMemory: 50Mi`; overridable per service).
- **Opt-OUT** `sidecar.istio.io/inject: "false"` on gandalf stub/ci
  (<span class="filepath">backend/gandalf/templates/deployment.yaml:20,77</span>), jobs, cronjobs,
  migration hooks, caching, hasura helpers.
- **`Sidecar` egress allow-list:** <span class="filepath">platforms/gateway/templates/sidecar.yaml:1-33</span>
  — only prod/dorp tokyo|jprep backend namespaces; restricts egress hosts (`./*`,
  `istio-system/*`, siblings, `keda/*`, `monitoring/*`).

## 7. Istio installation *(Lesson 1)*
<span class="filepath">deployments/helm/platforms/istio/skaffold.yaml</span> — 3 Helm releases
from vendored tarballs (plus CNI): **istio-base** (`base-1.18.5.tgz`, ns `istio-system`,
`:5-16`), **istiod-1-18-5** (`istiod-1.18.5.tgz`, `revision: 1-18-5`, `:30-44`),
**istio-ingressgateway** (`gateway-1.18.5.tgz`, `:85-99`), `cni-1.18.5.tgz`. **No IstioOperator**
— plain upstream Helm. `meshConfig` (<span class="filepath">istiod-values.yaml:10-21</span>):
`outboundTrafficPolicy: ALLOW_ANY`, `enableAutoMtls: false`, JSON access logs, Zipkin tracing →
`opentelemetry-collector.monitoring:9411` @100% sampling, `holdApplicationUntilProxyStarts: true`.
Prod pilot `replicaCount: 5`.

## 8. ServiceEntry / Sidecar *(Lesson 12)*
- **ServiceEntry:** only <span class="filepath">platforms/gateway/templates/service-entry.yaml</span>
  — prod-tokyo cross-cluster reach to renseikai/ga (`MESH_EXTERNAL`, STATIC, `:1-21`),
  synersia→tokyo admin (`:51-79`), each paired with a DR doing `tls.mode: SIMPLE` + `sni`.
- **Sidecar:** only the egress allow-list (topic 6). **No WorkloadEntry.**

## 9. Telemetry → Prometheus → KEDA *(Lesson 11)*
- **No `Telemetry` CRD.** Metrics come from the Envoy sidecar's built-in Prometheus stats
  (`enablePrometheusMerge`), scraped via `prometheus.io/scrape` annotation. Prometheus job
  `kubernetes-pods` <span class="filepath">platforms/monitoring/prometheus/values.yaml:424-462</span>;
  annotations from <span class="filepath">_workload_metadata.tpl:24-26</span>. Alert rules query
  `istio_requests_total` directly (`prometheus/values.yaml:793-836`).
- **KEDA tie:** <span class="filepath">libs/util/templates/_keda.tpl:146-154</span> —
  `query: sum(rate(istio_requests_total{destination_service_namespace=…,destination_service_name=…}[2m]))`,
  `serverAddress: http://prometheus-server.monitoring…`. The metric originates from the
  destination pod's Istio sidecar (Course 2 L9).

## 10. gandalf vs the ingress — the correction *(Lesson 5)*
**gandalf is NOT the ingress gateway.** The ingress is `istio-ingressgateway` (topic 2).
gandalf's chart deploys only a **test/BDD harness**: `gandalf-stub` (runs `/stub`) and
`gandalf-ci` (runs `sleep infinity` for BDD), both `sidecar.istio.io/inject: "false"` (outside
the mesh), ClusterIP only, and **no VirtualService/Gateway routes to it**
(<span class="filepath">backend/gandalf/templates/deployment.yaml:20,44,77,122</span>). The
"gandalf = API gateway" phrase is the **grpc-gateway transcoding** convention (spike &
notificationmgmt mount a grpc-gateway ServeMux; gRPC course). Real request path:
**client → istio-ingressgateway (TLS terminate) → per-service VirtualService (apiHttp/webHttp) →
service pod (in-app grpc-gateway REST↔gRPC)**. gandalf is the integration-test client, off to the side.

---

## Anchors cheat-list

| Thing | Where |
|---|---|
| VS/DR/CORS factory | `libs/util/templates/_hosts.tpl` |
| VirtualService api macro | `_hosts.tpl:96-112` (gateways `istio-system/<env>-<vendor>-gateway`) |
| Route tables (values) | `backend/bob/values.yaml` (`apiHttp:41`, `webHttp:168`, `adminHttp:1`) |
| Internal-RPC edge block | `bob/values.yaml:42-46` (`fault.abort` 403) |
| DestinationRule macro | `_hosts.tpl:68-80`; consumer `tom/templates/destinationrule.yaml` |
| tom session affinity | `tom/values.yaml:67-70` (`consistentHash` on `x-chat-userhash`) |
| Ingress Gateway | `platforms/gateway/templates/gateway.yaml` (SIMPLE TLS, `<env>-<vendor>-gateway`) |
| EnvoyFilter (Salesforce Lua) | `libs/util/templates/_app_envoyfilter_salesforce.tpl` (via `_app.tpl:24`) |
| Injection (revision) | `platforms/istio/skaffold.yaml:16` (`defaultRevision: 1-18-5`) |
| Sidecar tuning annotations | `_workload_metadata.tpl:16-17` |
| mTLS OFF | `istiod-values.yaml:13` (`enableAutoMtls: false`) |
| istio_requests_total → KEDA | `_keda.tpl:146-154` |
| gandalf = test harness (not ingress) | `backend/gandalf/templates/deployment.yaml:20,77` |
| Istio version | `platforms/istio/skaffold.yaml` (1.18.5) |