kube-proxy

kube-proxy

Chainguard's redistribution of the kube-proxy Helm chart, pre-configured with hardened Chainguard Images.

Prerequisites

Authentication is required to access this chart and its images. First, authenticate with Chainguard and configure your environment:

chainctl auth login
chainctl auth configure-docker --pull-token --save
helm registry login cgr.dev

Create an image pull secret for the cluster:

kubectl create secret docker-registry cgr-pull-secret \
  --docker-server=cgr.dev \
  --docker-username="$(echo cgr.dev | docker-credential-cgr get | jq -r '.Username')" \
  --docker-password="$(echo cgr.dev | docker-credential-cgr get | jq -r '.Secret')" \
  --namespace kube-system

Installation

helm install kube-proxy oci://cgr.dev/ORGANIZATION/charts/kube-proxy \
  --namespace kube-system \
  --set imagePullSecrets[0].name=cgr-pull-secret \
  --set apiServer.endpoint=https://YOUR_API_SERVER_ENDPOINT

About This Chart

This is a redistribution of the upstream kube-proxy Helm chart. All upstream configuration options and documentation apply.

For full documentation, see: https://github.com/stevehipwell/helm-charts/tree/main/charts/kube-proxy

Chainguard Customizations

apiServer.endpoint defaults to https://kubernetes.default.svc (the standard in-cluster DNS name for the Kubernetes API server), making the field optional. In environments where cluster DNS is not reachable — for example when kube-proxy runs with hostNetwork: true — override the default with the API server's IP address:

helm install kube-proxy oci://cgr.dev/ORGANIZATION/charts/kube-proxy \
  --set apiServer.endpoint=https://YOUR_API_SERVER_IP:PORT

Compatibility settings

The chart also accepts three top-level settings in the shape that AWS's own kube-proxy Amazon EKS add-on takes. Each one replaces a setting under config:

They are opt-in: with none set, config renders exactly as the upstream chart renders it. When a setting and its config counterpart are both set, the top-level setting wins. Null counts as unset. Other keys under top-level ipvs and conntrack do nothing. kube-proxy 1.37 deprecates ipvs mode.

helm install kube-proxy oci://cgr.dev/ORGANIZATION/charts/kube-proxy \
  --set mode=iptables \
  --set conntrack.tcpBeLiberal=true

Amazon EKS Add-on Configuration Values

The chart ships aws_mp_configuration_schema.json at its root. When the chart runs as an Amazon EKS add-on from AWS Marketplace, EKS validates the values passed to aws eks create-addon and aws eks update-addon with --configuration-values against it, and aws eks describe-addon-configuration returns it. Helm ignores the file.

The schema accepts every setting of AWS's own kube-proxy add-on (version v1.37.0-eksbuild.19):

• mode, ipvs.scheduler, and conntrack.tcpBeLiberal, through the compatibility settings above
• podAnnotations and podLabels, with string values only: Kubernetes rejects other values, and this chart does not quote them
• resources.requests and resources.limits, each with cpu and memory

The configuration values you pass to that add-on also work here, unless they do one of these things, each explained in this section:

• set a label or annotation value that is not a string
• use an annotation key prefix that is not lowercase
• put a control character, U+2028, or U+2029 in a string, other than a tab or newline in an annotation value
• set a selector label key in podLabels
• set checksum/config in podAnnotations

The schema also checks Kubernetes syntax for label keys and values, annotation keys, and resources quantities. Quantities are strings, such as 100m or 128Mi, and may not be negative. A quantity may not be ., +, or +., which Kubernetes reads as 0, so there the schema is stricter than Kubernetes. The schema does not check Kubernetes rules that compare two fields, so a request above its limit passes the schema and fails at install. An annotation key prefix, such as example.com in example.com/owner, must be lowercase, as a label key prefix must be. Kubernetes accepts a mixed-case annotation key prefix, so there the schema is stricter than Kubernetes. No string may contain a control character, U+2028, or U+2029, except that annotation values may contain tabs and newlines. YAML parsers read U+0085 (a control character), U+2028, and U+2029 as line breaks, and Helm's toYaml writes them unescaped. Kubernetes accepts all of these characters in annotation values, so there the schema is stricter than Kubernetes.

podLabels rejects the keys app.kubernetes.io/name, app.kubernetes.io/instance, and k8s-app. The chart writes the DaemonSet's selector labels and then podLabels into the pod template's labels, so a repeated key gives one label two values, and the pods can stop matching the DaemonSet's selector. app.kubernetes.io/name and app.kubernetes.io/instance are the chart's selector labels, and k8s-app is the key that the adoption setting below sets. The schema cannot compare podLabels with selectorLabelsOverride, so if you set selectorLabelsOverride with other keys, do not repeat them in podLabels.

podAnnotations rejects the key checksum/config. The chart sets that annotation on the pods to a hash of the kube-proxy configuration, so that a configuration change rolls the pods. The chart writes it and then podAnnotations into the pod template's annotations, so a repeated key either fails the install or pins the hash. With a pinned hash, a later configuration change does not roll the pods, and they can keep running with the old configuration.

The schema rejects annotation keys that start with container.apparmor.security.beta.kubernetes.io/ because Kubernetes, from 1.30 through at least 1.37.1, still copies that annotation into the container's securityContext.appArmorProfile (applyAppArmorVersionSkew in kubernetes/kubernetes). Such a key would change a security context. The schema also rejects keys that start with seccomp.security.alpha.kubernetes.io/ or container.seccomp.security.alpha.kubernetes.io/ under the same rule, although the seccomp annotations have done nothing since Kubernetes 1.27. Kubernetes reads only these lowercase keys, and the schema rejects every mixed-case prefix.

AWS settings that the schema leaves out: none.

Where this add-on's defaults differ from AWS's own add-on, the chart keeps its own default:

• When mode is unset, this add-on runs in nftables mode, while AWS's own add-on runs in iptables mode. Pass {"mode": "iptables"} to keep AWS's mode.
• This add-on sets no resource requests unless you pass resources. AWS's archived kube-proxy manifest in aws/containers-roadmap requests cpu: 100m, which is unconfirmed for current AWS builds. Pass {"resources": {"requests": {"cpu": "100m"}}} to match it.

Adoption setting

The schema also accepts selectorLabelsOverride, so that this add-on can take over the kube-proxy DaemonSet that AWS's own add-on created. That DaemonSet selects its pods with the label k8s-app: kube-proxy, and a DaemonSet selector cannot change. To take it over, pass this setting when you install, and keep it on every update:

{"selectorLabelsOverride": {"k8s-app": "kube-proxy"}}

Chart settings that the schema leaves out

The schema accepts no other chart setting. In particular:

• args, by capability parity: AWS's own add-on accepts no free-form kube-proxy flags, so this add-on does not either.
• apiServer.endpoint, as an injected setting: EKS sets it to each cluster's API server endpoint.
• image, imagePullSecrets, podSecurityContext, securityContext, init, serviceAccount, rbac, nameOverride, and fullnameOverride, as excluded settings: the add-on fixes the images it runs, its security contexts, its service account and RBAC rules, and its object names.
• tolerations, affinity, nodeSelector, commonLabels, priorityClassName, the probes, updateStrategy, logLevel, and the rest of config, by the first-schema rule: the schema starts with AWS's settings and the adoption setting, and adds others when customers ask.