Ingresses

Kubernetes Ingresses manage external access to services within a cluster, enabling HTTP and HTTPS traffic routing based on hostnames and paths. They provide a flexible, scalable way to expose Magnolia applications, supporting features like SSL termination, load balancing, and custom NGINX configurations. Ingresses are essential for delivering secure, performant web experiences in the DX Cloud Cockpit.

In this section:

• Add an Ingress
• Add an Ingress via YAML
• Claim an Ingress
• Synchronize an Ingress
• Ingress terms

Select desired cluster

Select your desired cluster from the dropdown menu at the top of the Cockpit.

Add an Ingress

1. Go to Networking > Ingresses in your Cockpit.

2. Ensure you are on your desired cluster (see Select desired cluster above).

3. Click Add. This opens a dialog where you configure critical Ingress criteria.

4. Under General settings, give your Ingress a Name and a Description.

5. Under Rules, configure routing.

   Ingress rules specify the direction of allowed access to and from different identities and resources.

6. Set Allow regular expression if you need regular expression matching.

7. Enter the Host (hostname).

8. Choose the Path type:

   • ImplementationSpecific: matching is up to the IngressClass.
   • Exact: matches the URL path exactly, including case sensitivity.
   • Prefix: matches based on a URL path prefix split by /. This is case-sensitive.

9. Specify the Path itself, such as /icons or /docs.

10. Choose the Service from the dropdown. This is typically public or author, but you can also point to your redirect service (for example <env>-magnolia-redirects-svc). Use your redirect service for hosts/paths that must be processed by the redirect server. If the redirect server is not installed and running, the redirect service is not available as an option in the Service dropdown.

11. Choose the Backend port (number such as 9090, or the port name if a name is given).

12. Under Access control, enter the Allow List IPs.

13. Enter the Deny List IPs.

14. Disable the robots header (if desired).

15. Add any desired Denied locations. You can also deny access to Admincentral for locations here.

16. Under NGINX options, set the Max body size.

17. Enable Response buffering.

18. Set the Max buffer size.

19. Set the Number buffers.

20. Enable Request buffering.

21. Configure the Connection timeout.

22. Adjust the Read timeout.

23. Set the Send timeout.

24. Enable Force SSL redirect if desired.

25. Enable From to www redirect if desired.

26. Enable the Ingress firewall. Recommended where appropriate.

27. Set Rate limiting parameters.

28. Specify any Headers to clear in the response.

29. Set any Headers to set you want in the response.

30. If desired, enable and define an Error page.

31. Enable Sticky sessions to route a client’s requests to the same backend server.

32. If desired, enable Basic auth.

33. Configure CORS to control which domains can access resources.

34. Enable client certificate authentication to require clients to present a valid SSL/TLS certificate.

35. Under CDN options, choose to enable content delivery for the Ingress (if desired). If enabled, Fastly is currently the only option.

36. Under TLS certificates, choose to enable Acquire certificates automatically, using Let’s Encrypt (HTTP-01) if desired.

37. Otherwise, select an existing SSL/TLS certificate secret from the cluster to secure the Ingress. This is disabled if certificate acquisition is automatic (enabled above).

Add an Ingress via YAML

If you prefer to add your ingress via a .yaml file, you can do so by clicking the Add as YAML button. This opens a dialog where you can paste your .yaml file.

1. Go to Networking > Ingresses in your Cockpit.
2. Click Add as YAML.
3. Paste your .yaml file.

name: "example-website"
description: "Imported from existing ingress"
allowUnsecuredTraffic: false
acquireCertificate: false
allowRegex: false

nginxOptions:
  proxyBodySize: "8m"
  proxyBuffering: true
  proxyRequestBuffering: true
  forceSslRedirect: false
  fromToWwwRedirect: false
  enableWaf: false
  disableRobots: false
  deniedLocations: []
  headersToClear: []
  headersToSet: {}

cdnOptions:
  enabled: false

rules:
  - host: "www.example.com" <1>
    paths:
      - path: "/"
        pathType: "Prefix"
        backendName: "prod-magnolia-redirects-svc"
        backendPort: 80

tls:
  - secretName: "example-website-tls"

4. Click Add as YAML to add your ingress.

Once your Ingress is added, you can view it in the Ingresses table.

Claim an Ingress

Claiming an Ingress designates the Cockpit as the primary tool for managing its configuration, ensuring that subsequent changes are made through the Cockpit and external updates (for example, via Rancher or CI/CD pipelines) are ignored when publishing. Once claimed, external changes are overwritten when publishing from the Cockpit. Only healthy ingresses, those without synchronization warnings, can be claimed and managed via the Cockpit.

If you claim an Ingress that was previously managed by infrastructure as code (for example, a Helm chart or pipeline manifest), the Cockpit adopts the existing Ingress object in the cluster. You do not need to delete the Ingress via kubectl, Rancher, the Cockpit, or your pipeline.

