nevisadmin-plugin-base-generation

Generic Deployment

Use the advanced pattern for the following use cases:

• Deploy files and scripts for your own custom component or application.
• Modify remote system configuration files.
• Patch files generated by other nevisAdmin 4 patterns (not recommended).

The pattern cannot be used when deploying to Kubernetes.

Note that the third option is not recommended. Instead, please explore the various Generic patterns which can configure many low-level options. If you cannot find a solution, please open a Nevis Support ticket. Support may be able to provide an alternative, or can create a product improvement request.

Path

Absolute path of a directory on the target host(s) where the files will be deployed to. The command will run from the same path.

nevisAppliance targets only: if the files must be persisted across reboots, use a file name or path listed in the /etc/rwdisk.conf file on the nevisAppliance target host.

The path must not point into a directory (potentially) managed by a nevisAdmin 4 Instance Pattern. Thus, it is not possible to directly overwrite files generated by other patterns. See Command and Command: Execution File Triggers for an alternative solution to overcome this limitation.

Allowed Paths:

• /tmp/generic-deployment
• /var/opt/<directory>

Example:

• /tmp/generic-deployment/patch01/

Path: Delete Unknown Files

If enabled, all files in the directory (Path property) that are not specified under Files are deleted.

If you enable this property your files must be in one of the following directories or subdirectories:

• /var/opt
• /tmp
• /home

Files

Upload the files which will be copied into the Path.

To upload files into subdirectories within Path, add a single .zip file with files and directories. Unpacked files will have Owner and Group applied. Note: If multiple files are uploaded, any .zip file is deployed as is, without being extracted.

It is not supported to overwrite files generated by other patterns. See also Path above.

Template Parameters

Define Template Parameters.

Examples:

smtp: smtp.siven.ch
sender: [email protected]

These parameters can be used in:

• uploaded files matching an expression specified in the Template Files property
• the value of the Path property
• the value of the Command property

The expression formats are:

${param.<name>}:

• name found: parameter value is used.
• name missing: expression is not replaced.

${param.<name>:<default value>}:

• name found: parameter value is used.
• name missing: default value will be used.

In <default value> the character } must be escaped as \}.

Template Files

Expressions matching files in which to replace parameters.

If a single .zip file is unpacked, it is scanned for matching files as well.

Possible values are exact file names or file endings.

Example:

• my_script.sh
• *.txt
• *.properties

Owner

Owner of the directory at specified path. All files and subdirectories will have the same owner.

Group

Owner of the directory at path. All files and subdirectories will have the same owner.

Permissions: Owner

Read-write permissions for specified owner of the directory. All files and subdirectories (including unpacked from single .zip) will have the same permissions. The executable bit will be set automatically for readable directories and for readable Executable Files.

Permissions: Group

Read-write permissions for specified group of the directory. All files and subdirectories (including unpacked from single .zip) will have the same permissions. The executable bit will be set automatically for readable directories and for readable Executable Files.

Permissions: Other

Read-write permissions for all users of the directory. All files and subdirectories (including unpacked from single .zip) will have the same permissions. The executable bit will be set automatically for readable directories and for readable Executable Files.

Executable Files

Expression to select files which shall have the executable flag. Add exact file names or *.<ending>.

Example:

• myScript.sh
• *.py

Command

Bash shell expression which will be executed from the working directory Path as the deployment user (__connection_user variable in the inventory).

Example:

• ./my_script.sh

The command will run depending on the Command: Execution setting: always or conditional (e.g. onFileChange). Note that with the onFileChange setting, the command is not automatically executed if you change it here.

Tip: Instead of specifying your shell instruction(s) here, add them as a separate script file into Files. For example, if the file name is my_script.sh, enter ./my_script.sh as the Command. This way, the script will be re-executed each time you upload an updated script file and deploy the project (if onFileChange command execution is configured below).

Command: Execution Phase

Defines when the command is executed. The files are always copied during the CONFIGURE phase.

Phases:

• CONFIGURE: Command runs after files have been uploaded, but before NEVIS instances are (re)started. Use e.g. when patching a NEVIS instance configuration file.
• ACTIVATE: Command runs when instances are (re)started. Use when deploying files or commands that are independent of NEVIS instances.

Command: Execution

Defines when or how often the command is executed.

Possible values are:

• always: Execution during each deployment.
• onFileChange: Executed if an uploaded file under the specified Path has changed.
• onFileTriggers: Executed if a file that is listed under Command: Execution File Triggers has changed.
• onFileChange + onFileTriggers: Combining both options above.

Command: Execution File Triggers

Files deployed by other nevisAdmin 4 patterns that, when changed, trigger the script to be executed, even if the script and files itself do not change.

Example:

• /var/opt/nevisproxy/my_proxy/conf/navajo.xml

Hint: This is useful for patching e.g. navajo.xml after generation. Note that during the next deployment, it will be reverted (if the nevisProxy Instance pattern is deployed as well) and then patching will happen again.

Java Observability Settings

Sets up observability for Java-based Nevis components.

You can choose between OpenTelemetry and Application Insights.

This pattern adds a Java agent to integrate with either system.

Agent Type

Choose agent type:

• OpenTelemetry to integrate with self-hosted observability stack or with an OpenTelemetry compatible cloud provider.
• Application Insights to integrate with Azure Application Insights.

Agent Library Path

Path to the selected agent's library that is available locally to the deployed application.

Agent Configuration

Configuration file of the selected agent.

Use ${...} expressions to refer parameter values. Default parameters:

• ${name}: component name
• ${instance}: instance name
• ${version}: version
• ${service.name}: service name (kubernetes deployment)

Sample configuration for OpenTelemetry:

otel.service.name = ${service.name}
otel.resource.attributes = service.version=${version}
otel.exporter.otlp.protocol = http/protobuf
otel.exporter.otlp.traces.protocol = http/protobuf
otel.exporter.otlp.traces.endpoint = ${tracesEndpoint}
otel.exporter.otlp.metrics.protocol = http/protobuf
otel.exporter.otlp.metrics.endpoint = ${metricsEndpoint}
otel.exporter.otlp.metrics.temporality.preference = cumulative
otel.exporter.otlp.logs.protocol = http/protobuf
otel.exporter.otlp.logs.endpoint = ${logsEndpoint}

Sample configuration for Application Insights:

{
  "connectionString": "${connectionString}",
  "role": {
    "name": "${service.name}"
  },
  "customDimensions": {
    "service.version": "${version}"
  },
  "sampling": {
    "percentage": 100
  },
  "instrumentation": {
    "logging": {
      "level": "OFF"
    }
  }
}

Configuration Parameters

Provide parameters for your configuration file.

Examples:

connectionString = InstrumentationKey=00000000-0000-0000-0000-000000000000

tracesEndpoint = https://otel-collector:4318/v1/traces
metricsEndpoint = https://otel-collector:4318/v1/metrics
logsEndpoint = https://otel-collector:4318/v1/logs