ingress.yaml

Overview

The ingress.yaml file is a Kubernetes manifest template configured using Helm templating syntax. Its primary purpose is to define an Ingress resource for a Kubernetes cluster that routes external HTTP(S) traffic to internal services. This file enables dynamic configuration of ingress rules, TLS settings, annotations, and ingress class based on Helm chart values, allowing flexible and customizable exposure of services.

In summary, this file facilitates:

Conditional creation of an Ingress resource based on a Helm value.
Specification of ingress metadata such as name and labels.
Optional annotations to customize ingress controller behavior.
Support for ingress class name configuration.
TLS termination configuration with multiple hosts and secrets.
HTTP routing rules with multiple hosts and paths, directing traffic to the service associated with the Helm release.

Detailed Explanation

Template Conditional

{{- if .Values.ingress.enabled -}}
...
{{- end }}

The entire Ingress resource is created only if the Helm chart value ingress.enabled is set to true.
This enables users to toggle ingress creation without removing the resource file.

API Version and Kind

apiVersion: networking.k8s.io/v1
kind: Ingress

Uses the stable Kubernetes Ingress API networking.k8s.io/v1.
Defines the resource kind as Ingress.

Metadata Section

metadata:
  name: {{ include "ragflow.fullname" . }}
  labels:
    {{- include "ragflow.labels" . | nindent 4 }}
  {{- with .Values.ingress.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}

name: Uses a Helm template helper ragflow.fullname to generate the Ingress resource name, typically based on the release name and chart name.
labels: Adds labels generated by the ragflow.labels helper, which generally include app and version metadata to identify the resource.
annotations (optional): Adds user-defined annotations from ingress.annotations. These can be used to configure ingress controller-specific features (e.g., cert-manager, NGINX ingress controller behaviors).

Spec Section

spec:
  {{- with .Values.ingress.className }}
  ingressClassName: {{ . }}
  {{- end }}
  {{- if .Values.ingress.tls }}
  tls:
    {{- range .Values.ingress.tls }}
    - hosts:
        {{- range .hosts }}
        - {{ . | quote }}
        {{- end }}
      secretName: {{ .secretName }}
    {{- end }}
  {{- end }}
  rules:
    {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
          {{- range .paths }}
          - path: {{ .path }}
            {{- with .pathType }}
            pathType: {{ . }}
            {{- end }}
            backend:
              service:
                name: {{ $.Release.Name }}
                port:
                  name: http
          {{- end }}
    {{- end }}

ingressClassName

Optional field set if ingress.className is defined.
Specifies the IngressClass resource to target a specific ingress controller (e.g., nginx, traefik).

TLS Configuration

Configurable TLS settings via ingress.tls.
Each TLS entry includes:
- A list of hosts to secure.
- The secretName referencing a Kubernetes TLS secret with the certificate and key.
Enables HTTPS termination at ingress controller.

Rules

Defines HTTP routing rules per host.
For each host in ingress.hosts:
- The host field specifies the domain name.
- Under http.paths, one or more paths are configured.
- Each path has:
  - path: the URI path to match.
  - pathType: optional, defines matching behavior (Prefix, Exact, or ImplementationSpecific).
  - backend.service.name: set to the Helm release name, tying the ingress to the service deployed by this chart.
  - backend.service.port.name: fixed to http, expecting the service to expose a port named http.

Parameters and Values

This file relies heavily on Helm values defined in the values.yaml file (not included here). Key parameters include:

Parameter	Type	Description	Required	Default
`ingress.enabled`	boolean	Enables or disables creation of the Ingress resource	Yes	false
`ingress.annotations`	map[string]string	Custom annotations to add to the Ingress metadata	No
`ingress.className`	string	Name of the IngressClass to use	No
`ingress.tls`	list	List of TLS configurations, each with hosts and secret name	No
`ingress.hosts`	list	List of host configurations, each with host and paths	Yes

Example snippet of values.yaml for ingress:

ingress:
  enabled: true
  className: "nginx"
  annotations:
    kubernetes.io/ingress.class: "nginx"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  tls:
    - hosts:
        - example.com
      secretName: example-tls
  hosts:
    - host: example.com
      paths:
        - path: /
          pathType: Prefix

Usage Examples

Enabling Ingress with TLS and Multiple Hosts

In your Helm values.yaml:

ingress:
  enabled: true
  className: "nginx"
  annotations:
    kubernetes.io/ingress.class: "nginx"
  tls:
    - hosts:
        - "app.example.com"
      secretName: app-tls-secret
  hosts:
    - host: "app.example.com"
      paths:
        - path: /
          pathType: Prefix

Then install or upgrade the Helm chart:

helm install ragflow ./chart --values values.yaml

This will generate an Ingress resource exposing the service under app.example.com with TLS termination.

Implementation Details and Algorithms

The file uses Helm templating directives ({{ }}) to inject values dynamically.
Conditional blocks (if, with, range) control optional sections and iterations.
It uses include statements to reuse common template helpers for naming and labeling, ensuring consistency across resources.
The backend service name is set to the Helm release name ({{ $.Release.Name }}), assuming the service created shares this name.
The use of toYaml with indentation ensures proper YAML formatting for annotations.

Interaction with Other System Components

Service Resource: The Ingress routes traffic to a Kubernetes Service exposing application pods. The service name must match the Helm release name, and it must have a port named http.
Ingress Controller: This Ingress resource must be processed by a Kubernetes ingress controller (e.g., NGINX, Traefik). The ingress controller watches for Ingress resources and configures the underlying load balancer/proxy accordingly.
TLS Secrets: TLS termination depends on Kubernetes Secrets that store certificates. These secrets must exist in the same namespace or be accessible by the ingress controller.
Helm Chart Values: This file depends on values set in the Helm chart, making it configurable per deployment environment.

Visual Diagram

flowchart TD
    A[Start: Check ingress.enabled] -->|enabled=true| B[Ingress Resource Creation]
    A -->|enabled=false| Z[No Ingress Created]

    B --> C[Set metadata.name using ragflow.fullname]
    B --> D[Set metadata.labels using ragflow.labels]
    B --> E{Annotations?}
    E -->|Yes| F[Add annotations]
    E -->|No| G[Skip annotations]

    B --> H{ingress.className?}
    H -->|Yes| I[Set ingressClassName]
    H -->|No| J[Skip ingressClassName]

    B --> K{TLS configuration?}
    K -->|Yes| L[Add TLS hosts and secretNames]
    K -->|No| M[Skip TLS]

    B --> N[Configure rules for each host]
    N --> O[For each host: define host and http.paths]
    O --> P[For each path: set path, pathType, backend service and port]

    P --> Q[Ingress Resource Complete]

Summary

This ingress.yaml Helm template dynamically generates a Kubernetes Ingress resource based on user-defined values. It supports flexible configuration of ingress class, annotations, TLS certificates, and multiple host/path rules, allowing robust routing of external traffic to internal services. Its tight integration with Helm values and helper templates ensures reusable, environment-specific deployments within Kubernetes clusters.