Mach5 Search v5.9.0 - Migration Guide

This guide provides step-by-step instructions for upgrading an existing Mach5 deployment to v5.9.0. It covers breaking changes, required admin actions, Keycloak role migration, and configuration updates.

Release notes v5.9.0

Authentication and Authorization Migration

Mach5 v5.9.0 introduces significant changes in how roles are defined, assigned, and interpreted. These changes apply to all installations with authentication and authorization enabled in previous versions of Mach5.

Additional Documentation

Role Migration (Realm Roles → Client Roles)

What changed

  • Roles are no longer defined as realm roles.
  • All Mach5 roles are now client roles under the Mach5 client in the Default realm.
  • Authorization patterns (e.g., namespace:*/read) now follow updated semantics.

Required Actions

Unassign old realm roles

For all users:

  • Remove:

    • m5-admin
    • Any other Mach5-related realm roles

Create equivalent client roles

Under:

Realm: default
Client: mach5 (or your configured CLIENT_ID)

Recreate any custom roles as client roles, following the updated role-pattern rules.

Assign new client roles

For each user:

  • Assign admin (new client role) if they previously had m5-admin
  • Assign migrated custom client roles as needed

Optional cleanup

You may safely delete obsolete realm roles.

Resource Authorization Now Enforced

Prior versions did not verify user permissions for resources. Mach5 v5.9.0 enforces authorization for all entities. This include namespaced entities like connections, ingest pipelines, index, etc and non namespaced entities like store, store route, etc.

If your deployment relied on unrestricted search, ensure users now have the proper client roles.

NGINX / Keycloak InitContainer Changes

Init flow now ignores Keycloak bootstrap errors

This allows administrators to:

  • Change the default admin user
  • Remove the default admin user
  • Reset credentials

without breaking the NGINX init-container execution.

No action required.

Notebooks API Migration (ID → Name)

Notebook APIs now use names instead of IDs.

Breaking Change

Update these endpoints:

OperationPrevious Versionsv5.9.0+
ReadGET /namespaces/{namespace}/notebooks/{id}GET /namespaces/{namespace}/notebooks/{name}
UpdatePATCH /namespaces/{namespace}/notebooks/{id}PATCH /namespaces/{namespace}/notebooks/{name}
DeleteDELETE /namespaces/{namespace}/notebooks/{id}DELETE /namespaces/{namespace}/notebooks/{name}

Actions:

  • Update all API clients and scripts.
  • Ensure Notebook names are unique and stable.

For more details on notebooks: Notebooks in Mach5

values.yaml Migration

User-provided Keycloak Master Realm credentials

You may now supply your own secret:

keycloak:
  master:
    secret:
      create: false
      name: keycloak-secret
      pwdkey: master-password
      userkey: master-username

## When create is false, i.e. user provided secret
# create: false
# name: keycloak-secret ## This secret name is provided

## apiVersion: v1
## kind: Secret
## metadata:
##   name: keycloak-secret
##   namespace: mach5
## type: Opaque
## data:
##   master-password: "...." ## base64 encoded password for the master realm
##   master-username: "...." ## base64 encoded username for the master realm

User-provided Default Realm Client secret

Provide your own client secret:

keycloak:
  client:
    secret:
      create: false
      name: keycloak-default-client
      namekey: name
      clientsecretkey: clientsecret

### When create is false, i.e. user provided secret
# create: false
# name: keycloak-default-client ## This secret name is provided

## apiVersion: v1
## kind: Secret
## metadata:
##   name: keycloak-default-client
##   namespace: mach5
## type: Opaque
## data:
##   name: "...." ## base64 encoded value of default realm client name (eg. mach5)
##   clientsecret: "...." ## base64 encoded value of the client secret you want to set

User-provided License secret

license:
  createSecretResources: false
  name: license-secret
  metered: false

### When createSecretResources is false, i.e. user provided secret
# createSecretResources: false
# name: license-secret ## This secret name is provided

# apiVersion: v1
# kind: Secret
# metadata:
#    name: license-secret
#    namespace: mach5
# type: Opaque
# data:
#    .licensemode: "VE9LRU4=" ## base64 encoded value of mode = TOKEN
#    .licensetoken: "...." ## base64 encoded value of licensetoken

Additional annotations for NGINX service

For LoadBalancer or other cloud provider annotations:

nginx:
  annotations:
    my-custom-annotation: "true"
    another-custom-annotation: "true"