{"id":22475486,"url":"https://github.com/philips/ip-masq-agent","last_synced_at":"2025-03-27T17:27:16.935Z","repository":{"id":66550450,"uuid":"91134332","full_name":"philips/ip-masq-agent","owner":"philips","description":"Container that configures iptables to skip MASQUERADE for certain CIDR ranges. Intended to run as a K8s DaemonSet.","archived":false,"fork":false,"pushed_at":"2017-05-12T22:34:20.000Z","size":231,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T20:31:37.490Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philips.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-12T22:33:38.000Z","updated_at":"2018-07-13T22:30:09.000Z","dependencies_parsed_at":"2023-02-28T13:16:10.169Z","dependency_job_id":null,"html_url":"https://github.com/philips/ip-masq-agent","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Fip-masq-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Fip-masq-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Fip-masq-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Fip-masq-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philips","download_url":"https://codeload.github.com/philips/ip-masq-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245891351,"owners_count":20689317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-06T13:17:33.501Z","updated_at":"2025-03-27T17:27:16.923Z","avatar_url":"https://github.com/philips.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ip-masq-agent\n\nThe ip-masq-agent configures `iptables` rules to `MASQUERADE` traffic outside link-local (optional, enabled by default) and additional arbitrary IP ranges.\n\nIt creates an `iptables` chain called `IP-MASQ-AGENT`, which contains match rules for link local (`169.254.0.0/16`) and each of the user-specified IP ranges. It also creates a rule in `POSTROUTING` that jumps to this chain for any traffic not bound for a `LOCAL` destination.\n\nIPs that match the rules (except for the final rule) in `IP-MASQ-AGENT` are *not* subject to `MASQUERADE` via the `IP-MASQ-AGENT` chain (they `RETURN` early from the chain). The final rule in the `IP-MASQ-AGENT` chain will `MASQUERADE` any non-`LOCAL` traffic.\n\n`RETURN` in `IP-MASQ-AGENT` resumes rule processing at the next rule the calling chain, `POSTROUTING`. Take care to avoid creating additional rules in `POSTROUTING` that cause packets bound for your configured ranges to undergo `MASQUERADE`.\n\n## Launching the agent as a DaemonSet\nThis repo includes an example yaml file that can be used to launch the ip-masq-agent as a DaemonSet in a Kubernetes cluster.\n\n```\nkubectl create -f ip-masq-agent.yaml\n```\n\nThe spec in `ip-masq-agent.yaml` specifies the `kube-system` namespace for the DaemonSet Pods.\n\n## Configuring the agent\n\nImportant: You should not attempt to run this agent in a cluster where the Kubelet is also configuring a non-masquerade CIDR. You can pass `--non-masquerade-cidr=0.0.0.0/0` to the Kubelet to nullify its rule, which will prevent the Kubelet from interfering with this agent.\n\nBy default, the agent is configured to treat the three private IP ranges specified by [RFC 1918](https://tools.ietf.org/html/rfc1918) as non-masquerade CIDRs. These ranges are `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16`. The agent will also treat link-local (`169.254.0.0/16`) as a non-masquerade CIDR by default.\n\nBy default, the agent is configured to reload its configuration from the `/etc/config/ip-masq-agent` file in its container every 60 seconds.\n\nThe agent configuration file should be written in yaml or json syntax, and may contain three optional keys:\n- `nonMasqueradeCIDRs []string`: A list strings in CIDR notation that specify the non-masquerade ranges.\n- `masqLinkLocal bool`: Whether to masquerade traffic to `169.254.0.0/16`. False by default.\n- `resyncInterval string`: The interval at which the agent attempts to reload config from disk. The syntax is any format accepted by Go's [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) function.\n\nThe agent will look for a config file in its container at `/etc/config/ip-masq-agent`. This file can be provided via a `ConfigMap`, plumbed into the container via a `ConfigMapVolumeSource`. As a result, the agent can be reconfigured in a live cluster by creating or editing this `ConfigMap`.\n\nThis repo includes a directory-representation of a `ConfigMap` that can configure the agent (the `agent-config` directory). To use this directory to create the `ConfigMap` in your cluster:\n\n```\nkubectl create configmap ip-masq-agent --from-file=agent-config --namespace=kube-system\n```\n\nNote that we created the `ConfigMap` in the same namespace as the DaemonSet Pods, and named the `ConfigMap` to match the spec in `ip-masq-agent.yaml`. This is necessary for the `ConfigMap` to appear in the Pods' filesystems.\n\n## Rationale\n(from the [incubator proposal](https://gist.github.com/mtaufen/253309166e7d5aa9e9b560600a438447))\n\nThis agent solves the problem of configuring the CIDR ranges for non-masquerade in a cluster (via iptables rules). Today, this is accomplished by passing a `--non-masquerade-cidr` flag to the Kubelet, which only allows one CIDR to be configured as non-masquerade. [RFC 1918](https://tools.ietf.org/html/rfc1918), however, defines three ranges (`10/8`, `172.16/12`, `192.168/16`) for the private IP address space.\n\nSome users will want to communicate between these ranges without masquerade - for instance, if an organization's existing network uses the `10/8` range, they may wish to run their cluster and `Pod`s in `192.168/16` to avoid IP conflicts. They will also want these `Pod`s to be able to communicate efficiently (no masquerade) with each-other *and* with their existing network resources in `10/8`. This requires that every node in their cluster skips masquerade for both ranges.\n\nWe are trying to eliminate networking code from the Kubelet, so rather than extend the Kubelet to accept multiple CIDRs, ip-masq-agent allows you to run a DaemonSet that configures a list of CIDRs as non-masquerade.\n\n## Incubator\n\nThis is a [Kubernetes Incubator project](https://github.com/kubernetes/community/blob/master/incubator.md). The incubator team for the project is:\n\n- Author: Mike Taufen (@mtaufen)\n- Sponsor: Tim Hockin (@thockin)\n- Champion: Bowei Du (@bowei)\n- SIG: sig-awesome\n\n## Releasing\n\nSee [RELEASE](RELEASE.md).\n\n## Developing\n\nClone the repo to `$GOPATH/src/k8s.io/ip-masq-agent`.\n\nThe build tooling is based on [thockin/go-build-template](https://github.com/thockin/go-build-template).\n\nRun `make` or `make build` to compile the ip-masq-agent.  This will use a Docker image\nto build the agent, with the current directory volume-mounted into place.  This\nwill store incremental state for the fastest possible build.  Run `make\nall-build` to build for all architectures.\n\nRun `make test` to run the unit tests.\n\nRun `make container` to build the container image.  It will calculate the image\ntag based on the most recent git tag, and whether the repo is \"dirty\" since\nthat tag (see `make version`).  Run `make all-container` to build containers\nfor all architectures.\n\nRun `make push` to push the container image to `REGISTRY`.  Run `make all-push`\nto push the container images for all architectures.\n\nRun `make clean` to clean up.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilips%2Fip-masq-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilips%2Fip-masq-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilips%2Fip-masq-agent/lists"}