Proxy Harness reference

Coming in enterprise-2.16

BEL provides a mesh expansion proxy harness component that works along the BEL autoregistration controller to automate configuration and lifecycle management for external workloads. The harness is a component that is installed on a host machine. Upon installation, a configuration file is automatically created on the file system. This configuration file contains sensible defaults. Furthermore, it allows for configuring certain aspects of the harness behavior.

Upon installing the harness package, the configuration file is placed in /var/lib/linkerd/linkerd-proxy-harness.cfg and contains the following config:

{
  "ProxyUserID": 997,
  "InboundPortsToIgnore": [
    "4567",
    "4568"
  ],
  "OutboundPortsToIgnore": [
    "4567",
    "4568"
  ],
  "IPTablesMode": "legacy",
  "InboundListenAddress": "0.0.0.0:4143",
  "OutboundListenAddress": "127.0.0.1:4140",
  "AdminAddress": "127.0.0.1:4192",
  "Identity": {
    "SpireSocketAddress": "/tmp/spire-agent/public/api.sock",
    "Backoff": {
      "Min": "100ms",
      "Max": "1s",
      "Jitter": 0.1
    }
  },
  "Dns": {
    "MinTTL": "10s",
    "MaxTTL": "10m",
    "ResolvConfPath": "/etc/resolv.conf"
  },
  "LogLevel": "info",
  "LogFormat": "plain"
}
FieldDescription
ProxyUserIDUser id under which the proxy runs (automatically derived based on the ID of the proxyharness user, which is created as part of the package installation).
PortsToRedirectPorts to redirect to proxy, if no port is specified then ALL ports are redirected.
SubnetsToIgnoreSubnets to ignore and not redirect to proxy. This has higher precedence than any other parameters.
InboundPortsToIgnoreInbound ports and/or port ranges (inclusive) to ignore and not redirect to proxy. This has higher precedence than any other parameters.
OutboundPortsToIgnoreOutbound ports and/or port ranges (inclusive) to ignore and not redirect to proxy. This has higher precedence than any other parameters.
IPTablesModeVariant of iptables command to use (legacy or nft).
InboundListenAddressAddress on which the proxy listens for incoming traffic.
OutboundListenAddressAddress on which the proxy listens for outbound traffic.
AdminAddressAddress on which the admin server of the harness is served.
FieldDescription
SpireSocketAddressAddress of the SPIRE agent Workload API (default: /tmp/spire-agent/public/api.sock).
BackoffBackoff configuration for the SPIRE GRPC client.
FieldDescription
AddressAddress of the autoregistration controller.
ServerIdTLS Identity of the autoregistration controller.
ServerNameSNI of the autoregistration controller.
FieldDescription
MinTTLMinumum TTL for DNS results (defaults to 10s).
MaxTTLMax TTL for DNS results (defaults to 10m).
ResolvConfPathPath to the resolv.conf file (defaults to /etc/resolv.conf)
FieldDescription
LogLevelThe level of logging (defaults to info).
LogFormatThe format of logging (defaults to plain).
FieldDescription
GroupNameThe name of the WorkloadGroup resource that will own this workload.
GroupNamespaceThe namespace of the WorkloadGroup resource that will own this workload.

This piece of configuration controls the way the harness determines its own address. This address will be used when traffic is sent from the cluster to the harness and therefore should be reachable from within the cluster. If no configuration is provided, the harness lookups up the default interface on the host and picks the first address for the interface. If more specific configuration is needed, only one of the following options need to be specified

FieldDescription
InterfaceNameThe name of the network interface that will be used for inbound traffic (the harness will pick the default address on the interface).
AddressA single IPv4 address that will be used to reach the workload.

By default the configuration that the proxy is run with is provided by the autoregistration controller (with the exception of Inbound and Outbound proxy addresses). If the is further need to modify the config per workload basis, the following parameter can be used to explicitly override any proxy environment variable.

FieldDescription
ProxyConfigOverridesAn object containing key,value pairs where the key is the env variable that is used for proxy configuration.

As part of the harness installation a minimal CLI is provided. Its purpose is to allow for ergonomic manipulation of certain aspects of the config. Currently it mainly serves to configure the way the external workload connects to the Linkerd control plane.

harnessctl set-config
FlagUsage
--workload-group-nameName of the WorkloadGroup resource.
--workload-group-namespaceNamespace of the WorkloadGroup resource.
--control-plane-addressAddress of the autoregistration controller.
--control-plane-identityTLS Identity of the autoregistration controller.
--control-plane-sniSNI of the autoregistration controller (defaults to --control-plane-identity).
--config-fileHarness config file location (defaults to /var/lib/linkerd/linkerd-proxy-harness.cfg).