> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qodo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure ingress

> Choose customer-managed ingress, DNS, and TLS patterns for Qodo on AWS, Google Cloud, Azure, or OpenShift.

* **Deployment model**: On-premises
* **Configuration reference**: Qodo Helm chart `7.22.0`, product `3.0`.

Use your existing ingress controller to expose Qodo's portal, APIs, sign-on,
and Git webhooks. The Qodo chart creates routing resources. Your platform
team owns the controller, load balancer, network access, DNS, and certificates.

## Choose your controller

Choose the pattern that matches your controller, even if you run it on a
different cloud. Do not combine annotations from multiple controller profiles.

> **[AWS ALB](https://docs.qodo.ai/on-prem/ingress/aws.md)**
>
> IP targets, ACM TLS, and backend health checks.

> **[Google Cloud GKE](https://docs.qodo.ai/on-prem/ingress/google-cloud.md)**
>
> GCE controller, network endpoint groups, and BackendConfigs.

> **[Azure Application Gateway](https://docs.qodo.ai/on-prem/ingress/azure.md)**
>
> AGIC, private access, TLS, and readiness probes.

These profiles are values examples verified by rendering the released chart.
They have not been installed on every cloud. Complete the provider-specific
acceptance checks in your environment before opening traffic.

## Prepare DNS and certificates

Set `global.baseDomain` in your customer values. The chart uses these hosts:

| Default hostname | Backend Service and port | Required traffic |
| - | - | - |
| `app.<baseDomain>` | `qodo-portal:8080` | Browser portal |
| `api.<baseDomain>` | `qodo-platform:8000` | Platform API |
| `portal-api.<baseDomain>` | `qodo-platform:8000` | Portal backend |
| `auth.<baseDomain>` | `qodo-zitadel:8083` | OIDC discovery, login, and callbacks |
| `sdk.<baseDomain>` | `qodo-agent-runtime-qar:8000` | SDK and CLI API |
| `git.<baseDomain>` | `qodo-litegit:8000` | `/webhooks`, `/gerrit-webhooks`, and `/webhook` prefixes |

One wildcard DNS record and certificate for `*.<baseDomain>` covers the
defaults. For custom hostnames, set the corresponding
`global.ingress.*Hostname` values and cover every resolved hostname in DNS
and the certificate. Keep all six hostnames distinct. Resolve the auth host
from inside the cluster as well as from user browsers.

With Kubernetes Secret-based TLS, create the Secret named by
`global.tlsSecretName` in the Qodo namespace before installation. If you use
cert-manager, have the certificate become ready before disabling HTTP or
requiring an HTTPS-only listener. ALB uses the configured ACM certificate.

Keep TLS termination at the approved edge and use the backend protocol in
your selected profile. The shipped service ports use plaintext inside the
cluster. Configure backend TLS separately if your network policy requires it.
Preserve the original host and forwarded HTTPS scheme so OIDC issuer URLs
and callbacks remain correct.

A private ingress requires a network path from every caller, including your
Git provider. Cloud-hosted Git webhooks cannot reach a private address
without an approved connectivity path. If the webhook host needs different
exposure from the other hosts, design separate customer-managed routes.
The chart creates one Ingress with annotations shared by all hosts.

## Use an existing controller or OpenShift Routes

**Existing controller**

Use the actual IngressClass name supplied by your platform team. This
example assumes an existing Traefik class and a pre-created TLS Secret:

```yaml ingress-existing-controller-values.yaml theme={null}
global:
  tlsSecretName: qodo-tls
  ingress:
    enabled: true
    className: traefik
    annotations: {}
```

Configure the controller's backend protocol, request timeouts, forwarded
headers, and HTTPS-only policy through its supported configuration.
Test sign-on and a complete code review through that controller.

**OpenShift Routes**

Route creation is an alternative to Kubernetes Ingress:

```yaml ingress-openshift-values.yaml theme={null}
global:
  ingress:
    enabled: false
  route:
    enabled: true
```

The chart refuses to enable Ingress and Routes together. The Route
hostnames still come from `global.ingress.*Hostname`. Configure the
OpenShift router's certificate and the chart's Route TLS options using
your approved policy. For more information, see
[Helm chart configuration reference](https://docs.qodo.ai/on-prem/on-prem-helm-chart-reference.md).

To hand routing to your own Gateway API, service mesh, or separately managed
Ingress, set both `global.ingress.enabled: false` and
`global.route.enabled: false`. Provision routes for every host and path in
the table first. That switch suppresses the chart's Ingress; it does not
create HTTPRoutes, listeners, certificates, or DNS records.

## Render and verify

Apply one ingress overlay after your existing base and customer values.
For GKE, also append the release's `values-gke.yaml`. Inspect only the
Ingress template so generated Secret values do not appear in the output:

```bash theme={null}
NAMESPACE=qodo
helm template qodo ./qodo-onprem --namespace "$NAMESPACE" \
  -f qodo-onprem/onprem-base.yaml -f my-values.yaml \
  -f ingress-aws-values.yaml --show-only templates/ingress.yaml
```

After your normal Helm or GitOps deployment:

```bash theme={null}
KUBE_CONTEXT="REPLACE_WITH_YOUR_CONTEXT"
NAMESPACE=qodo
BASE_DOMAIN=qodo.example.com

kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" \
  get ingress qodo-qodo
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" \
  describe ingress qodo-qodo
curl --fail --silent --show-error \
  "https://auth.$BASE_DOMAIN/.well-known/openid-configuration"
```

Use your resolved custom auth hostname if you set an override. Verify each
outcome before opening traffic:

* Confirm the certificate is trusted and the HTTPS issuer matches the auth hostname.
* Check that the load-balancer provider reports every backend as healthy.
* Fetch OIDC discovery with an HTTP/1.1 client, including from inside the cluster.
* Complete SSO from a browser and load the portal.
* Exercise the SDK endpoint with your normal client.
* Deliver a real Git provider webhook and confirm its code review completes.

To check HTTP/1.1 explicitly:

```bash theme={null}
curl --http1.1 --fail --silent --show-error \
  "https://auth.$BASE_DOMAIN/.well-known/openid-configuration"
```

An assigned load-balancer address alone does not prove these flows work.

## Troubleshoot routing

| Symptom | Check and recovery |
| - | - |
| No load-balancer address | Verify controller selection, IAM, subnet discovery, and controller events |
| Unhealthy backends or HTTP 502 | Verify Service endpoints, backend protocol, health-check path/port, and firewalls |
| TLS errors | Check certificate coverage and readiness, Secret namespace, or the ACM ARN |
| Login redirects to HTTP or the wrong host | Check forwarded headers, auth hostname, issuer, and registered callbacks |
| Portal works but webhooks fail | Check reachability from the provider and preserve the webhook path without rewriting |

Fix the owning values or infrastructure configuration and let its controller
reconcile. Keep the existing Ingress during diagnosis; recreating it can
change the address and interrupt DNS.

## Next steps

* [Configure Kubernetes addons with values files](https://docs.qodo.ai/on-prem/kubernetes-addons.md): Compose ingress, scaling, and Secret references.
* [Deploy Qodo using Helm](https://docs.qodo.ai/on-prem/qodo-on-prem-helm-chart-overview.md): Apply the full installation and upgrade procedure.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.