About the Centralised Config app

The Centralised Config app manages Geneos Gateway configuration centrally on ITRS Analytics. Instead of maintaining setup files separately on each Gateway host, you can store configuration in the ITRS Analytics platform, control who can modify it, and apply updates through a consistent workflow in the Web Console.

Using the Centralised Config app, you can:

• Create and manage Gateways and resources, particularly Gateway setup files.
• Associate shared setup files with one or more Gateways.
• Lock resources while editing, assign read/write permissions by role, and review version history.
• Upload and manage Gateway binaries used for validating configuration changes.

Use cases Copied

Centralised Config is intended for teams that operate multiple Geneos Gateways and want consistent, controlled configuration management. Typical benefits include:

• A single source of truth for Gateway setup on the platform.
• Reuse of common setup files across Gateways without duplicating content.
• Safer change workflows through validation, locking, and history.
• Role-based access so administrators and operators can share responsibility for different setup files.

Prerequisites Copied

Centralised Config uses IAM for both user and Gateway authentication.

IAM client configuration Copied

By default, the app Helm configuration provisions a dedicated IAM client named geneos-gw with the following settings:

iam:
  clients:
    geneosGw:
      name: geneos-gw
      serviceAccountsEnabled: true
      authorizationServicesEnabled: true
      directAccessGrantsEnabled: true
      publicClient: false
      implicitFlowEnabled: false
      webOrigins:
        - +
      redirectUris:
        - geneos-gw

The geneos-gw client automatically generates a client secret upon installation of the Centralised Config app.

IAM roles Copied

The IAM admin role is required for privileged operations such as:

• deleting resources and Gateways
• setting resource permissions
• uploading and deleting Gateway archives
• force-modifying or force-deleting resource locks

Users with the admin role always have read and write access to resources. Other roles may still be configured read and write permissions per resource.

Key terms Copied

The app stores three related but separate items:

In the UI, the Gateways section lists all centrally configured Gateways, the Resources section lists all Gateway setup files, and Binaries lists uploaded Gateway versions.

Note

The same Gateways, Resources, and Binaries described above can also be managed through the Centralised Config REST API, including Gateway registration and setup changes, resource creation and permissions, and Gateway binary uploads for validation.

Configure Gateways Copied

Connect and authenticate the Geneos Gateway Copied

The Geneos Gateway uses an application key file (-app-key) to obtain a token from ITRS Analytics for Centralised Config APIs.

The running Gateway can create its own platform record on first connect, for example, on a host install where you start the process directly, or in Kubernetes and Helm deployments. See Connecting to ITRS Analytics for the Helm equivalent.

1. Create the app-key file once per Gateway host. Store the file securely.

   ./gateway2.linux_64 -store-app-key app-key.txt geneos-gw <client_secret> obcerv
   

   Expand table

   Parameter	Typical value for ITRS Analytics
   File name	Your choice (for example app-key.txt)
   Client ID	geneos-gw
   Client secret	Generated by the geneos-gw client upon installation of the Centralised Config app
   SSO provider	obcerv

2. Start the Gateway in centralised-config mode (with -gateway-name, -iax, and -app-key, and no local -setup file):

   ./gateway2.linux_64 \
     -iax https://<platform-url> \
     -gateway-name <gateway_name> \
     -app-key app-key.txt
   

On first startup, the Gateway:

• Obtains a token using the app-key file (app-key.txt).
• Searches Centralised Config for a Gateway with the same name as -gateway-name.
• If none exists, calls POST /configuration/gateways with that name and the Geneos version of the running binary.
• Loads setup from the platform, including the main resource Gateway/<gateway_name> when newly created.

You can also create a Gateway in Centralised Config using the POST /configuration/gateways endpoint. The request must include:

• a unique Gateway name
• the Geneos version the Gateway will run (for example, GA7.3.0-...)

The app creates a Gateway record and a main setup resource named Gateway/<gateway_name> with a minimal valid Gateway setup.

Modify resources used on a Gateway connection Copied

You need admin rights to change a Gateway configuration.

1. On the Gateways section, click a Gateway name. This reloads the Resources section with a list of files used by the Gateway.
2. Review the resources that the selected Gateway is currently using.

To use the uploaded file on a Gateway, open that Gateway in Gateways, review its current resources, and add your resource from the available resources list. Removing a resource from a Gateway stops that Gateway from using it but does not delete the resource from the platform.

Configure resources Copied

Add a resource from the UI Copied

