Puppet ProSA

Table of Contents

1. Description
2. Setup
   • What the ProSA module affects
   • Setup requirements
   • Beginning with prosa
3. Usage
4. Limitations
5. Development - Guide for contributing to the module

Description

ProSA (Protocol Service Adaptor) is a framework designed to provide a simple and lightweight protocol service adaptor for service-oriented architectures. This Puppet module managed with PDK streamlines the process of creating configurations to manage ProSA in your infrastructure. It is capable of configuring and managing a range of processors. For more information on deploying ProSA, please refer to cargo-prosa.

Setup

What the ProSA module affects

• Service and configuration files for ProSA
• ProSA processor configuration files

Setup Requirements

This module does not install dependencies required for your specific ProSA instance, such as OpenSSL. You will need to install these dependencies separately according to your ProSA setup.

Beginning with prosa

To have Puppet install ProSA with the default parameters, declare the [prosa][https://forge.puppet.com/modules/worldline/prosa/reference#prosa] class:

class { 'prosa': }

When you declare this class with the default options, the module:

• Installs the ProSA instace binary from the configured bin_repo.
• Generate configuration files in the conf_dir.
• Creates and starts a ProSA service.

Usage

ProSA base

To set up ProSA, you need to use the [prosa][https://forge.puppet.com/modules/worldline/prosa/reference#prosa] class.

From this class, you should specify the binary repository to retrieve the ProSA binary. Additionally, observability is configured by default, but you may need to specify parameters based on your particular stack.

class { 'prosa':
  bin_repo        => 'https://user:password@binary.repo.com/repository/prosa-1.0.0.bin',
  telemetry_level => 'info',
  observability   => {
    'metrics' => {
      'otlp' => {
        'endpoint' => 'http://opentelemetry-collector:4317',
        'protocol' => 'Grpc'
      },
    },
    'traces' => {
      'otlp' => {
        'endpoint' => 'http://opentelemetry-collector:4317',
        'protocol' => 'Grpc'
      },
      'stdout' => {
        'level' => 'info',
      },
    },
    'logs' => {
      'otlp' => {
        'endpoint' => 'http://opentelemetry-collector:4317',
        'protocol' => 'Grpc'
      },
      'stdout' => {
        'level' => 'info',
      },
    },
  }
}

With this configuration, ProSA will be installed and ready to accept processors. Configuring processors is the next step.

Configuring Processors

Processors are configured using the prosa::proc defined type. You can set them up individually or use prosa::processors for all:

class { 'prosa::processors':
  processors => {
    'stub' => {
      'proc_settings' => {
        'service_names' => ['test'],
      },
    },
    'inj' => {
      'proc_settings' => {
        'service_name' => 'test',
      },
    },
  }
}

Since processors have different configurations, proc_settings is provided as a Hash to accommodate all necessary configuration options. To determine which configurations to specify, refer to the documentation for the corresponding processor.

Reference

For information on classes, types and functions see the REFERENCE.md

Limitations

Limitations are associated with the ProSA binary generated with cargo-prosa. You need to pay attention to the compiled architecture of your binary. Additionally, if you are using external binaries (e.g., OpenSSL), you'll need to install them independently.

Development

For development guidelines, please follow contributing rules.

If you submit a change to this module, be sure to regenerate the reference documentation as follows:

puppet strings generate --format markdown --out REFERENCE.md

Acceptance tests are runs with litmus

Authors

Worldline

• Jérémy HERGAULT

Reference

Table of Contents

Classes

Public Classes

• prosa: Guides the basic setup and installation of ProSA on your system.
• prosa::processors: Creates prosa::proc defined types.

Private Classes

• prosa::params: This class manages ProSA parameters
• prosa::service: Installs and configures ProSA service.

Defined types

• prosa::proc: Allows specialised configurations for ProSA processors

Data types

• ProSA::TelemetryLevel: A string that conforms to the ProSA TelemetryLevel syntax.

Classes

prosa

A description of what this class does

Examples

class { 'prosa': }

Parameters

The following parameters are available in the prosa class:

• prosa_name
• service_name
• bin_repo
• bin_path
• log_dir
• conf_dir
• service_enable
• service_manage
• service_ensure
• manage_user
• manage_group
• user
• group
• telemetry_level
• observability

prosa_name

Data type: String

The name of your ProSA. It take this name to advertise himself. This name is sometime very important for some processors.

Default value: $prosa::params::prosa_name

service_name

Data type: String

Sets the name of the ProSA service.

Default value: $prosa::params::service_name

bin_repo

Data type: Optional[String]

Link to the binary repository where the ProSA binary can be find. See Puppet File source attribute to set this parameter

Default value: $prosa::params::bin_repo

bin_path

Data type: Stdlib::Absolutepath

Sets the path where the ProSA binary will be located.

Default value: '/usr/local/bin/prosa'

log_dir

Data type: Stdlib::Absolutepath

Sets the directory where the ProSA logs files are located.

Default value: '/var/log'

conf_dir

Data type: Stdlib::Absolutepath

Sets the directory where the ProSA configuration files are located.

Default value: $prosa::params::conf_dir

service_enable

Data type: Boolean

Determines whether Puppet enables the ProSA service when the system is booted.

Default value: true

service_manage

Data type: Boolean

Determines whether Puppet manages the ProSA service's state.

Default value: true

service_ensure

Data type: Variant[Stdlib::Ensure::Service, Boolean]

Determines whether Puppet should make sure the service is running. Valid values are: true (or running) or false (or stopped). The false or stopped values set the ProSA service resource's ensure parameter to false, which is useful when you want to let the service be managed by another application.

Default value: 'running'

manage_user

Data type: Boolean

When false, stops Puppet from creating the user resource. This is for instances when you have a user, created from another Puppet module, you want to use to run ProSA. Without this parameter, attempting to use a previously established user would result in a duplicate resource error.

Default value: true

manage_group

Data type: Boolean

When false, stops Puppet from creating the group resource. If you have a group created from another Puppet module that you want to use to run ProSA, set this to false. Without this parameter, attempting to use a previously established group results in a duplicate resource error.

Default value: true

user

Data type: String

Change the user that ProSA uses to run. To prevent Puppet from managing the user, set the manage_user parameter to false.

Default value: $prosa::params::user

group

Data type: String

Changes the group ID that ProSA uses to run. To prevent Puppet from managing the user, set the manage_user parameter to false.

Default value: $prosa::params::group

telemetry_level

Data type: ProSA::TelemetryLevel

Configures the ProSA TelemetryLevel directive which adjusts the verbosity of telemetry messages recorded.

Default value: $prosa::params::telemetry_level

observability

Data type: Hash[String, Hash[String, Hash[String, String]]]

Configures the ProSA Observability directive which configure metrics, traces and logs export.

Default value: $prosa::params::observability

prosa::processors

Creates prosa::proc defined types.

Examples

To create a ProSA processor stub-1

class { 'prosa::processors':
  processors => {
    'stub-1' => {
      'adaptor_config_path'          => undef,
      'proc_restart_duration_period' => undef,
      'proc_max_restart_period'      => undef,
      'proc_settings'                     => {
        'service_names' => ['test'],
      },
    },
  },
}

Parameters

The following parameters are available in the prosa::processors class:

• processors

processors

Data type: Hash

A hash, where the key represents the processor name and the value represents a hash of prosa::proc defined type's parameters.

Default value: {}

Defined types

prosa::proc

Allows specialised configurations for ProSA processors

Examples

class { 'prosa':
  default_vhost     => false,
  default_ssl_vhost => false,
}

Parameters

The following parameters are available in the prosa::proc defined type:

• adaptor_config_path
• adaptor_settings
• proc_restart_duration_period
• proc_max_restart_period
• proc_settings
• config_file_mode

adaptor_config_path

Data type: Optional[Stdlib::Absolutepath]

For some ProSA adaptor, they need to have a configuration in addition to processor. If needed you need to specify the path of it.

Default value: undef

adaptor_settings

Data type: Optional[Hash]

All settings of the adaptor if needed. The keys/values are depending of the adaptor. The adaptor_config_path should be defined if it's sets.

Default value: undef

proc_restart_duration_period

Data type: Optional[Integer[0, 86400000]]

Period in milliseconds of processors restarts when an error is detected

Default value: undef

proc_max_restart_period

Data type: Optional[Integer[10, 604800]]

Period in seconds of the maximum wait duration for a processor restart

Default value: undef

proc_settings

Data type: Hash

All settings of the processor. The keys/values are depending of the processor.

Default value: {}

config_file_mode

Data type: Optional[String]

Permissions mode for the processor configuration file The file should be read at least by the ProSA process. But can be reduced to avoid any configuration leak. If not set, the permission will be '0644'.

Default value: undef

Data types

ProSA::TelemetryLevel

A string that conforms to the ProSA TelemetryLevel syntax. Different levels can be specified for individual metrics, traces, and logs.

The levels are (in order of decreasing significance):

• error
• warn
• info
• debug
• trace
• off

ProSA accept non case sensitive levels (like this type).

• See also
  • https://docs.rs/prosa-utils/latest/prosa_utils/config/tracing/enum.TelemetryLevel.html

Alias of Pattern[/\A(?i:error|warn|info|debug|trace|off)\Z/]