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

# Configuring ingress

> Expose Midaz services through Kubernetes ingress — set hostnames, TLS secrets, and controller annotations for NGINX, ALB, or Traefik.

Each Midaz service can be independently exposed via ingress. The ingress block is identical across services (Ledger, Onboarding, Transaction, CRM, Grafana) — configure it under each service's `.ingress` section in `values.yaml`.

To use ingress, you need an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) running in your cluster (e.g., **NGINX**, **AWS ALB**, or **Traefik**) and DNS entries pointing to it.

<Tip>
  You can enable ingress per service in your values.yaml file and configure hostnames, TLS secrets, and any controller-specific annotations.
</Tip>

<Note>
  **cert-manager integration:** If you use cert-manager for automatic TLS, add the annotation `cert-manager.io/cluster-issuer: <issuer-name>` and set `tls.secretName` — cert-manager will provision the certificate automatically.
</Note>

The following sections provide configuration examples for the most common ingress controllers.

## NGINX ingress controller

***

To use the **NGINX Ingress Controller**, configure the `values.yaml` as follows:

```yaml expandable theme={null}
ingress:
  enabled: true
  className: "nginx"
  # The `annotations` field is used to add custom metadata to the Nginx resource.
  # Annotations are key-value pairs that can be used to attach arbitrary non-identifying metadata to objects.
  # These annotations can be used by various tools and libraries to augment the behavior of the Nginx resource.
  # See more https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md
  annotations: {}
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: midaz-tls  # Ensure this secret exists or is managed by cert-manager
      hosts:
        - midaz.example.com
```

<Tip>
  Check the ingress-nginx official documentation for a full reference on Nginx annotations.
</Tip>

## AWS ALB (Application load balancer)

***

For **AWS ALB Ingress Controller**, configure the `values.yaml` as follows:

```yaml expandable theme={null}
ingress:
  enabled: true
  className: "alb"
  annotations:
    alb.ingress.kubernetes.io/scheme: internal  # Use "internet-facing" for public ALB
    alb.ingress.kubernetes.io/target-type: ip   # Use "instance" if targeting EC2 instances
    alb.ingress.kubernetes.io/group.name: "midaz"  # Group ALB resources under this name
    alb.ingress.kubernetes.io/healthcheck-path: "/healthz"  # Health check path
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'  # Listen on HTTP and HTTPS
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls: []  # TLS is managed by the ALB using ACM certificates
```

## Traefik Ingress controller

***

For **Traefik**, configure the `values.yaml` as follows:

```yaml expandable theme={null}
ingress:
  enabled: true
  className: "traefik"
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: "web, websecure"  # Entrypoints defined in Traefik
    traefik.ingress.kubernetes.io/router.tls: "true"  # Enable TLS for this route
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: midaz-tls  # Ensure this secret exists and contains the TLS certificate
      hosts:
        - midaz.example.com
```

## Multiple services example

***

To expose both the Ledger API and Grafana with different hostnames:

```yaml theme={null}
ledger:
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: api.midaz.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: midaz-api-tls
        hosts:
          - api.midaz.example.com

grafana:
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: grafana.midaz.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: midaz-grafana-tls
        hosts:
          - grafana.midaz.example.com
```