Adding a resource from the Centralised Config app UI registers the XML as a shared configuration resource on the platform. The app stores the content, assigns a resource ID and version, and records who uploaded it and when. The upload does not attach the file to any Gateway automatically, and a running Geneos Gateway does not use the new content until you link it to a Gateway and apply validated setup changes.

1. Click Add Resources.
2. Upload one or more Gateway setup XML files.
3. Enter a name for each resource. Resource names are case-sensitive and must not start with the prefix Gateway/ as that prefix is reserved for a Gateway’s main setup resource. If no name is set, the filename is used as the resource name by default.
4. Click Save to create each resource in the app. Each resource is stored with type GatewaySetup.

Note

Uploaded setup XML must not contain a gatewayName element under /gateway/operatingEnvironment. The app rejects resources that include it. The Gateway’s main setup resource supplies the Gateway name when configuration is applied.

From the Resources section, you can:

• Search and browse all uploaded setup files.
• Review logs and compare XML between versions
• Set read and write permissions by role . Users with the admin role always have full access.
• Lock or unlock a resource while editing
• Delete a resource

Resource permissions and locking Copied

Each setup file can have role-based permissions and an edit lock. Permissions control who may change a resource, while a lock stops other users from modifying it while someone else is editing.

Permissions Copied

• Assign read and write to one or more platform IAM roles using the key icon on the resource row. Only users with the admin role can change permissions.
• Users with admin always have full read and write access, regardless of the lists you set.
• If you leave a role list empty when saving, the app treats that access level as all roles (*).
• Until permissions are set for a resource, the app does not restrict access by role (other platform controls still apply).

To manage permissions through the REST API (retrieve or update permissions), see Resource permissions in the Centralised Config API reference.

Locks Copied

• A lock marks a resource as in use for editing. Validate-and-apply and other changes are rejected when a resource is locked by another user or you lack write access.
• Locks expire automatically after five minutes. Expired locks are removed when the app next checks the resource. If the same user locks a resource again (through the REST API or Geneos Gateway Setup Editor), the lock is renewed and the five-minute window restarts.
• A lock is tied to the resource’s current content hash. If the file changes underneath, the lock no longer matches and cannot be used to apply stale changes.
• admin users can force-unlock a resource held by someone else.
• Updating a Gateway’s Geneos version (PUT gateway version) is not blocked by resource locks held by another user. Setup changes, resource edits, and deletes still respect locks.

To manage locks through the REST API (create, delete, or retrieve lock information), see Resource locking in the Centralised Config API reference.

Add or change resources from the Geneos Gateway Setup Editor Copied

The Geneos Gateway Setup Editor applies changes to the Centralised Config app through REST API following this workflow:

1. Validate the proposed Gateway setup change using the POST /configuration/gateways/{gatewayId}/validations endpoint.
2. Apply the validated change to update the Gateway’s resources on the platform using the POST /configuration/gateways/{gatewayId}/changes endpoint.

When applying changes, include all resources currently used by the Gateway. The app updates the Gateway’s resource associations to match the list you submit. Changes may be rejected if:

• The setup change has not been validated.
• Validation reported Critical or Fatal severity for the Gateway.
• A modified resource is locked by another user.
• You do not have write access to one or more resources.
• A resource hash does not match the latest version of that resource.

Create a resource with the REST API Copied

Use this procedure to add a standalone setup file to the resource catalogue, similar to when uploading resources through the app UI. It does not validate setup, attach the file to a Gateway, or update a running Gateway.

Use the POST /configuration/gateways/resources endpoint. This requires you to provide a JSON metadata for the resource and an XML file or a gzipped XML file for larger contents. For example:

Create resource.json:

{
  "name": "Samplers/Infrastructure",
  "type": "GatewaySetup"
}

Create contents.xml:

<gateway compatibility="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/GA3.0.0-121008/gateway.xsd">
  <samplers>
    <sampler name="CPU">
      <plugin>
        <cpu/>
      </plugin>
    </sampler>
  </samplers>
</gateway>

Upload both parts as multipart form data:

curl -F "resource=@resource.json;type=application/json" -F "contents=@contents.xml;type=application/xml" https://obcerv.com/rest/centralised-config/v1/configuration/gateways/resources

Upload binaries Copied

As in the Geneos Gateway Setup Editor (GSE) where you validate setup before saving to catch configuration errors, the Centralised Config app requires validation before setup changes are applied. The app runs the real Geneos Gateway binary for that check. You must upload a Gateway archive for each unique centralized Gateway version you use. Gateway archives can be downloaded from the official ITRS Downloads page.

Note

Only Linux (linux-x64) binaries are supported for validation.

