|
| 1 | +--- |
| 2 | +title: Configuring Istio Ingress |
| 3 | +type: docs |
| 4 | +weight: 1 |
| 5 | +--- |
| 6 | + |
| 7 | +UDS Core leverages Istio for ingress into the service mesh. This document provides an overview and examples of the Istio resources that UDS Core deploys to handle ingress. |
| 8 | + |
| 9 | +## Gateways |
| 10 | + |
| 11 | +UDS Core provides a few Istio [Gateway](https://istio.io/latest/docs/reference/config/networking/gateway/) resources to allow ingress into the service mesh. Each one serves a different purpose and can be used to route traffic to different services. |
| 12 | + |
| 13 | +1. **(Required)** Tenant Gateway - This gateway provides ingress to typical end-user applications. By default, UDS Core deploys a few services on this gateway, such as the Keycloak SSO portal. This gateway is typically exposed to end users of the applications deployed on top of UDS Core. |
| 14 | +2. **(Required)** Admin Gateway - This gateway provides ingress to admin-related applications that are not for use by the default end user. By default, UDS Core deploys a few services on this gateway, such as the Admin Keycloak interface. This gateway is typically accessible to admins of the applications deployed on top of UDS Core. *Since the Admin and Tenant Gateways are logically separated, it is possible to have different security controls on each gateway.* |
| 15 | +3. **(Optional)** Passthrough Gateway - This gateway allows mesh ingress without TLS termination performed by Istio. This could be useful for applications that need to (or currently) handle their own TLS termination. This gateway used to be a default component of UDS Core but is no longer deployed by default. To deploy this gateway, you must specify `istio-passthrough-gateway` as an `optionalComponent` in your UDS Bundle configuration. |
| 16 | + |
| 17 | +### Enable Passthrough Gateway |
| 18 | + |
| 19 | +In order to enable the Passthrough Gateway, you must specify `istio-passthrough-gateway` as an `optionalComponent` in your UDS Bundle configuration. Here is an example of how to do this: |
| 20 | + |
| 21 | +```yaml |
| 22 | +kind: UDSBundle |
| 23 | +metadata: |
| 24 | + name: core-with-passthrough |
| 25 | + description: A UDS example bundle for packaging UDS core with the passthrough gateway enabled |
| 26 | + version: "0.0.1" |
| 27 | + |
| 28 | +packages: |
| 29 | + - name: core |
| 30 | + repository: oci://ghcr.io/defenseunicorns/packages/uds/core |
| 31 | + ref: 0.23.0-upstream |
| 32 | + # You must specify the istio-passthrough-gateway as an optionalComponent or else it will not be deployed |
| 33 | + optionalComponents: |
| 34 | + - istio-passthrough-gateway |
| 35 | +``` |
| 36 | +
|
| 37 | +### Configure Domain Name and TLS for Istio Gateways |
| 38 | +
|
| 39 | +By default, the UDS Core Istio Gateways are set up to use the `uds.dev` domain and have a valid TLS certificate packaged. You will want to change the domain name for your environment and provide a valid TLS certificate for this domain. |
| 40 | + |
| 41 | +You can set the TLS certs via overrides in a [UDS Bundle](https://uds.defenseunicorns.com/bundles/) (see below). |
| 42 | + |
| 43 | +```yaml |
| 44 | +kind: UDSBundle |
| 45 | +metadata: |
| 46 | + name: core-with-cert-override |
| 47 | + description: A UDS example bundle for packaging UDS core with a custom TLS certificate |
| 48 | + version: "0.0.1" |
| 49 | + |
| 50 | +packages: |
| 51 | + - name: core |
| 52 | + repository: oci://ghcr.io/defenseunicorns/packages/uds/core |
| 53 | + ref: 0.23.0-upstream |
| 54 | + overrides: |
| 55 | + istio-admin-gateway: |
| 56 | + uds-istio-config: |
| 57 | + variables: |
| 58 | + - name: ADMIN_TLS_CERT |
| 59 | + description: "The TLS cert for the admin gateway (must be base64 encoded)" |
| 60 | + path: tls.cert |
| 61 | + - name: ADMIN_TLS_KEY |
| 62 | + description: "The TLS key for the admin gateway (must be base64 encoded)" |
| 63 | + path: tls.key |
| 64 | + istio-tenant-gateway: |
| 65 | + uds-istio-config: |
| 66 | + variables: |
| 67 | + - name: TENANT_TLS_CERT |
| 68 | + description: "The TLS cert for the tenant gateway (must be base64 encoded)" |
| 69 | + path: tls.cert |
| 70 | + - name: TENANT_TLS_KEY |
| 71 | + description: "The TLS key for the tenant gateway (must be base64 encoded)" |
| 72 | + path: tls.key |
| 73 | +``` |
| 74 | + |
| 75 | +You can then either use environment variables (`UDS_ADMIN_TLS_CERT`, `UDS_ADMIN_TLS_KEY`, `UDS_TENANT_TLS_CERT`, and `UDS_TENANT_TLS_KEY`) or a config file to configure the certs for each gateway. These values should be base64 encoded strings of the TLS certificate and key for the admin and tenant gateways respectively. |
| 76 | + |
| 77 | +Domain should be set via your [uds-config](https://uds.defenseunicorns.com/cli/quickstart-and-usage/#variables-and-configuration) file using the shared key to override the Zarf Domain Variable (see example `uds-config.yaml` below). |
| 78 | + |
| 79 | +```yaml |
| 80 | +shared: |
| 81 | + domain: yourawesomedomain.com # shared across all packages in a bundle |
| 82 | +
|
| 83 | +# TLS Certs/Keys if not provided via environment variables |
| 84 | +variables: |
| 85 | + core: |
| 86 | + admin_tls_cert: # base64 encoded admin cert here |
| 87 | + admin_tls_key: # base64 encoded admin key here |
| 88 | + tenant_tls_cert: # base64 encoded tenant cert here |
| 89 | + tenant_tls_key: # base64 encoded tenant key here |
| 90 | +``` |
0 commit comments