Set the CXDOT Collector schema version - Cortex XCOR Documentation

The CXDOT Collector uses schema versions so that you can upgrade the Collector without needing to rewrite your configuration file. If your specified schema version is older than the active version of your CXDOT Collector, the Collector validates your configuration file using the schema and default values defined by the schema version, then translates your configuration settings to their equivalent format in the active version. For example, if a YAML configuration key named address was renamed to ip_address in v1.15, but your configuration file specifies schema_version: v1.14, the Collector continues to expect the address key in your configuration file.

When the CXDOT Collector translates configuration settings from the specified schema version, it doesn’t modify your configuration file.

Set the schema version

Use the schema_version field in your configuration file to set the schema version for your CXDOT Collector configuration file. Replace VALUE with the version to use (for example, v1.14).

Helm values file
Configuration file

values.yaml

config:
  schema_version: VALUE

config.yaml

cxdot:
  schema_version: VALUE

The schema_version field is required in all Collector configuration files. When you install the CXDOT Collector in a Kubernetes cluster, you must specify this value in your Helm values file. When you install the CXDOT Collector in a Linux or Windows environment, the example configuration file includes this field already.

Upgrade the Collector without updating the schema version

If you upgrade the CXDOT Collector to a newer version, but want to continue using the same schema version, leave the schema_version field unchanged in your configuration file.

The schema version only governs settings and behavior specific to the CXDOT Collector. When you upgrade the Collector to a newer version based on an upgraded version of the upstream OpenTelemetry Collector, changes in upstream components will still take effect.

Update schema version

Update the CXDOT Collector’s schema version when you need to use a configuration setting or integration that was introduced in a newer release than your current schema version. To use a newer schema version, update the value of schema_version, then update your configuration file so that the change takes effect. Before you update to a newer schema version, compare your current configuration file with the translated version to identify the settings you need to change before you adopt the newer schema. The Collector rejects configuration settings that don’t exist in the specified schema version. This means that if a field was renamed or removed prior to the newer schema version, you must rename or remove that field accordingly in your configuration file. Default values for certain configuration settings can change between Collector releases. This means that settings not specified in your configuration file might change behavior in a newer schema version. For information about the available versions of the Collector and the changes associated with each, including breaking changes, review the release notes in Palo Alto Networks Cortex XCOR. In the navigation menu, select More information > Release notes, and then click the CXDOT Collector tab.

View the translated version of your configuration file

When you use a schema version earlier than the Collector’s active version, the Collector translates your configuration settings to their equivalent format in the active version, but doesn’t modify your configuration file. To view the schema-translated version of your configuration file, use the CXDOT Collector debug interface to query config/migrated.yaml. You can compare this file against your original configuration file to identify any fields that were renamed or removed between the schema version and the active version. To inspect the differences between your original configuration file and the translated configuration file, ensure that the debug interface is enabled, then run the following commands:

Kubernetes
Linux
Windows

kubectl exec --namespace cxdot POD -- \
  /bin/cxdot-admin debug get config/original.yaml > original.yaml

kubectl exec --namespace cxdot POD -- \
  /bin/cxdot-admin debug get config/migrated.yaml > migrated.yaml

diff -u original.yaml migrated.yaml
rm original.yaml migrated.yaml

Replace POD with the name of the CXDOT Collector Pod whose configuration you want to inspect.

cxdot-admin debug get config/original.yaml --socket PATH > original.yaml
cxdot-admin debug get config/migrated.yaml --socket PATH > migrated.yaml
diff -u original.yaml migrated.yaml
rm original.yaml migrated.yaml

Replace PATH with your configured debug socket path. If you use the default socket path, or if the CXDOT_DEBUG_SOCKET environment variable is set, omit --socket PATH.

$Original = & .\cxdot-admin.exe debug get `
  --socket "PATH" `
  config/original.yaml

$Migrated = & .\cxdot-admin.exe debug get `
  --socket "PATH" `
  config/migrated.yaml

Compare-Object -ReferenceObject $Original -DifferenceObject $Migrated

Replace PATH with your configured debug socket path. If you use the default socket path, or if the CXDOT_DEBUG_SOCKET environment variable is set, omit --socket "PATH".In the resulting output, <= identifies lines from the original configuration, and => identifies lines from the migrated configuration.

​Set the schema version

​Upgrade the Collector without updating the schema version

​Update schema version

​View the translated version of your configuration file

Set the schema version

Upgrade the Collector without updating the schema version

Update schema version

View the translated version of your configuration file