Sidecar startup requirements

Role of manifest.yaml

The manifest.yaml file informs splunk-supervisor which sidecars are available to run and how to load their packages. It is located at $SPLUNK_HOME/etc/packages/manifest.yaml. For each sidecar, manifest.yaml has a package entry that identifies the sidecar, its tarball, and, optionally, the feature that controls whether the supervisor starts it.

Treat manifest.yaml file as read-only. Splunk checks the file checksum and reports if it has been modified. If the file is malformed or a referenced tarball is missing, the manifest fails to load.

How conditional startup works

If a package entry names a feature, the supervisor checks that feature requirements against .conf values returned by Splunk HTTP API.

• If all requirements pass, the supervisor includes the package in its package configuration and starts the corresponding sidecar.
• If any requirement in not met, the supervisor excludes the package and does not start the corresponding sidecar.
• A feature can control multiple package entries, allowing the supervisor to start their sidecars together.
• A sidecar whose package entry does not name a feature is always included and is not controlled by feature requirements.
• When a feature has no requirements, the supervisor can include its packages if the feature is compatible with the FIPS mode. When Splunk Enterprise runs in FIPS mode, a feature must declare FIPS support for the supervisor to include its packages.

As a result, the supervisor starts sidecars only when their corresponding features in the Splunk platform are activated, avoiding starts when those features are deactivated.

The manifest.yaml file can contain two top-level lists:

• Packages, which identify sidecars and their tarballs.
• Features, which can define requirements that the supervisor checks to determine whether it starts the corresponding sidecars.

Packages, features, and requirement flags

The manifest.yaml files connects three pieces:

• packages identify sidecars and their tarballs. Each package entry includes the following fields:
  • name - The sidecar name
  • file - The name of the sidecar tarball file. Tarballs are stored in the $SPLUNK_HOME/opt/packages/ folder.
  • signature - The cryptographic signature for the sidecar tarball.
  • (Optional) feature field - The name of the feature that controls whether the supervisor includes the package and starts the sidecar. Multiple package entries can use the same feature.
• features define the conditions for including packages assigned to it. A feature includes the following fields:
  • name - The feature name that a package references in the feature field.
  • (Optional) essential - Marks the feature (sidecar) as part of the sidecar infrastructure, like IPC Broker and Spotlight.
  • supports - Environment properties that the feature supports. When Splunk Enterprise runs in FIPS mode, a feature must declare FIPS support for the supervisor to include its packages.
  • (Optional) requirements - Conditions read from the Splunk platform .conf files. All requirements must pass to activate the the feature.
• requirements.flags are configuration checks nested under the feature requirements field. Every flag must pass for the supervisor to include the feature packages.

Each flag identifies a configuration setting using:

• file - The .conf file name without the .conf suffix, for example server.
• stanza - The stanza containing the setting.
• key - The setting name.
• expected_values - The values that satisfy the check. When this field is present, the current value must match one of its listed values. When omitted or empty, any successfully read value satisfies the flag.
• (Optional) cache_ttl_minutes - The minimum time, in minutes, before the supervisor queries the Splunk HTTP API for the value again. A value of 0 or less uses the default cache duration of 60 minutes.

If a feature has several flags, every flag must pass. Otherwise, the supervisor excludes the feature packages. A package assigned to a deactivated feature is not included in the supervisor package configuration.

Example

In this example, the postgres package entry assigns the postgres sidecar to the postgres feature. The supervisor checks the disabled setting in the [postgres] stanza of server.conf. It includes the package and starts the sidecar only when the setting value matches an expected value.

features:
  - name: postgres
    supports:
      - FIPS140-3
    requirements:
      flags:
        - file: server
          stanza: postgres
          key: disabled
          expected_values:
            - "false"
            - "0"
            - ""
          cache_ttl_minutes: 5

packages:
  - name: postgres
    file: postgres-package.tar.gz
    signature: <package-signature>
    feature: postgres