This guide provides instructions on how to install and configure a Midaz environment for Kubernetes using Helm, covering key aspects such as Ingress controllers, observability, and dependencies.

Before you start

Before deploying Midaz with Helm, ensure you have the following:

• Kubernetes (version 1.30 or later): A running Kubernetes cluster is required for deployment.
• Helm 3+: Ensure you have Helm installed. You can check your version with helm version command

For better understanding of every dependency and architecture layer, we recommend reading about the Midaz components architecture documentation.

How to deploy Midaz

To install Midaz using Helm, run the following command:

$ helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version> -n midaz --create-namespace

This will create a new namespace called midaz, if it doesn't already exist, and deploy the Midaz Helm chart.

After installation, you can verify that the release was successful by listing the Helm releases in the midaz namespace:

$ helm list -n midaz

👍

Helm Chart Source

The Helm chart used in this guide is available at GitHub in the helm repository . Check it out if you need to modify values or extend functionality.

Configuring Ingress for Different Controllers

If needed, the Midaz Helm Chart supports different Ingress Controllers for exposing services when necessary. You can enable Ingress for the following services: Transaction, Ledger, and Console.

Before configuring Ingress, make sure you have an Ingress Controller installed in your cluster. Use the values.yaml file to configure the ingress, according to the controller.

In the following codes, you can find the configurations or commonly used controllers.

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"  # Ensure this issuer exists in your cluster
    nginx.ingress.kubernetes.io/rewrite-target: /
  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

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

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

Configuring Observability

We use Grafana Docker OpenTelemetry LGTM for the observability within Midaz. This component helps in collecting, processing, and exporting telemetry data like traces and metrics.

Accessing Grafana dashboard

To access the observability dashboard, forward the Grafana port with the following command:

$ kubectl port-forward svc/midaz-otel 3000:3000 -n midaz

After running the command, you will be able to navigate to the dashboard at http://localhost:3000.

Allowing access through DNS to the Grafana dashboard

If you want to access the observability dashboard internally using a custom DNS (e.g., within your Kubernetes cluster or private network), you need to enable and configure the Ingress for the otel component in the values.yaml file.

Here's an example configuration for an internal Ingress:

otel:
  enabled: true
  name: otel

  ingress:
    enabled: true
    className: "nginx"  # Use an internal Ingress class (e.g., nginx-internal)
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /
      # Optional: Use the following annotation to restrict access to internal networks
      nginx.ingress.kubernetes.io/whitelist-source-range: ""
    hosts:
      - host: "midaz-ote.example.com"  # Replace with your custom internal DNS
        paths:
          - path: /
            pathType: Prefix
    tls: []  # TLS is optional for internal access

Disabling observability

If necessary, the deployment of this component can be disabled by setting otel.enabled to false in the values file.

otel:
  enabled: false

Configuring Dependencies

This installation has a series of dependencies, enabled by default, for the project's default installation.

Depending on your setup, you can disable these dependencies in the values file, under the enabled boolean flag and configure Midaz Components to use your existing instances.

Midaz Components

The Midaz system runs on four distinct layers that work together, distributed in segregated workloads:

Ledger

Transaction

Audit

Console