Gateway archives can be uploaded to the app by copying them to a specific directory (/gateways/archives/) in the app’s backend pod. When preparing a Gateway archive, ensure that:

• The upload file is a compressed archive (.tar.gz).
• The archive contains the Linux Gateway binary at gateway/gateway2.linux_64.
• A corresponding commit marker file (<archive-name>.commit) is created.

The upload can be done with the following commands:

Note

The commands below use the iax-app-centralised-config-daemon label and container name. In some production environments, the Helm release may still use obcerv-app-centralised-config naming instead.

Before running these commands, confirm the label and container names in your namespace:

kubectl get pod -n <namespace> \
  -l 'app.kubernetes.io/name in (iax-app-centralised-config-daemon, obcerv-app-centralised-config-daemon)' \

Replace the iax alias in the commands below if they differ.

# Set the path to the Gateway archive
gatewayArchive=geneos-gateway-6.3.0-linux-x64.tar.gz
# Get the name of the app's backend pod
daemonPod=$(kubectl get pod -l app.kubernetes.io/name=iax-app-centralised-config-daemon -o jsonpath="{.items[0].metadata.name}")
# Copy the Gateway archive to the pod
kubectl -n <namespace> cp $gatewayArchive -c iax-app-centralised-config-daemon $daemonPod:/gateways/archives/
# Create a 'commit' file with the same name as the gateway archive (e.g. "geneos-gateway-6.3.0-linux-x64.tar.gz.commit")
touch "${gatewayArchive}.commit"
# Copy the commit file to the pod.
kubectl -n <namespace> cp "${gatewayArchive}.commit" -c iax-app-centralised-config-daemon $daemonPod:/gateways/archives/

Note

You may need to wait 10 to 30 seconds for the uploaded binaries to appear listed in the UI.

When uploading a Gateway binary, the UI does not display any error messages or notifications if the upload fails. To troubleshoot issues, use the following command to view the most recent log entries from the app’s backend pod:

kubectl -n <namespace> logs --tail=<number-of-lines> $daemonPod

To see the list of uploaded binaries, click Binaries. To delete a binary file, click next to its file name.

Validate Gateway setup Copied

Validation checks proposed Gateway setup, which includes the XML resources a Gateway would use. It does not test whether a Geneos Gateway process is connected or running.

Ensure that:

• A Gateway record exists with the correct Geneos version.
• A matching Gateway binary archive is available under Binaries.
• The validation request lists the Gateway’s main setup resource and all include resources, with content hashes that match the versions you intend to validate. If you supply new XML for a resource, you must have write access to that resource and it must not be locked by another user.

The app checks that you are allowed to change the Gateway setup files (the main file plus any includes), then tests the setup with the Geneos Gateway binary that matches the Gateway’s version under Binaries. You then receive a list of messages that describe any problems found. If a shared file is used by more than one Gateway, the app checks each affected Gateway.

Who performs validation Copied

Validation is performed through the Geneos Gateway Setup Editor or the Centralised Config REST API. The following is an example of a typical REST workflow:

Validation results and applying changes Copied

Each message includes a severity. The app distinguishes at least Error, Critical, and Fatal levels. Critical and Fatal issues block applying setup changes for that Gateway until the configuration is fixed and validated again.

To apply setup changes (through the REST API or Geneos Gateway Setup Editor), you must:

1. Validate the same configuration you intend to apply.
2. Apply the change while the validation result is still trusted (the app matches the configuration hash from validation to the apply request).
3. Ensure no Critical or Fatal validation messages remain for that Gateway.

Setup changes are rejected if validation was skipped, the configuration hash does not match a recent validation, a resource is locked by another user, you lack write access, or a resource hash is out of date.

View the version history of resources and Gateways Copied

Centralised Config stores a version each time a resource or Gateway configuration changes. If you have read access to the resource or Gateway you want to query, you can list historic versions through the REST API and retrieve metadata or XML for a specific version.

Additionally, in the Web Console, you can open a resource and use the icon to browse versions and compare XML in the UI.

Gateway version history Copied

Each Gateway history entry includes the Gateway id, name, Geneos version, docVersion, the resources associated with that Gateway at that point in time, and an optional setupValidationId if the change was validated.

Resource version history Copied

History entries are returned newest first. Each entry includes lastChangedBy, lastChangedOn, hash, version, and an optional comment from the setup change that created it.

Pagination Copied

History queries support skip and limit query parameters:

• skip defaults to 0
• limit defaults to 100

When more results exist than returned in one response, the Has-More header is true. You can increase skip and repeat the request until Has-More is false.