Skip to content

Helper Binaries

The operator image ships three helper binaries that are mounted into Server pods and called by Puppet at runtime. They are not intended to be run manually. The operator generates their configuration as Kubernetes Secrets from the corresponding CRDs.

openvox-autosign

Puppet autosign script that evaluates SigningPolicy rules against incoming CSRs.

Invocation (by Puppet, configured via autosign setting in puppet.conf):

openvox-autosign [--config <path>] <certname>
Flag Default Description
--config /etc/puppetlabs/puppet/autosign-policy.yaml Path to the policy config (generated by operator from SigningPolicy CRDs)

The CSR is read from stdin as PEM-encoded data.

Exit codes:

Code Meaning
0 Sign the certificate
1 Deny the certificate

Policy evaluation:

  • Multiple policies are evaluated with OR logic (any match signs)
  • Within a policy, all conditions use AND logic (all must match)
  • any: true signs unconditionally
  • pattern matches certnames using glob patterns (*, ?)
  • csrAttributes matches Puppet CSR extension OIDs (e.g. pp_role, pp_environment, pp_preshared_key)
  • dnsAltNames validates DNS SANs in the CSR - if a CSR contains SANs, they must be explicitly allowed

Supported CSR attributes:

pp_uuid, pp_instance_id, pp_image_name, pp_preshared_key, pp_cost_center, pp_product, pp_project, pp_application, pp_service, pp_employee, pp_created_by, pp_environment, pp_role, pp_software_version, pp_department, pp_cluster, pp_provisioner, pp_region, pp_datacenter, pp_zone, pp_network, pp_securitypolicy, pp_cloudplatform, pp_apptier, pp_hostname, pp_owner, pp_authorization, pp_auth_token, pp_cli_auth, challengePassword

openvox-enc

Puppet External Node Classifier (ENC) script that queries an external classification service. Configured via the NodeClassifier CRD.

Invocation (by Puppet, configured via node_terminus and external_nodes settings):

openvox-enc [--config <path>] <certname>
Flag Default Description
--config /etc/puppetlabs/puppet/enc.yaml Path to the ENC config (generated by operator from NodeClassifier CRD)

Exit codes:

Code Meaning
0 Classification YAML written to stdout
1 Node not found (HTTP 404)
2 Error (config, network, or parse failure)

Features:

  • Supports GET and POST methods
  • POST body types: certname (sends {"certname": "..."}) or facts (sends certname + cached Puppet facts)
  • Response formats: yaml (default) and json - both are normalized to Puppet ENC YAML on stdout
  • Authentication: mtls, bearer, basic, token
  • TLS: custom CA certificate for server verification, mTLS with client certificate
  • Cache: when enabled, caches successful classifications to disk and falls back to cache on network errors

openvox-report

Puppet report processor that forwards reports to external endpoints via HTTP webhooks. Configured via the ReportProcessor CRD.

Invocation (by Puppet via webhook.rb report processor):

openvox-report [--config <path>] < report.json
Flag Default Description
--config /etc/puppetlabs/puppet/report-webhook.yaml Path to the report config (generated by operator from ReportProcessor CRDs)

The report JSON is read from stdin.

Exit codes:

Code Meaning
0 Report forwarded to all endpoints successfully
2 Error (config, network, or endpoint failure)

Features:

  • Forwards reports to multiple endpoints in sequence
  • Processor types:
    • puppetdb: transforms Puppet's to_data_hash report format into PuppetDB Wire Format v8 (store report command) and sends to /pdb/cmd/v1
    • Generic (default): forwards the report JSON as-is to the configured URL
  • Authentication: mtls, bearer, basic, token
  • TLS: custom CA certificate for server verification, mTLS with client certificate
  • Custom HTTP headers per endpoint
  • Default timeout: 30 seconds per endpoint