Skip to content

Ingress

Definition

ingresses:
  minimum:
    services:
      full:
        hosts:
          - host1.local

  full:
    tls:
      enabled: true # generate certificate for all hosts in spec if tls is not explicitly provided with spec
      secret:  "my-tls-secret" # tls secret name override
    hosts:  # host lists to avoid copy paste in spec
      default: # default hosts list used if `hosts` is not set for service in `.services` or `spec` has rule without `host` defined
        - host1.local
        - host2.local
      example:
        - example.local
    services: # list of application services to generate rules for
      full:
        hosts: 
          - default 
          - host3.local
        ports:
          api:
            - path: /api
          metrics:
            - path: /metrics
              pathType: Exact     
    spec: 
      rules:
        - host: example.com
          http:
            paths:
              - path: /
                pathType: "Prefix"
        - host: example
          http:
            paths:
              - path: /
                pathType: "Prefix"
        - http:
            paths:
              - path: /default
                pathType: "Prefix"


  pure-spec:
    spec:
      defaultBackend:
        service:
          name: full
          port:
            name: api 
      tls:
        - hosts:
            - host1.k3s.local
          secretName: testsecret-tls            
      rules:
        - host: "host1.k3s.local"
          http:
            paths:
              - path: /api/v3(/|$)(.*)
                pathType: Prefix
              - path: /
                pathType: Prefix       

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/tls-acme: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
  labels:
    app.kubernetes.io/component: cicd-sample
    app.kubernetes.io/instance: docs
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/name: cicd-sample
    app.kubernetes.io/part-of: cicd
    app.kubernetes.io/version: 1.0.0
    exordis/application: cicd-sample
    exordis/application-instance: docs
    exordis/application-type: service
    exordis/environment: test
    exordis/product: Some Product
    exordis/subsystem: cicd
    helm.sh/chart: cicd-subsystem-application-0.1.0
  name: cicd-sample-docs-minimum
  namespace: cicd-test
spec:
  rules:
    - host: host1.local
      http:
        paths:
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: api
            path: /api
            pathType: Prefix
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: metrics
            path: /metrics
            pathType: Prefix
  tls:
    - hosts:
        - host1.local
      secretName: cicd-sample-docs-minimum-tls

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/tls-acme: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
  labels:
    app.kubernetes.io/component: cicd-sample
    app.kubernetes.io/instance: docs
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/name: cicd-sample
    app.kubernetes.io/part-of: cicd
    app.kubernetes.io/version: 1.0.0
    exordis/application: cicd-sample
    exordis/application-instance: docs
    exordis/application-type: service
    exordis/environment: test
    exordis/product: Some Product
    exordis/subsystem: cicd
    helm.sh/chart: cicd-subsystem-application-0.1.0
  name: cicd-sample-docs-full
  namespace: cicd-test
spec:
  rules:
    - host: host1.local
      http:
        paths:
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: api
            path: /api
            pathType: Prefix
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: metrics
            path: /metrics
            pathType: Exact
    - host: host2.local
      http:
        paths:
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: api
            path: /api
            pathType: Prefix
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: metrics
            path: /metrics
            pathType: Exact
    - host: host3.local
      http:
        paths:
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: api
            path: /api
            pathType: Prefix
          - backend:
              service:
                name: cicd-sample-docs-full
                port:
                  name: metrics
            path: /metrics
            pathType: Exact
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
    - host: example.local
      http:
        paths:
          - path: /
            pathType: Prefix
    - host: host1.local
      http:
        paths:
          - path: /default
            pathType: Prefix
    - host: host2.local
      http:
        paths:
          - path: /default
            pathType: Prefix
  tls:
    - hosts:
        - host1.local
        - host2.local
        - host3.local
        - example.com
        - example.local
      secretName: cicd-sample-docs-full-tls

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/tls-acme: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
  labels:
    app.kubernetes.io/component: cicd-sample
    app.kubernetes.io/instance: docs
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/name: cicd-sample
    app.kubernetes.io/part-of: cicd
    app.kubernetes.io/version: 1.0.0
    exordis/application: cicd-sample
    exordis/application-instance: docs
    exordis/application-type: service
    exordis/environment: test
    exordis/product: Some Product
    exordis/subsystem: cicd
    helm.sh/chart: cicd-subsystem-application-0.1.0
  name: cicd-sample-docs-pure-spec
  namespace: cicd-test
spec:
  defaultBackend:
    service:
      name: full
      port:
        name: api
  rules:
    - host: host1.k3s.local
      http:
        paths:
          - path: /api/v3(/|$)(.*)
            pathType: Prefix
          - path: /
            pathType: Prefix
  tls:
    - hosts:
        - host1.k3s.local
      secretName: testsecret-tls
enabled

if set to false ingress is excluded from rendering

default: true

namespace

ingress namespace

default: subsystem namespace generated by convention

labels

list of labels to add to secret in addition to common labels

default: empty dict

annotations

list of annotations to add to secret in addition to common labels

default: empty dict

hosts

lists of hosts. If hosts has item with some name, this name would be expanded to list when used as host on spec or service mapping

default

hosts from this list are used if hosts is not explicitly provided in service mapping or spec.rules

default: { "default": ["default"] }

services

Defines services mapping. Dict where key is service name and value

hosts

hosts to expose service on

default: empty dict

ports

ports of service to expose and settings for them. key is service port name, values - list of rule overrides for service port

default: expose all service ports on path matching port name e.g port api would be exposed on path /api with pathType: "Prefix"

default: empty dict

tls

Defines tls utilization

enabled

Whether to use TLS

default: true

secretName

name of the secret for tls certificate

default: namespace generated with naming conventions with secret id equal to <ingress id>-tls

spec

Ingress kubernetes manifests spec field value.

default: empty

Minimum Viable Ingress Definition

  • Default metadata
  • single host host1.local
  • Ingress exposes all service ports on paths matching service port name (single port http on path /http )
  • TLS is enabled and cert has single SAN host1.local
applicationContainer:
  spec:
    ports:
      - containerPort: 8080
        name: http  

services:
  minimum: 
    ports:
      http:

ingresses:
  minimum:
    services:
      minimum:
        hosts:
          - host1.local

Validations

  • services referenced in services are defined in values.services
  • ports referenced in services.<service id>.ports are defined for service with given id on values.services

Overrides

name

generated with naming conventions from ingress id

Manifests Generation

Ingress manifest is generated for each ingress.

  • common labels are added to metadata
  • spec value is extended with rules generated from services
  • Resulting spec is processed with expansion of spec.rules[].host based on lists provided with hosts e.g. if some rule has host myhosts and hosts.myhosts is defined, the rule would be repeated for each value in hosts.myhosts as host

if spec.tls is not explicitly provided and tls is set to true, it is generated:

  • spec.tls.hosts contains all hosts referenced on spec in this case
  • annotation nginx.ingress.kubernetes.io/force-ssl-redirect: "true" is added
  • tls.secretName value is used as tls secret name