Open Ask AI (⌘/Ctrl+I)
On this page

Create redirects

You can view redirects that you have created or add them directly yourself from the Cockpit. You must publish any changes you make to redirects.

Redirects overview

Important concepts:

Actions:

Good to knows

  • The redirects server is a proxy server.

  • Redirects are evaluated in order of appearance when entered. The first match is accepted.

  • Any query parameters with a request are copied over in the redirect.

  • We use the Source URL to detect duplicate entries when you add a single redirect or batch import redirects (CSV).

    If the redirect you enter is a duplicate, you get a 409 error code, showing the duplicate already exists. If there are any duplicates in a batch import of redirects, the entire batch is rejected. However, we notify you in the cockpit of the specific duplicate entries so you can remove them from the batch.

  • Only 3xx status codes are acceptable. Different codes affect the browser in different ways. For more, see HTTP redirections on MDN.

  • If there is an issue with your .csv import when you import redirects, the dialog will inform you of what the issue is so you can remedy it.

  • Some applications (like Microsoft Excel) wrap quotations (") around CSV lines. You need to remove those quotations if importing or adding a redirect in the Cockpit.

  • You can use RE2 syntax.

    Regex example

    https://www.example.com/[0-9]{2}(bar|baz) matches https://www.example.com/01bar or https://www.example.com/14baz

    Wildcard example

    https://www.example.com/(.*) -> https://www.example.com/$1.html redirects https://www.example.com/test to https://www.example.com/test.html

Redirect best practices

To meet security and SEO expectations, canonicalize traffic to the https://www.* host through this chain:

http://example.com -> https://example.com -> https://www.example.com

Key Guidelines

  • Ordering matters: Redirects are evaluated in order. Place the exact apex-host redirect above any path-preserving rules to avoid unintended behavior.
  • TLS coverage: Ensure your TLS secret covers both example.com and www.example.com in the same Ingress to avoid certificate mismatches.
  • Single Ingress: Use one MgnlIngress. The rule host is the canonical host (www). Put both example.com and www.example.com on the same TLS secret. fromToWwwRedirect sends the other host to the canonical one.
  • Explicit 308 redirects: Use permanent 308 redirects to preserve HTTP methods. Define two rules:
    • Exact apex-to-www redirect (avoids added trailing slashes).
    • Path-preserving redirect (ensures /page maps to /page on the canonical host).
  • DNS alignment: Ensure DNS A/AAAA records for both example.com and www.example.com point to your Ingress controller.

Example MgnlIngress

HTTP to HTTPS is nginxOptions.forceSslRedirect. Apex to www is nginxOptions.fromToWwwRedirect. The rule host is the canonical host. Both names stay on the TLS secret.

apiVersion: magnolia.info/v1alpha1
kind: MgnlIngress
metadata:
  name: prod-ingress-example-com
  namespace: prod
  labels:
    app.kubernetes.io/managed-by: cockpit
spec:
  acquireCertificate: true
  nginxOptions:
    forceSslRedirect: true
    fromToWwwRedirect: true
  rules:
    - host: www.example.com
      paths:
        - path: /
          pathType: Prefix
          backendName: prod-magnolia-redirects-svc
          backendPortName: http
  tls:
    - hosts:
        - example.com
        - www.example.com
      secretName: prod-ingress-example-com

See Force SSL redirect and From to www redirect.

Example redirect rules (308)

SourceTargetCode
https://example.comhttps://www.example.com308 (exact host)
https://example.com/(.*)https://www.example.com/$1308 (path-preserving)

CSV example

https://example.com,https://www.example.com,308 <1>
https://example.com/(.*),https://www.example.com/$1,308 <2>

The first rule avoids an added trailing slash on the target host.

The second rule preserves paths, for example: https://example.com/page -> https://www.example.com/page.

Redirect filters

The Redirects list is filtered by environment, status, and mode.

The environment list includes a namespace that contains only a redirect server.

You can see a redirect’s status under the Status column.

  • Synced: Published redirect including any changes (if applicable).
  • Created: New redirect; unpublished.
  • Modified: Changes were made to the redirect; unpublished.
  • Deleted: The redirect is marked for deletion; it is removed the next time you publish.

Status

  1. In your Cockpit, go to Networking > Redirects.
  2. Open Status.
  3. Select one or more of Created, Modified, Deleted, or Synced. The table updates as you select them.

Clear Status to show every status.

Mode

  1. In your Cockpit, go to Networking > Redirects.
  2. Open Mode.
  3. Choose Redirect, Forward, Proxy, or Any.

Any shows every mode.

Add redirect server

By default, redirects are served from the backend. However, you can configure the settings to suit your needs if you want to use a Frontend redirect. After adding the redirect server, you can configure and/or uninstall the server as needed. Follow the instructions here to do just that:

Publish redirects

  1. In the Cockpit, go to Networking > Redirects > Redirect server.

  2. Choose the number of Replicas you would like. There is a minimum of 2 redirect server replicas.

    You may choose as many replicas as needed. However, if no more memory is available, the system rejects new replicas.

  3. Under Redirects server, choose Backend (the default configuration for load balancing with DX Cloud) or Frontend (the frontend client distributes traffic to servers).

    If choosing Frontend, you’ll need to pass the port number you want to use, such as 3000.

  4. Under Load balancing, choose Round Robin (client requests go down the list of servers found in a group; the load balancer forwards a client request to each server in turn and loops back to the top when it reaches the end) or Cookie based (the hashed cookie and other parameters are sent to the client in a cookie; the value in the cookie enables the service to route client requests to the correct server) load balancing.

  5. Set your desired Memory limit in MB.

    Memory limit details

    Memory limit specifies the maximum amount of memory (in megabytes) allocated to each redirect server instance. This setting helps ensure each instance runs efficiently under your traffic load.

    When to adjust:

    • High traffic or high availability: Add more replicas for load balancing and high availability; increasing replicas spreads traffic across instances rather than relying on more memory per instance.
    • Resource optimization: Decrease the limit for low-traffic scenarios to optimize resource usage, especially in resource-constrained environments.
    • Frontend vs. Backend: Frontend redirect servers (e.g., using a CDN or JavaScript-based redirects) may require different memory considerations compared to backend servers, as frontend redirects offload some processing to client-side resources.

  6. Don’t forget to save your updates.

Configure redirect server

Once you’ve successfully added a redirect server by following the instructions in Add redirect server and saved your updates, the Add redirect server button in the Cockpit changes to Configure redirect server. Clicking this button opens a dialog where you can:

  • Edit the redirect server settings: Modify the existing configuration, such as the number of replicas, redirect server type, load balancing method, or cookie name (if applicable).

    You can adjust the following settings through the Configure redirect server dialog.

    Consider the following before acting:

    • Number of replicas
      • Increasing replicas: You can add more replicas to handle increased traffic, but sufficient memory must be available. If memory is insufficient, the system will reject the new replicas, leaving your configuration unchanged.
      • Decreasing replicas: Reducing the number of replicas may lower the system’s capacity to manage high traffic loads, potentially degrading performance during peak times.
    • Redirect server type
      • Switching between backend and frontend redirect servers alters how traffic is routed.
      • Switching to frontend: You must specify a valid port (e.g., 3000). If the port is misconfigured or conflicts with other services, traffic may be misrouted, or the service could become unavailable.
      • Switching to backend: This reverts to the default configuration, which may not suit your original intent (e.g., if frontend was chosen for performance or security reasons).
    • Load balancing method
      • Switching to Cookie-Based: You’ll need to provide a cookie name. If sticky sessions are enabled, this name must be different from nginxOptions.stickySession.cookieName on the MgnlIngress. See Map UI fields to manifest.
      • Switching to Round Robin: This eliminates session persistence, which could disrupt applications that depend on consistent server routing (for example, those maintaining user sessions).
      • Cookie name: If sticky sessions are enabled, keep this cookie name different from nginxOptions.stickySession.cookieName. Changing either name can invalidate existing sessions, which may log people out or reset their session.

  • Uninstall the redirect server: Remove the custom redirect server entirely, reverting to the default backend behavior.

    Choosing to uninstall the redirect server removes the custom configuration and reverts the system to the default behavior (backend redirect server).

    Consider the following before acting:

    • Loss of custom benefits: Any advantages gained from the custom redirect server (e.g., optimized traffic distribution, frontend-specific routing) will be lost.
    • Service disruptions: Applications or services that depend on the custom redirect server may encounter errors or downtime if the default backend configuration doesn’t suit their needs.

Add redirects

  1. Go to Networking > Redirects.
  2. Add a single redirect, or import redirects from a CSV file.

Add redirect

  1. Click Add. This opens a page where you configure the redirect.

  2. Under Source, enter the source. Use Query to match a query string, or select The rule is strictly for clean URLs so requests that include query parameters do not match.

  3. Under Match conditions, optionally select Countries and Accept languages. These conditions apply in every mode.

  4. Select the Mode:

    • Redirect (default): sends an HTTP 3xx to a new URL.
    • Forward: proxies to a hostname, internal or external.
    • Proxy: proxies to a Service in this environment.

  5. Under Target, fill in the fields for that mode.

    • Redirect: select the HTTP status code, enter the target, and optionally set Target query.
    • Forward: enter the target.
    • Proxy: select a service and, if needed, a pathname suffix.

  6. Click Save.

Import redirects (CSV)

  1. Click Import CSV.
  2. Choose a .csv file. The dialog shows the required columns.
  3. To set rule order from the file, select Reorder items to match this CSV’s order. The file must then list every existing redirect, with the same number of rows as the current list, and every row must have an Id. Omitting an existing redirect is rejected.
  4. Click Import CSV.

Format

Id,Source,Target,Code,Query,QueryTarget,Mode,Country,Language <1>

Mode is REDIRECT (default), FORWARD, or PROXY. Only 3xx HTTP codes are used when Mode is REDIRECT. Leave Code and QueryTarget empty for FORWARD and PROXY. When Mode is PROXY, Target is a service reference such as http://service-name:8080/foo/$1, not an external URL. See Proxy. Id is optional. If an Id is provided, the system tries to match it with an existing record and update it. If blank or no match is found, a new record is created.

Example

Id,Source,Target,Code,Query,QueryTarget,Mode,Country,Language
19514,https://www.example.com,https://www.example.be/foo.html,308,,,REDIRECT,,
,https://www.example.com/[0-9]{2}(bar|baz),https://www.example.be/barbaz.html,,,,FORWARD,"AE,AF,PL",pl
,https://www.example.com/app/(.*),http://service-name:8080/foo/$1,,,,PROXY,,

Redirect field reference

Source

The Source controls when this rule matches.

Enter a full URL or a pathname alone (for example, example.com/blog/.*, https://example.com/old-page, or /blog/.*). The pathname can be plain text or a regular expression. A pathname-only source matches any domain or subdomain. When the source includes a host, that host must be a recognized host for the environment. Use Show all recognized hosts to see the list.

Select The rule is strictly for clean URLs when the rule should match only requests with no query string. Requests that include query parameters do not match that rule.

Query

Query further restricts which requests match, based on the query string. Enter only the part after ?, without the leading ? (for example, utm_source=google or utm_source=.*). The value can be a plain query string or a regular expression. If you leave Query empty, any query string matches as long as the source matches. This field is unavailable while The rule is strictly for clean URLs is selected.

Countries

Under Match conditions. These apply in every mode.

Restrict this redirect to visitors from specific countries. Matching uses the client IP geolocation.

Select one or more countries from the dropdown. When set, only visitors from the selected countries match. Visitors from other countries are not affected.

Leave empty to match any country.

Accept languages

Under Match conditions. These apply in every mode.

Restrict this redirect based on the visitor’s browser language settings.

Select one or more languages from the dropdown. The rule matches when the visitor’s browser Accept-Language header matches. The first match is accepted.

Leave empty to match any language.

Mode

The Mode controls how a matching request is handled. The default is Redirect. Changing mode clears the target you already entered.

  • Redirect: sends an HTTP 3xx to a new URL. Choose a status code. The browser’s URL changes to the target.
  • Forward: proxies to a hostname, internal or external. No redirect is sent to the client. Code and Target query are not shown.
  • Proxy: proxies to a Service in this environment. No redirect is sent to the client. Code and Target query are not shown.

Code

Shown only when Mode is Redirect.

The HTTP status code sent to browsers and search engines.

Permanent redirects (SEO value transfers to new URL):

  • 301: Moved Permanently. Standard permanent redirect for GET requests.
  • 308: Permanent Redirect. Like 301, but preserves POST/PUT request methods.

Temporary redirects (original URL retains SEO value):

  • 300: Multiple Choices. Indicates multiple redirect options.
  • 302: Found. Standard temporary redirect.
  • 303: See Other. Redirects POST to GET (e.g., after form submission).
  • 307: Temporary Redirect. Like 302, but preserves POST/PUT request methods.

Target

For Redirect and Forward, Target is where matching requests are sent (for example, https://example.com/new-page). The pathname can be plain text or a regular expression, and it can reference capture groups from the source pattern ($1, $2).

Forward and Proxy rules can still match on the query string, but they do not rewrite it.

Proxy

Proxy sends the request to a Service in the same environment. The browser URL stays on the source.

Select Service. The list shows http and https ports for services in this environment, in the form http://service-name:port. The redirects service itself is not listed. The picker is available only when Magnolia is installed in the environment. If it is not, the field stays disabled.

The saved target looks like http://service-name:8080/foo/$1.

Pathname suffix

Optionally set Pathname suffix (for example, /foo/$1). It is appended after the selected service. It can be plain text or a regular expression, and it can reference capture groups from the source pattern ($1, $2).

Target query

Target query is shown only for Redirect. It rewrites the outgoing query string and can reference capture groups from the Query pattern ($1, $2). Enter only the part after ?, without the leading ? (for example, campaign=flash or $1). Leave it empty to pass the original query string through unchanged.

For background on redirect configuration, see Redirects.

Manage redirects

You can edit, move, or delete a redirect from the list.

  1. Go to Networking > Redirects.
  2. Choose the Environment.

Edit

  1. Click the pencil on the redirect’s row. This opens the same page as Add redirect.
  2. Change the fields you need.
  3. Click Save.

Move

Move changes the rule’s position. Lower numbers are matched first.

  1. Open the actions menu on the redirect’s row.
  2. Click Move.
  3. Move it to a specific position, or place it before or after another rule.
  4. Confirm the move.

Delete

  1. Open the actions menu on the redirect’s row.
  2. Click Delete.
  3. Confirm that you want to delete the redirect.

The redirect is marked Deleted until you publish.

Publish redirects

You must publish any changes you’ve made to redirects from within the Cockpit.

  1. Go to Networking > Redirects.
  2. Make changes as desired inside the Redirects screen.
  3. Click Publish all.
  4. Enter a meaningful message so it’s easier to understand what changes were made. This is useful if you need to restore changes.
  5. Click Publish all.

Restore redirects

You can restore redirects that you’ve published.

  1. Go to Networking > Redirects.
  2. Click Restore.
  3. Select a version from the dropdown list.
  4. Click Restore.

Download redirects

  1. Go to Networking > Redirects.

  2. Click Download to download every listed redirect, then confirm.

    To download some of them, select those rows first, then click Download and confirm.

  3. This generates a .csv file with the same columns as Import redirects (CSV):

    Id,Source,Target,Code,Query,QueryTarget,Mode,Country,Language