Deleting the Ingress during this handoff can tear down related CDN configuration (for example, Fastly) and cause downtime.

What you must do instead:

1. Claim the Ingress in the Cockpit.
2. Remove the Ingress definition from your IaC source (for example, from values.yml or the pipeline manifest) so the next deploy cannot recreate or overwrite it.
3. Redeploy the Helm chart (or equivalent pipeline) so ownership in your release no longer includes that Ingress.

After claiming, manage the Ingress exclusively through the Cockpit.

To claim an Ingress:

1. Go to Networking > Ingresses.
2. Choose the desired Ingress.
3. Under the details section, click Claim.

Validation severity levels

Ingress validation issues are categorized into two severity levels:

• Warnings: These ingresses are functional but fail validation checks, preventing them from being claimed. Warnings indicate issues that must be resolved at the infrastructure level (for example, via Rancher). After fixing the issues, trigger a Synchronization in the Cockpit to revalidate the Ingress. If no synchronization warnings remain, the Ingress can be claimed. Attempting to claim an Ingress with synchronization warnings will result in an HTTP 422 status code from the backend.
• Errors: Ingresses with errors are non-functional and can be claimed to allow fixes directly in the Cockpit. Use the Cockpit interface to edit and resolve these errors, restoring the Ingress to a healthy state.

Synchronize an Ingress

Synchronization updates the Cockpit’s view of an unclaimed Ingress to reflect its current configuration in the Kubernetes cluster (for example, managed via Rancher). Synchronization allows users to review the Ingress’s state in the Cockpit before deciding to claim it for Cockpit management. Synchronization is not available for claimed Ingresses, as claiming stops this process to ensure the Cockpit controls the Ingress’s configuration.

Ingresses created in the Cockpit are typically claimed and aligned with Kubernetes upon publishing, so synchronization is only needed if external changes or validation issues arise.

Why synchronize?

Synchronization is used when:

• You need to view the latest Kubernetes configuration of an unclaimed Ingress (for example, created in Rancher or modified externally) in the Cockpit before claiming it.
• Validation warnings have been fixed at the infrastructure level (for example, in Rancher), and you need to revalidate an unclaimed Ingress to confirm it’s claimable.

How to synchronize an Ingress

To synchronize an Ingress:

1. In the Cockpit, go to Networking > Ingresses.
2. Select an unclaimed Ingress from the list.
3. Verify that no unpublished changes exist in the Cockpit (for example, check for pending edits in the Ingress details).
4. Click Synchronize.

The Cockpit then pulls the Ingress’s current configuration from the Kubernetes cluster, updates its database, and revalidates the Ingress. If validation errors persist (for example, resulting in an HTTP 422 status code), resolve them at the infrastructure level and synchronize again.

Best practices

• Choose a management tool: Decide whether an Ingress is managed via the Cockpit, a CI/CD pipeline, or manually (for example, Rancher). Synchronize unclaimed ingresses to review their state, then claim them for Cockpit management if desired.
• Check before synchronizing: Ensure no temporary Cockpit edits are critical, as they will be lost during synchronization.
• Synchronize selectively: Use synchronization only when needed (for example, to review external changes or revalidate warnings). After claiming, manage the Ingress exclusively via the Cockpit.
• Monitor Ingress health: After synchronizing, check for validation warnings or errors in the Cockpit.
• Troubleshoot issues: If synchronization fails, verify the Ingress configuration in Rancher or with kubectl get ingress to identify discrepancies.

Ingress terms

Field-level help in the Cockpit Add/Edit Ingress dialog matches the definitions below. For NGINX options, Magnolia-specific guidance is included where it applies.

General settings

