Configuring ingress

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

CRM and Fees guidance marked legacy on this page applies only to an existing legacy release. Midaz v4 deploys the unified Ledger and serves CRM and Fees on /v2.

The Helm repository retains a crm.enabled workload and the plugin-fees-helm chart for older application releases. These are legacy compatibility surfaces, not the Midaz v4 deployment model.

Use ledger.ingress for Midaz v4. The retained CRM ingress examples apply only to the legacy crm.enabled compatibility workload.

To use ingress, you need an ingress controller running in your cluster (e.g., NGINX, AWS ALB, or Traefik) and DNS entries pointing to it.

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

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.

NGINX ingress controller

---

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

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

Check the ingress-nginx official documentation for a full reference on Nginx annotations.

AWS ALB (Application load balancer)

---

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

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: "/health"  # 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:

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 CRM with different hostnames:

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

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