Skip to main content

Reserved Fields Consistency Validator

Overview​

The "Reserved Fields Consistency Validator" feature is designed to ensure that specific fields within the YAML descriptor of an entity remain unmodified from their original values. This documentation provides an overview of how to configure and utilize the Reserved Fields feature effectively.

Configuration​

To configure the Reserved Fields Consistency Validator feature, you have two parts to consider: global and local fields.

Global Fields​

In the global section of the configuration, you can enable the Consistency Validator feature for the fields metadata.name and kind of the entities. This means that the validator will work for all kinds of entities. You can set the name and kind fields to either true or false to enable or disable the validator for each field, respectively.

Example:

mesh:
  reservedFields:
    global:
      name: <true/false>
      kind: <true/false>

Local Fields​

In the local section of the configuration, you can define specific reserved fields for different entity kinds. This allows you to customize reserved fields based on the type of entities you are working with. You can specify the entity kind and its paths

Example:

mesh:
  reservedFields:
    local:
      myKind:
        - 'path.one'
        - 'path.two'
      anotherKind:
        - 'path.one'

You can add more entries to define reserved fields for other kinds as needed.

note

You cannot enable the validator feature for metadata.name and kind with respect to different kinds; they can only be set at the global level. Similarly, you can specify kind-path values only for local fields.

Example configuration:

mesh:
  reservedFields:
    global:
      name: true
      kind: false
    local:
      system:
        - 'spec.mesh.email'
      component:
        - 'spec.mesh.email'
        - 'spec.domain'

In this example, the validator is enabled for the metadata.name field of all kinds. It is also enabled for the spec.mesh.email field of entities with the System and Component kinds, and for the field spec.domain of entities with the Component kind.

With this configuration, the Reserved Fields Consistency Validator will ensure that the specified fields remain unmodified for the entities of the specified kinds. If any reserved field are modified, the system will detect the change during the next entity refresh, and the entity will display an error in the UI, telling you to restore the original fields' names.

To resolve this issue, you must edit the entity yaml descriptor and return the reserved fields to their previous values. After restoring the fields you can trigger a refresh, or you can wait for the scheduled refresh to happen automatically. After the system detects that the original entity has been restored, it will delete all invalid duplicates

You can see the consistency status of an entity in its metadata.annotations field if you inspect the entity.

Once an entity has been marked an invalid, it will forever continue to be invalid. If you delete the original entity after its name or kind changed and a duplicate was generated, you can still modify restore the reserved fields value to their previous ones, and the original entity will be generated once again.

Disabled entities and kinds​

The Consistency Validator feature is selectively disabled for certain entities and kinds to ensure accurate processing. Here are the exceptions:

Entities Originating from url​

The Consistency Validator is disabled for entities that originate from a location with type url. This exclusion is to accommodate entities that are loaded externally, such as those obtained from a file or ingested through protocols like AD (Active Directory) or LDAP (Lightweight Directory Access Protocol).

Disabled Kinds​

The feature is disabled for entities with the following kinds:

  • Location
  • User
  • Hierarchy
  • HierarchyClass

Entities of these kinds will not undergo Consistency Validator checks during processing. The exclusion is intentional to suit specific use cases where validator verification is not applicable or relevant.