Name {#name}

A unique name for the Ingress resource, used to identify it within the Kubernetes cluster. Must follow Kubernetes naming conventions (lowercase, alphanumeric, hyphens).

Description

An optional description of the Ingress, providing context or purpose for the resource. Useful for organizing, auditing, and documenting resources.

Access control

Allow List IPs {#whitelistips}

A list of IP addresses or CIDR ranges allowed to access the Ingress. Only requests from these IPs are permitted, enhancing security by restricting access.

Deny List IPs {#blacklistips}

A list of IP addresses or CIDR ranges blocked from accessing the Ingress. Requests from these IPs are denied, protecting against known threats.

Disable robots header {#disablerobots}

Enables or disables the robots header in HTTP responses. When checked, prevents search engine crawlers from indexing the Ingress; useful for private or sensitive endpoints.

Denied locations {#deniedlocations}

Allows you to block access to specific paths by defining a list of denied locations. Ensures requests to those paths are rejected before reaching the backend services.

NGINX options

Max body size {#proxybodysize}

Sets the maximum allowed size of the client request body, specified in bytes (for example 10m for 10 megabytes). Limits large uploads to protect server resources.

Enable response buffering {#proxybuffering}

Controls response buffering:

• on (default): NGINX buffers the response in memory (or disk if large) before delivering it to the client.
• off: NGINX streams the response to the client as it receives it from the backend.

Set it to off for Server-Sent Events (SSE), real-time APIs, or to reduce memory use under load.

Max buffer size {#proxybuffersize}

Sets the size of the buffer used for reading the first part of the response received from the proxied server. By default the proxy buffer size is 4k.

Allows large cookies, big JWT tokens, or long custom headers to pass through NGINX.

Number buffers {#proxybuffersnumber}

Sets the number of buffers in proxy_buffers used for reading the first part of the response. By default the number of buffers is 4.

Enable request buffering {#proxyrequestbuffering}

Controls request buffering:

• on (default): Buffer the entire request body in memory or to disk before sending it to the backend.
• off: NGINX streams the request to the backend as it receives it from the client.

Set it to off for file uploads (for example, to enable a progress bar while uploading to Magnolia) or real-time data input.

Connection timeout {#proxyconnecttimeout}

Sets the maximum time, in seconds, that NGINX waits while establishing a TCP connection to the upstream. By default the timeout is 60 seconds.

Read timeout {#proxyreadtimeout}

Sets the maximum time, in seconds, that NGINX waits to read data from the backend after the connection has been established. By default the timeout is 60 seconds.

Send timeout {#proxysendtimeout}

Sets the maximum time, in seconds, that NGINX waits while sending data to the backend. By default the timeout is 60 seconds.

Force SSL redirect {#forcesslredirect}

When enabled, redirects all HTTP requests to HTTPS, ensuring secure communication.

From to www redirect {#fromtowwwredirect}

When enabled, redirects requests between www and non-www (apex) versions of the domain. If your rule’s host is the apex domain, the Ingress redirects www requests to the apex domain. If your rule’s host is the www domain, the Ingress redirects apex requests to the www domain. In both cases, the preferred domain should be the only one defined in the rules.

Enable Ingress firewall (OWASP) {#enablewaf}

Enables the Web Application Firewall (WAF) to protect against common web attacks.

Rate limiting {#ratelimiting}

Configures rate limiting to restrict the number of requests per client, preventing abuse or denial-of-service attacks.

Headers to clear {#headerstoclear}

Specifies HTTP headers to remove from the response, improving security or compatibility by eliminating unwanted headers.

Headers to set {#headerstoset}

Defines custom HTTP headers to add to the response, such as security headers (for example X-Frame-Options) or caching directives.

Error page {#errorpage}

Customizes error pages for specific HTTP status codes (for example 404, 500), providing user-friendly messages or redirects.

Sticky session {#stickysession}

Enables sticky sessions to route a client’s requests to the same backend server, useful for session-based applications.

Basic auth {#basicauth}

Enables HTTP Basic Authentication, requiring a username and password for access.

CORS {#cors}

Configures Cross-Origin Resource Sharing (CORS) to control which domains can access resources, enabling secure cross-origin requests.

mTLS {#certificateauthentication}

Enables client certificate authentication: the Ingress verifies clients using a certificate. When enabled, choose a Mode (on, off, optional, or optional_no_ca) and select the mTLS secret from the dropdown.

CDN options

Enabled {#cdnenabled}

Enables or disables the Content Delivery Network (CDN) for the Ingress. When enabled, traffic is routed through the CDN (Fastly) to improve performance and caching.

Provider

Displays the CDN provider, fixed to Fastly. This field is read-only.

Rules

Allow regular expressions {#allowregex}

Allows using regular expressions in rule path fields. Use only with path type ImplementationSpecific and an actual regex path; this can have a performance impact.

When path type is Prefix or Exact, Kubernetes restricts path format. Paths such as /.magnolia/admincentral require path type ImplementationSpecific.

Host {#host}

Specifies the host domain for the Ingress rule (for example, example.com). Wildcard domains are supported by adding a * to the host (for example *.example.com).

Paths {#paths}

Configures the URL paths and their corresponding backend services for the host. For each path, choose Path type and the path value.

TLS

SSL/TLS Configuration {#acquirecertificate}

• Allow unsecure traffic (No SSL/TLS): Disables SSL/TLS encryption and allows traffic over HTTP only.
• Automatic certificate acquisition: Automatically obtains and manages an SSL/TLS certificate, typically via Let’s Encrypt.
• Custom certificate: Use a manually provided SSL/TLS certificate by selecting a pre-created secret.

Secret name {#secretname}

Selects an existing SSL/TLS certificate secret from the cluster to secure the Ingress. Disabled when automatic certificate acquisition is enabled.