Skip to main content

Configuration

The Sensor and Cluster Manager are shipped with default configurations that should be suitable for most installations, but can be customized by setting values in the Upwind Operator chart.

Using Kubernetes Secret for Upwind Operator clientId and clientSecret​

The Upwind Operator requires a clientId and clientSecret to authenticate with the Upwind API. These credentials can be provided as a Kubernetes Secret, which is then referenced in the Upwind Operator configuration.

The Secret convention is as follows:

clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET

For example, you can create it with the following command:

kubectl create secret generic --namespace upwind upwind-secret \
        --from-literal=clientId=$CLIENT_ID \
        --from-literal=clientSecret=$CLIENT_SECRET

To reference the Secret in the Upwind Operator configuration, you must use the following configuration:

credentials:
  create: false
  name: upwind-secret

Tuning the Sensor and Cluster Manager​

The Sensor pods will use memory roughly in proportion to the level of network and process activity on the node the Sensor is running on, and is not dependent on the overall size of the Kubernetes cluster. Most of the memory the Sensor uses is dedicated to internal caches of data related to active network connections. Depending on your specific environment, it may be beneficial to adjust the size or expiration time of these caches by configuring the Sensor daemonset by modifying agent.values.agent.config.connCache or agent.values.agent.config.connTrackCache. Increasing the cache sizes will allow the sensor to monitor more concurrent network connections. Reducing the size of the caches or the expiration time can reduce memory usage.

The Cluster Manager will use memory roughly in proportion to the size of the cluster it is running in and the amount of network traffic in the cluster. For clusters larger than 50 nodes or with more than 1 GB/s of network traffic, it's recommended to increase the memory requests and limits for the Cluster Manager.

Custom Private IP Ranges​

The Sensor classifies each connection as private network traffic or internet traffic using a list of private IP ranges. You can add your own ranges with the --private-cidrs flag.

Learn more about private IP ranges including the default ranges and how to set the flag.

Proxy Configuration​

All cluster components the operator, cluster manager, sensor and scanner will all respect the HTTP_PROXY family of environment variables for egress communication The helm charts have a proxy object that can be configured

proxy:
  enabled: true|false
  httpProxy: ""
  httpsProxy: ""
  noProxy: ""
httpProxy​

Used as the proxy URL for HTTP requests unless overridden by noProxy.

httpsProxy​

Used as the proxy URL for HTTPS requests unless overridden by noProxy When not specified will use the value from httpProxy

noProxy​

Specifies a string that contains comma-separated values specifying hosts that should be excluded from proxying. Each value is represent by:

  • an IP address (1.2.3.4)
  • an IP address prefix in CIDR notation (1.2.3.0/24)
  • a domain name An IP address prefix and domain name can also include a literal port number (1.2.3.4:80). A domain name matches that name and all subdomains.

Enabling response​

To enable the response feature, verify that the --responses-enabled flag is set to true.

For example:

