Create an Ingress via Infrastructure as Code

Define each Ingress as an MgnlIngress. Create it in the Cockpit, or manage the same object from your deployment pipeline with the manifest on this page.

Leave ingress.enabled off in your Helm values.yml. Use the MgnlIngress on this page so the platform can manage the Ingress.

When you deploy ingresses via your CI/CD pipeline, they appear in the Cockpit with Origin: PIPELINE. You can optionally claim them later for centralized management in the Cockpit as this is the recommended approach.

This guide shows you how to create the same Ingress configurations using Kubernetes manifests that you would normally configure through Add an Ingress. There is embedded help available directly in Cockpit for adding Ingresses.

Manifest structure

Magnolia uses a custom Kubernetes resource called MgnlIngress that provides the same functionality as the Cockpit:

apiVersion: magnolia.info/v1alpha1
kind: MgnlIngress <1>
metadata:
  name: your-ingress-name
  namespace: your-namespace
  labels:
    app.kubernetes.io/managed-by: pipeline <2>
spec:
  # Configuration matching Cockpit UI options

kind must be MgnlIngress.

The value for app.kubernetes.io/managed-by must be pipeline.

Basic example

Here’s a simple Ingress manifest that matches what you’d create in the Cockpit:

apiVersion: magnolia.info/v1alpha1
kind: MgnlIngress
metadata:
  name: company-author <1>
  namespace: production
  labels:
    app.kubernetes.io/component: app
    app.kubernetes.io/managed-by: pipeline <2>
    app.kubernetes.io/name: company-author <1>
    app.kubernetes.io/part-of: magnolia
spec:
  # General settings (corresponds to "General settings" in UI)
  description: "Company Author Environment - Production"

  # Access control (corresponds to "Access control" in UI)
  whitelistIps: []
  blacklistIps: []

  # NGINX options (corresponds to "NGINX options" in UI)
  nginxOptions:
    forceSslRedirect: true
    proxyBodySize: "512m"
    rateLimiting:
      enabled: true
      limitPerMinute: 1000
      limitPerSecond: 20

  # CDN options (corresponds to "CDN options" in UI)
  cdnOptions:
    enabled: true <3>
    provider: Fastly <4>

  # Rules (corresponds to "Rules" in UI)
  allowRegex: false
  rules:
    - host: "author.company.com"
      paths:
        - path: "/"
          pathType: "Prefix"
          backendName: "production-magnolia-author-svc"
          backendPort: 443

  # TLS (corresponds to "TLS certificates" in UI)
  acquireCertificate: true
  tls:
    - hosts:
        - "author.company.com"
      secretName: "company-author-le-tls"

The app.kubernetes.io/name label should match the Ingress name (metadata.name).

The value for app.kubernetes.io/managed-by must be pipeline.

The cdnOptions.enabled must be true if you want to use the CDN.

The cdnOptions.provider must be Fastly if you want to use the CDN.

Map UI fields to manifest

The names below are the YAML keys. What each field means in the Cockpit is in Ingress terms.

General settings

description → Description

Access control

whitelistIps → Allow List IPs
blacklistIps → Deny List IPs
nginxOptions.disableRobots → Disable robots header
nginxOptions.deniedLocations → Denied locations

NGINX options

nginxOptions.proxyBodySize → Max body size
nginxOptions.proxyConnectTimeout → Connection timeout
nginxOptions.proxyReadTimeout → Read timeout
nginxOptions.proxySendTimeout → Send timeout
nginxOptions.forceSslRedirect → Force SSL redirect
nginxOptions.fromToWwwRedirect → From to www redirect. In Gateway API mode the redirect status is 301.
nginxOptions.rateLimiting → Rate limiting
nginxOptions.stickySession.enabled → Sticky session
nginxOptions.stickySession.cookieName: name of the affinity cookie
nginxOptions.stickySession.cookieMaxAgeInSecond: how long the cookie lasts, in seconds
nginxOptions.basicAuth.enabled → Basic auth
nginxOptions.basicAuth.basicAuthMessage: realm message shown in the browser prompt
nginxOptions.basicAuth.basicAuthSecret: name of the Secret that holds the htpasswd auth file

nginxOptions.permanentRedirect sends every request for this Ingress to another URL. Set enabled to true, url to the target, and redirectCode to 301, 302, 303, 307, or 308.

CDN options

cdnOptions.enabled → Enabled
cdnOptions.provider → Provider

Rules

allowRegex → Allow regular expressions
rules[].host → Host
rules[].paths[].pathType → Paths
rules[].paths[].path → Paths
rules[].paths[].backendName → Paths
rules[].paths[].backendPort → Paths
rules[].paths[].backendPortName → Paths. Set either this port name or backendPort. One of the two is required.

TLS certificates

acquireCertificate: true → TLS
tls[].secretName → Secret name

Deploy via pipeline

Add the manifest to your repository:

infrastructure/
├── ingresses/
│   └── production-author-ingress.yaml
└── .github/workflows/
    └── deploy.yml

Deploy using kubectl in your CI/CD pipeline:

- name: Deploy Ingress
  run: |
    kubectl apply -f infrastructure/ingresses/production-author-ingress.yaml <1>

Location of the manifest file; in this case, it is production-author-ingress.yaml.

After deployment, the Ingress should appear in Networking > Ingresses with Origin: PIPELINE.

Ingress with Origin PIPELINE in Cockpit

Configuration reference

The example below includes the fields from Map UI fields to manifest.

apiVersion: magnolia.info/v1alpha1
kind: MgnlIngress
metadata:
  name: full-example
  namespace: production
  labels:
    app.kubernetes.io/managed-by: pipeline <1>
spec:
  description: "Full configuration example"
  acquireCertificate: true
  allowRegex: false
  errorPages: false
  whitelistIps: []
  blacklistIps: []

  nginxOptions:
    # Security
    disableRobots: false
    forceSslRedirect: true
    fromToWwwRedirect: false
    deniedLocations: []

    # Performance
    proxyBodySize: "1024m"
    proxyBufferSize: "4k"
    proxyBuffersNumber: 4
    proxyRequestBuffering: true
    proxyBuffering: true
    proxyConnectTimeout: 300
    proxyReadTimeout: 300
    proxySendTimeout: 300

    # Headers
    headersToClear: []
    headersToSet: {}

    # Features
    rateLimiting:
      enabled: true
      limitPerMinute: 3000
      limitPerSecond: 50
      whitelistIps: []
    basicAuth:
      enabled: false
    cors:
      enabled: false
    certificateAuthentication:
      enabled: false
    stickySession:
      enabled: false
    errorPage:
      enabled: false
    permanentRedirect:
      enabled: false

  cdnOptions:
    enabled: true
    provider: Fastly

  rules:
    - host: "app.company.com"
      paths:
        - path: "/"
          pathType: "Prefix"
          backendName: "production-app-service"
          backendPort: 80

  tls:
    - hosts:
        - "app.company.com"
      secretName: "app-company-tls"

The value for app.kubernetes.io/managed-by must be pipeline.

Manage pipeline Ingresses

After deploying via pipeline:

Ingresses appear with Origin: PIPELINE
You can view and monitor them in the Cockpit
Optionally claim them to bring them under Cockpit management
Use Synchronize to update the Cockpit view if you make external changes