{"id":26653718,"url":"https://github.com/sighupio/module-policy","last_synced_at":"2025-07-10T20:12:23.242Z","repository":{"id":38237979,"uuid":"207518853","full_name":"sighupio/module-policy","owner":"sighupio","description":"Policy Module: Policy enforcement for your Kubernetes Cluster","archived":false,"fork":false,"pushed_at":"2025-04-02T14:47:23.000Z","size":1670,"stargazers_count":38,"open_issues_count":0,"forks_count":10,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-06-15T00:36:57.103Z","etag":null,"topics":["cncf","fury","gatekeeper","k8s","kubernetes","module","opa","sighup"],"latest_commit_sha":null,"homepage":"https://docs.sighup.io/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sighupio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2019-09-10T09:32:38.000Z","updated_at":"2025-04-02T14:46:48.000Z","dependencies_parsed_at":"2024-01-23T14:48:04.769Z","dependency_job_id":"1bd3e4d4-1a3a-4159-8144-5861451827af","html_url":"https://github.com/sighupio/module-policy","commit_stats":null,"previous_names":["sighupio/module-policy","sighupio/fury-kubernetes-opa"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/sighupio/module-policy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sighupio%2Fmodule-policy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sighupio%2Fmodule-policy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sighupio%2Fmodule-policy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sighupio%2Fmodule-policy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sighupio","download_url":"https://codeload.github.com/sighupio/module-policy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sighupio%2Fmodule-policy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264648521,"owners_count":23643669,"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":["cncf","fury","gatekeeper","k8s","kubernetes","module","opa","sighup"],"created_at":"2025-03-25T04:02:11.316Z","updated_at":"2025-07-10T20:12:23.210Z","avatar_url":"https://github.com/sighupio.png","language":"Shell","funding_links":[],"categories":["kubernetes"],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD033 --\u003e\n\u003ch1 align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/sighupio/distribution/refs/heads/main/docs/assets/white-logo.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/sighupio/distribution/refs/heads/main/docs/assets/black-logo.png\"\u003e\n  \u003cimg alt=\"Shows a black logo in light color mode and a white one in dark color mode.\" src=\"https://raw.githubusercontent.com/sighupio/distribution/refs/heads/main/docs/assets/white-logo.png\"\u003e\n\u003c/picture\u003e\u003cbr/\u003e\n  Policy Module\n\u003c/h1\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n![Release](https://img.shields.io/badge/Latest%20Release-v1.14.0-blue)\n![License](https://img.shields.io/github/license/sighupio/module-policy?label=License)\n![Slack](https://img.shields.io/badge/slack-@kubernetes/fury-yellow.svg?logo=slack\u0026label=Slack)\n\n\u003c!-- \u003cKFD-DOCS\u003e --\u003e\n\n**Policy Module** provides policy enforcement at runtime for the [SIGHUP Distribution (SD)][skd-repo].\n\nIf you are new to SD please refer to the [official documentation][skd-docs] on how to get started with SD.\n\n## Overview\n\n\u003e [!TIP]\n\u003e [Starting from Kubernetes v1.25][kubernetes-pss-stable], [Pod Security Standards (PSS)][kubernetes-pss] are promoted to stable. For most use cases, the policies defined in the Pod Security Standards are a great starting point, consider applying them before switching to one the of tools provided by this module.\n\u003e\n\u003e For more advanced use-cases, where custom policies that are not included in the PSS must be enforced, this module is the right choice.\n\nThe Kubernetes API server provides a mechanism to review every request that is made (object creation, modification, or deletion). To use this mechanism the API server allows us to create a [Validating Admission Webhook][kubernetes-vaw-docs] that, as the name says, will validate every request and let the API server know if the request is allowed or not based on some logic (policy).\n\n**Policy Module** module is based on [Gatekeeper][gatekeeper-page] and [Kyverno][kyverno-page], two popular open-source Kubernetes-native policy engines that runs as a Validating Admission Webhook. It allows writing custom constraints (policies) and enforcing them at runtime.\n\n[SIGHUP][sighup-page] provides a set of base constraints that could be used both as a starting point to apply constraints to your current workloads and to give you an idea of how to implement new rules matching your requirements.\n\n## Packages\n\nPolicy Module provides the following packages:\n\n| Package                                                | Version   | Description                                                                                                                                             |\n| ------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Gatekeeper Core](katalog/gatekeeper/core)             | `v3.18.2` | Gatekeeper deployment, ready to enforce rules.                                                                                                          |\n| [Gatekeeper Rules](katalog/gatekeeper/rules)           | `N.A.`    | A set of custom rules to get started with policy enforcement.                                                                                           |\n| [Gatekeeper Monitoring](katalog/gatekeeper/monitoring) | `N.A.`    | Metrics, alerts and dashboard for monitoring Gatekeeper.                                                                                                |\n| [Gatekeeper Policy Manager](katalog/gatekeeper/gpm)    | `v1.0.13` | Gatekeeper Policy Manager, a simple to use web-ui for Gatekeeper.                                                                                       |\n| [Kyverno](katalog/kyverno)                             | `v1.13.4` | Kyverno is a policy engine designed for Kubernetes. It can validate, mutate, and generate configurations using admission controls and background scans. |\n\nClick on each package name to see its full documentation.\n\n## Compatibility\n\n| Kubernetes Version |   Compatibility    | Notes           |\n| ------------------ | :----------------: | --------------- |\n| `1.32.x`           | :white_check_mark: | No known issues |\n| `1.31.x`           | :white_check_mark: | No known issues |\n| `1.30.x`           | :white_check_mark: | No known issues |\n| `1.29.x`           | :white_check_mark: | No known issues |\n\nCheck the [compatibility matrix][compatibility-matrix] for additional information on previous releases of the module.\n\n## Usage\n\n\u003e [!NOTE]\n\u003e The following instructions are for using the module with furyctl legacy, or downloading it and using it via kustomize.\n\u003e\n\u003e In the latest versions of the SIGHUP Distribution the Policy Module is natively integrated and can be used and configured by the `.spec.distribution.modules.policy` key in the configuration file.\n\n### Prerequisites\n\n| Tool                                    | Version    | Description                                                                                                                                                    |\n| --------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [furyctl][furyctl-repo]                 | `\u003e=0.27.0` | The recommended tool to download and manage SD modules and their packages. To learn more about `furyctl` read the [official documentation][furyctl-repo].     |\n| [kustomize][kustomize-repo]             | `\u003e=3.10.0` | Packages are customized using `kustomize`. To learn how to create your customization layer with `kustomize`, please refer to the [repository][kustomize-repo]. |\n| [SD Monitoring Module][skd-monitoring] | `\u003ev1.10.0` | Expose metrics to Prometheus *(optional)* and use Grafana Dashboards.                                                                                          |\n\n\u003e You can comment out the service monitor in the [kustomization.yaml][core-kustomization] file if you don't want to install the monitoring module.\n\n### Gatekeeper deployment\n\n1. List the packages you want to deploy and their version in a `Furyfile.yml`\n\n```yaml\nbases:\n  - name: opa/gatekeeper\n    version: \"1.14.0\"\n```\n\n\u003e See `furyctl` [documentation][furyctl-repo] for additional details about `Furyfile.yml` format.\n\n2. Execute `furyctl legacy vendor -H` to download the packages\n\n3. Inspect the download packages under `./vendor/katalog/opa/gatekeeper`.\n\n4. Define a `kustomization.yaml` that includes the `./vendor/katalog/opa/gatekeeper` directory as a resource.\n\n```yaml\nresources:\n  - ./vendor/katalog/opa/gatekeeper\n```\n\n5. Apply the necessary patches. You can find a list of common customization [here](#common-customizations).\n\n6. To deploy the packages to your cluster, execute:\n\n```bash\nkustomize build . | kubectl apply -f -\n```\n\n\u003e [!WARNING]\n\u003e Gatekeeper is deployed by default as a Fail open (also called `Ignore` mode) Admission Webhook. Should you decide to change it to `Fail` mode read carefully [the project's documentation on the topic first][gatekeeper-failmode].\n\u003c!-- space intentionally left blank --\u003e\n\u003e [!TIP]\n\u003e If you decide to deploy Gatekeeper to a different namespace than the default `gatekeeper-system`, you'll need to patch the file `vwh.yml` to point to the right namespace for the webhook service due to limitations in the `kustomize` tool.\n\n#### Common Customizations\n\n##### Exempting a namespace\n\nGatekeeper supports 3 levels of granularity to exempt a namespace from policy enforcement.\n\n1. Global exemption at Kubernetes API webhook level: the requests to the API server for the namespace won't be sent to Gatekeeper's webhook.\n2. Global exemption at Gatekeeper configuration level: requests to the API server for the namespace will be sent to Gatekeeper's webhook, but Gatekepeer will not enforce constraints for the namespace. It is the equivalent of exempting the namespace in all the constraints. Useful when you don't want any of the constraints enforced in a namespace.\n3. Exemption at constraint level: you can exempt namespaces in the definition of each constraint. Useful when you may want only a subset of all the constraints to be enforced in a namespace.\n\n\u003e [!CAUTION]\n\u003e Exempting critical namespaces like `kube-system` or `logging` [won't guarantee that the cluster will function properly when Gatekeeper webhook is in `Fail` mode][gatekeeper-failmode].\n\nFor more details on how to implement the exemption, please refer to the [official Gatekeeper documentation site][gatekeeper-exemption].\n\n##### Disable constraints\n\nDisable one of the default constraints by creating the following kustomize patch:\n\n```yml\npatchesJson6902:\n    - target:\n          group: constraints.gatekeeper.sh\n          version: v1beta1\n          kind: K8sUniqueIngressHost # replace with the kind of the constraint you want to disable\n          name: unique-ingress-host # replace with the name of the constraint you want to disable\n      path: patches/allow.yml\n```\n\nadd this to the `patches/allow.yml` file:\n\n```yml\n- op: \"replace\"\n  path: \"/spec/enforcementaction\"\n  value: \"allow\"\n```\n\n#### Emergency brake\n\nIf for some reason Gatekeeper is giving you issues and blocking normal operations in your cluster, you can disable it by removing the Validating Admission Webhook definition from your cluster:\n\n```bash\nkubectl delete ValidatingWebhookConfiguration gatekeeper-validating-webhook-configuration\n```\n\n#### Monitoring\n\nGatekeeper is configured by default in this module to expose some Prometheus metrics about its health, performance, and operative information.\n\nYou can monitor and review these metrics by checking out the provided Grafana dashboard. (This requires the SD Monitoring Module to be installed).\n\nGo to your cluster's Grafana and search for the \"Gatekeeper\" dashboard:\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\n\u003ca href=\"docs/images/screenshots/grafana-dashboard.png\"\u003e\u003cimg src=\"docs/images/screenshots/grafana-dashboard.png\" width=\"250\"/\u003e\u003c/a\u003e\n\n\u003c!-- markdownlint-enable MD033 --\u003e\n\nYou can also use [Gatekeeper Policy Manager](katalog/gatekeeper/gpm/README.md) to view the Constraints Templates, Constraints, and Violations in a simple-to-use UI.\n\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\n\u003ca href=\"docs/images/screenshots/gpm-screenhost.png\"\u003e\u003cimg src=\"docs/images/screenshots/gpm-screenhost.png\" width=\"250\"/\u003e\u003c/a\u003e\n\n\u003c!-- markdownlint-enable MD033 --\u003e\n\nTwo alerts are also provided by default with the module, the alerts are triggered when the number of errors seen by the Kubernetes API server trying to contact Gatekeeper's webhook is too high. Both for Fail open (`Ignore`) mode and Fail mode:\n\n| Alert                         | Description                                                                                                                                 |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| GatekeeperWebhookFailOpenHigh | Gatekeeper is not enforcing {{$labels.type}} requests to the API server.                                                                    |\n| GatekeeperWebhookCallError    | Kubernetes API server is rejecting all requests because Gatekeeper's webhook '{{ $labels.name }}' is failing for '{{ $labels.operation }}'. |\n\nNotice that the alert for when the Gatekeeper webhook is in `Ignore` mode (the default) depends on an API server metric that has been added in Kubernetes version 1.24. Previous versions of Kubernetes won't trigger alerts when the webhook is failing and in `Ignore` mode.\n\n### Kyverno deployment\n\n1. List the packages you want to deploy and their version in a `Furyfile.yml`\n\n```yaml\nbases:\n  - name: opa/kyverno\n    version: \"1.14.0\"\n```\n\n\u003e See `furyctl` [documentation][furyctl-repo] for additional details about `Furyfile.yml` format.\n\n2. Execute `furyctl legacy vendor -H` to download the packages\n\n3. Inspect the download packages under `./vendor/katalog/opa/kyverno`.\n\n4. Define a `kustomization.yaml` that includes the `./vendor/katalog/opa/kyverno` directory as a resource.\n\n```yaml\nresources:\n  - ./vendor/katalog/opa/kyverno\n```\n\n5. To deploy the packages to your cluster, execute:\n\n```bash\nkustomize build . | kubectl apply --server-side -f -\n```\n\n\u003c!-- Links --\u003e\n\n[kubernetes-pss-stable]: https://kubernetes.io/blog/2022/08/25/pod-security-admission-stable/\n[kubernetes-pss]: https://kubernetes.io/docs/concepts/security/pod-security-standards/\n\n[gatekeeper-page]: https://github.com/open-policy-agent/gatekeeper\n[gatekeeper-failmode]: https://open-policy-agent.github.io/gatekeeper/website/docs/failing-closed/\n[gatekeeper-exemption]: https://open-policy-agent.github.io/gatekeeper/website/docs/exempt-namespaces/\n\n[kyverno-page]: https://github.com/kyverno/kyverno\n[kubernetes-vaw-docs]: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/\n\n[core-kustomization]: ./katalog/gatekeeper/core/kustomization.yaml\n[compatibility-matrix]: https://github.com/sighupio/module-policy/blob/main/docs/COMPATIBILITY_MATRIX.md\n\n[sighup-page]: https://sighup.io\n[skd-repo]: https://github.com/sighupio/distribution\n[skd-docs]: https://docs.kubernetesfury.com/docs/distribution/\n[skd-monitoring]: https://github.com/sighupio/module-monitoring\n[furyctl-repo]: https://github.com/sighupio/furyctl\n[kustomize-repo]: https://github.com/kubernetes-sigs/kustomize\n\n\u003c!-- \u003c/KFD-DOCS\u003e --\u003e\n\n\u003c!-- \u003cFOOTER\u003e --\u003e\n\n## Contributing\n\nBefore contributing, please read the [Contributing Guidelines](docs/CONTRIBUTING.md).\n\n### Reporting Issues\n\nIn case you experience any problems with the module, please [open a new issue](https://github.com/sighupio/module-policy/issues/new/choose).\n\n## License\n\nThis module is open-source and released under the following [LICENSE](LICENSE)\n\n\u003c!-- \u003c/FOOTER\u003e --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsighupio%2Fmodule-policy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsighupio%2Fmodule-policy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsighupio%2Fmodule-policy/lists"}