{
    "agent": {
        "values": {
            "agent": {
                "extraArgs": [
                    ...
                    "--responses-enabled=true",
                    ...
                ]
            },
           ...
    },
    "clusterAgent": {
        "values": {
            "extraArgs": [
                "--responses-enabled=true"
            ],
            ...
        }
    }
}

EKS Auto Mode​

In EKS Auto Mode, the hop limit for IMDS is set to 1 and can not be updated. This prevents most pods from accessing IMDS unless they are using host networking. In this case, you must provide the AWS account ID via a flag to the Upwind Operator and Upwind Cluster Manager components since they can not load the account ID from IMDS. Example values for the upwind-operator chart:

credentials:
  clientId: XXX
  clientSecret: XXX
extraArgs:
  - --cloud-account-id=XXXX
clusterAgent:
  values:
    extraArgs:
      - --cloud-account-id=XXXX

Google Autopilot Clusters​

In Google Autopilot Clusters, additional configuration of the sensor is required to allow the pods to launch.

credentials:
  clientId: XXX
  clientSecret: XXX
agent:
  values:
    extraArgs:
      - --cluster-name=<CLUSTER NAME>
    providers:
      gke:
        autopilot:
          enabled: true
clusterAgent:
  values:
    extraArgs:
      - --cluster-name=<CLUSTER NAME>
extraArgs:
  - --cluster-name=<CLUSTER NAME>

Nodes in Autopilot clusters do not have a label indicating the cluster name, so on order for the name of the cluster to be correctly displayed in the Upwind Console it needs to be passed to the components as a flag.

API Catalog Configuration​

There are a number of flags to control the data included in the API Catalog.

Environment VariableFlagDescriptionDefault
UPWIND_API_SEC_CATALOG--api-sec-catalog=trueWhether to enable the API Catalog.true
UPWIND_API_SEC_REQUESTS_SAMPLE_CNT--api-sec-requests-sample-cnt=1000Maximum number of request samples to include in an API Catalog report. Set to 0 to disable request sampling entirely.1000
UPWIND_API_SEC_REQUESTS_SAMPLE_SIZE_MAX--api-sec-requests-sample-size-max=1024Maximum size of request body. Set to 0 to disable including request bodies.1024
UPWIND_API_SEC_RESPONSE_SAMPLE_SIZE_MAX--api-sec-response-sample-size-max=1024Maximum size of response body. Set to 0 to disable including response bodies.1024
UPWIND_API_SEC_EXCLUDE_SENSITIVE_BODY--api-sec-exclude-sensitive-body=falseWhether to mask the entire request or response body on a sensitive data matchfalse

These flags or environment values can be added to the agent.values.extraArgs or agent.values.env lists in the upwind-operator chart.

gVisor Support​

The Upwind Sensor includes support for monitoring applications running in gVisor sandboxes, providing enhanced security isolation for sensitive workloads. gVisor implements a userspace kernel that acts as a security boundary between containerized applications and the host system.

Learn more about gVisor support including configuration, architecture, and deployment options.

Istio Ambient Mesh Support​

In order for the Upwind Sensor to accurately report network activity when Istio Ambient mesh is enabled, traffic must be monitored at layer 7 instead of layer 4. Set the --network-flow-sock and --network-flow-sock-all-flows flags on the sensor. Example values for the upwind-operator chart with these flags set:

credentials:
  clientId: XXX
  clientSecret: XXX
agent:
  values:
    extraArgs:
      - --network-flow-sock
      - --network-flow-sock-all-flows

S3 Report Upload​

The Cluster Manager can write a copy of the reports it sends to Upwind into an S3 bucket you own, or into S3-compatible object storage.

Learn more about S3 report upload including credentials, bucket configuration, and the report types available.

Configuration Library​

Below are the supported helm values for Upwind components. Note that you may need to upgrade to latest helm chart release version to use some of the values listed below.

# -- `[Optional]` Overrides application name.
nameOverride: ""

# -- `[Optional]` Overrides the full qualified application name.
fullnameOverride: ""

# Image.
# @see: <https://kubernetes.io/docs/concepts/containers/images/>
image:
  # -- `[Optional]` Specifies the image registry/repository.
  repository: public.ecr.aws/upwindsecurity/images/operator
  # -- `[Optional]` Specifies the image pull policy.
  pullPolicy: IfNotPresent
  # -- `[Optional]` Specifies the image tag. Defaults to `.Chart.AppVersion`.
  tag: ""
# -- `[Optional]` Specifies the image pull secrets.
# The Upwind Operator image is publicly available, but when self hosting images or using a proxy repository that
# requires authentication the imagePullSecrets can be set.
imagePullSecrets: []

# Service account.
# @see: <https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/>
serviceAccount:
  # -- `[Optional]` Specifies whether a Service Account should be created.
  create: true
  # -- `[Optional]` Specifies the annotations for the Service Account.
  annotations: {}
  # -- `[Optional]` Specifies the name of the Service Account. Defaults to fully qualified application name.
  name:

# -- `[Optional]` Specifies the Deployment annotations.
# @see: <https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/>
annotations: {}

# -- `[Optional]` Specifies the Pod annotations.
# @see: <https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/>
podAnnotations: {}

# `[Required]` Compute resources granted to the controller
resources:
  limits:
    cpu: 500m
    memory: 500Mi
  requests:
    cpu: 10m
    memory: 256Mi

# `[Required]` Deployment livenessProbe
livenessProbe:
  failureThreshold: 3
  httpGet:
    path: /healthz
    port: 8081
    scheme: HTTP
  initialDelaySeconds: 15
  periodSeconds: 20
  successThreshold: 1
  timeoutSeconds: 1

# `[Required]` Deployment readinessProbe
readinessProbe:
  failureThreshold: 3
  httpGet:
    path: /readyz
    port: 8081
    scheme: HTTP
  initialDelaySeconds: 5
  periodSeconds: 10
  successThreshold: 1
  timeoutSeconds: 1

# -- `[Optional]` Specifies the region of the Upwind Endpoints. Defaults to `us`
region:  # @schema type:[string, null]

# [Static Secret] Upwind Application Credentials (OAuth 2.0 Client Credentials).
credentials:
  # -- `[Optional]` Specifies whether a Secret should be created.
  create: true
  # -- `[Optional]` Specifies the name of the Secret. Defaults to fully qualified application name.
  # When create is set to false this will be used as a reference to an existing Secret to use.
  name:  # @schema type:[string, null]
  # -- `[Required]` Specifies the application's Client ID.
  clientId:  # @schema type:[string, null]
  # -- `[Required]` Specifies the application's Client Secret.
  clientSecret:  # @schema type:[string, null
  # -- `[Optional]` Specifies annotations for the Credentials Secret
  annotations: {}
  # -- `[Required]` Specifies the name of the Secret to be created.
  registrySecretName:  # @schema type:[string, null]
  # -- `[Required]` Specifies the name of the Secret to be created.
  agentSecretName:  # @schema type:[string, null]

# [Agent Component] Configuration settings specifically for the Agent Custom Resource
agent:
  # -- `[Optional]` Specifies whether or not this chart will create the Agent
  # component resource. Disable to manage this resource on your own.
  create: true
  # -- `[Required]` The name of the Upwind `Agent` resource to create. Defaults
  # to `upwind`. Final pod names will be `upwind-agent-...`.
  name: upwind
  # -- `[Optional]` Configures the reconciliation frequency of the Agent
  # resource. Default is 1h.
  interval:  # @schema type:[string, null]
  # -- `[Optional]` If specified, pins the version of the Agent component to a
  # specific release. If unset, the Upwind Operator will automatically upgrade
  # releases as they become available.
  version:  # @schema type:[string, null]
  # -- `[Optional]` if specified, these custom values will be added to the
  # Agent spec, and passed through to the Agent helm chart.
  values: {}

# [Cluster Agent Component] Configuration settings specifically for the
# ClusterAgent Custom Resource
clusterAgent:
  # -- `[Optional]` Specifies whether or not this chart will create the
  # ClusterAgent component resource. Disable to manage this resource on your
  # own.
  create: true
  # -- `[Required]` The name of the Upwind `ClusterAgent` resource to create.
  # Defaults to `upwind`. Final pod names will be `upwind-cluster-agent-...`.
  name: upwind
  # -- `[Optional]` Configures the reconciliation frequency of the ClusterAgent
  # resource. Default is 1h.
  interval:  # @schema type:[string, null]
  # -- `[Optional]` If specified, pins the version of the ClusterAgent
  # component to a specific release. If unset, the Upwind Operator will
  # automatically upgrade releases as they become available.
  version:  # @schema type:[string, null]
  # -- `[Optional]` if specified, these custom values will be added to the
  # ClusterAgent spec, and passed through to the Cluster Agent helm chart.
  values: {}

# Configuration settings specifically for the Operator itself
operator:
  # -- `[Optional]` Set the log level for the controller.
  logLevel: info
  extraVolumes: []
  extraVolumeMounts: []
  # -- `[Optional]` If specified, this controls the Oauth Endpoint that the
  # Operator will use to generate secret credentials for the components and for
  # image pulling.
  oauthEndpoint:  # @schema type:[string, null]
  # -- `[Optional]` If specified, this controls the audience value used by the
  # Operator when generating credential tokens for the Agent and the Cluster
  # Agent.
  agentEndpoint:  # @schema type:[string, null]
  # --`[Optional]` If specified, this controls the audience value used by the
  # Operator when generating credential Image Pull Secrets used to pull the
  # Component images from the private registry.
  registryEndpoint:  # @schema type:[string, null]
  # -- `[Optional]` If set to true, the Operator will use Helm to manage the
  # Agent and Cluster Agent components. Defaults to true.
  useHelm: true
  # -- `[Optional]` SecurityContext for the operator container
  securityContext:
    privileged: false
    allowPrivilegeEscalation: false
    readOnlyRootFilesystem: true
    runAsNonRoot: true
    runAsUser: 65532
    runAsGroup: 65532
    capabilities:
      drop:
        - ALL

# -- `[Optional]` Deployment progressDeadlineSeconds.
progressDeadlineSeconds:  # @schema type:[string, null]

# -- `[Optional]` The number of Upwind Secret Controllers to run.
replicas:  # @schema type:[integer, null]

# -- `[Optional]` Deployment revisionHistoryLimit.
revisionHistoryLimit:  # @schema type:[integer, null]

# -- `[Optional]` Deployment strategy.
strategy:  # @schema type:[string, null]

# -- `[Optional]` Specifies the priorityClass to use. Defaults to unset.
priorityClassName:

# -- `[Optional]` Specifies the RuntimeClass for the operator pod (e.g. `edera`).
# Defaults to unset (the cluster default runtime).
runtimeClassName:  # @schema type:[string, null]

# -- `[Optional]` Specifies the node selector.
# @see: <https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/>
nodeSelector: {}

# -- `[Optional]` Specifies the tolerations for nodes that have taints on them.
# @see: <https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/>
tolerations: []

# -- `[Optional]` Specifies the DNS policy for the pod. Defaults to "ClusterFirst".
# Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'.
# @see: <https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy>
dnsPolicy: ""  # @schema type:[string, null]

# -- `[Optional]` Specifies custom DNS configuration for the pod.
# Useful for overriding ndots, search domains, etc.
# @see: <https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config>
dnsConfig: {}

# -- ``[Optional]` Pod SecurityContext
securityContext:
  seccompProfile:
    type: RuntimeDefault

# `[Optional]` Allowed profiles that can be set for pod.
# Applies to Red Hat Openshift installation only and should be set according to `.securityContext.seccompProfile.type` value.
#
# @see: https://docs.redhat.com/en/documentation/openshift_container_platform/3.11/html-single/architecture/index#authorization-seccomp
openshift:
  scc:
    seccompProfiles:
      - runtime/default

# -- `[Required]` Pod affinity settings. The default allows linux or windows
# nodes on amd64/arm64. On EKS Windows you additionally need
# `nodeSelector.kubernetes.io/os: windows` — the EKS VPC Resource Controller's
# mutating webhook only annotates Windows pods with
# `vpc.amazonaws.com/PrivateIPv4Address` when it reads `spec.nodeSelector`,
# not `spec.affinity`.
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: kubernetes.io/arch
          operator: In
          values:
          - amd64
          - arm64
        - key: kubernetes.io/os
          operator: In
          values:
          - linux
          - windows

# -- `[Required]` Additional command line arguments for the manager.
extraArgs:
  # Ensure that we are reconciling the custom Component resources
  - --enable-custom-resources=true

# -- `[Optional]` Additional environment variables for the manager.
extraEnv: []

# -- `[Optional]` Any additional labels that should be added to resources
# created by this chart.
extraLabels:
  # This label is defined externally to the helper functions to enable
  # overriding it with a different value in the EKS add-on chart.
  # The common value Release[dot]Service (using [dot] notation to avoid
  # validation issues) is not supported in EKS add-ons managed through
  # the AWS Marketplace. However, in Helm, the value is always Helm,
  # so it may be acceptable to simply use a hard-coded default value instead.
  app.kubernetes.io/managed-by: Helm

identities:
  # -- Names of ConfigMaps the cluster-agent will be allowed to read.
  configMaps:
    - aws-auth

# -- `[Optional]` Parameters configurable by parent charts.
global:
  # [Static Secret] Upwind Application Credentials (OAuth 2.0 Client Credentials).
  credentials:
    # -- `[Optional]` Specifies whether a Secret should be created.
    create: true
    # -- `[Required]` Specifies the application's Client ID.
    clientId:  # @schema type:[string, null]
    # -- `[Required]` Specifies the application's Client Secret.
    clientSecret:  # @schema type:[string, null]

# -- This adds proxy configuration for outbound http/https traffic from the components
proxy:
  enabled: false
  httpProxy: ""
  httpsProxy: ""
  noProxy: ""

# -- `[Optional]` Kubernetes provider configuration, propagated to both the
# agent and cluster-agent charts (like `region` and `proxy`). Declare it here
# instead of repeating it inside `agent.values` and `clusterAgent.values`; a
# `providers` key set directly in a component's values takes precedence for
# that component. When empty nothing is propagated, so existing CRs are left
# untouched. Example: `--set providers.gke.autopilot.enabled=true`.
providers: {}

# -- the names of additional agent custom resources managed by the operator.
extraAgentResources: []

clusterRole:
  # -- Enables permissions to read all resources.
  enableCustomResources: true
  • Scan Jobs - run the Scanner as Cluster Manager jobs instead of a Sensor sidecar, and control their placement, tolerations, resources and retries.
  • Prometheus Metrics - expose Sensor and Cluster Manager metrics with a PodMonitor and ServiceMonitor.
  • TLS/mTLS - encrypt traffic between the Sensor and the Cluster Manager, optionally with cert-manager and trust-manager.
  • ClusterRole Permissions - the read-only Kubernetes permissions the Cluster Manager and Sensor use.
  • Private IP Ranges - add your own ranges to the ones the Sensor treats as private network traffic.