{"id":15567816,"url":"https://github.com/circa10a/k8s-label-rules-webhook","last_synced_at":"2025-10-12T21:30:49.314Z","repository":{"id":36616427,"uuid":"227957867","full_name":"circa10a/k8s-label-rules-webhook","owner":"circa10a","description":"A validating admission webhook to ensure compliant labels in your k8s cluster","archived":true,"fork":false,"pushed_at":"2023-02-28T03:53:15.000Z","size":915,"stargazers_count":53,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-09T17:44:47.781Z","etag":null,"topics":["admission-webhook","go","golang","hacktoberfest","kubernetes","kubernetes-webhook"],"latest_commit_sha":null,"homepage":"https://caleblemoine.dev/k8s-label-rules-webhook/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/circa10a.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2019-12-14T03:03:16.000Z","updated_at":"2024-07-18T23:45:18.000Z","dependencies_parsed_at":"2024-04-30T04:41:59.307Z","dependency_job_id":null,"html_url":"https://github.com/circa10a/k8s-label-rules-webhook","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fk8s-label-rules-webhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fk8s-label-rules-webhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fk8s-label-rules-webhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fk8s-label-rules-webhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circa10a","download_url":"https://codeload.github.com/circa10a/k8s-label-rules-webhook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236274592,"owners_count":19122692,"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":["admission-webhook","go","golang","hacktoberfest","kubernetes","kubernetes-webhook"],"created_at":"2024-10-02T17:13:25.060Z","updated_at":"2025-10-12T21:30:43.990Z","avatar_url":"https://github.com/circa10a.png","language":"Go","funding_links":["https://www.buymeacoffee.com/caleblemoine"],"categories":[],"sub_categories":[],"readme":"# [k8s-label-rules-webhook](https://github.com/circa10a/k8s-label-rules-webhook)\n\nEnforce standards for labels of resources being created in your k8s cluster\n\n![image](https://i.imgur.com/yiqw1we.png)\n\n![Build Status](https://github.com/circa10a/k8s-label-rules-webhook/workflows/GoReleaser/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/circa10a/k8s-label-rules-webhook)](https://goreportcard.com/report/github.com/circa10a/k8s-label-rules-webhook)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/circa10a/k8s-label-rules-webhook?style=plastic)\n![Docker Pulls](https://img.shields.io/docker/pulls/circa10a/k8s-label-rules-webhook?style=plastic)\n[![Buy Me A Coffee](https://img.shields.io/badge/BuyMeACoffee-Donate-ff813f.svg?logo=CoffeeScript\u0026style=plastic)](https://www.buymeacoffee.com/caleblemoine)\n\n## Table of Contents\n\n* [Usage](#usage)\n  + [Docker](#docker)\n    - [Volume mount your `rules.yaml` file](#volume-mount-your-rulesyaml-file)\n    - [Build your own docker image](#build-your-own-docker-image)\n  + [Kubernetes](#kubernetes)\n    - [Deploy webhook application](#deploy-webhook-application)\n    - [Deploy webhook application (TLS)](#deploy-webhook-application-tls)\n    - [Deploy admission webhook](#deploy-admission-webhook)\n* [Features](#features)\n  + [Hot reloading of ruleset](#hot-reloading-of-ruleset)\n  + [Rule validation](#rule-validation)\n  + [Easily view loaded ruleset](#easily-view-loaded-ruleset)\n  + [Prometheus Metrics](#prometheus-metrics)\n* [Configuration](#configuration)\n* [Development](#development)\n  + [Build](#build)\n  + [Run](#run)\n  + [Test](#test)\n* [Changelog](#changelog)\n* [Troubleshooting](#troubleshooting)\n\n## Usage\n\n![gif](https://j.gifs.com/6X7Vvn.gif)\n\nStart by creating a `rules.yaml` file containing rules for labels you require for your cluster resources to have along with a regex pattern for the values of the labels.\n\n\u003e Any rules specified in the rulseset will be required on resources to which you configure the admission webhook to fire on. View the kubernetes deployment section.\n\n```yaml\nrules:\n  - name: require-phone-number\n    key: phone-number\n    value:\n      regex: \"[0-9]{3}-[0-9]{3}-[0-9]{4}\" # 555-555-5555\n  - name: require-owner\n    key: owner\n    value:\n      regex: \".*\" # Any pattern matches, Just ensure a label of \"owner\" is set\n```\n\n\u003e IMPORTANT NOTE: Invalid regex for a given rule will make the rule default to .* which will allow any label value, but will still require the label to be present\n\nOnce you have your ruleset, you can deploy the webhook several different ways.\n\n### Docker\n\n#### Volume mount your `rules.yaml` file\n\n```shell\ndocker run -d --name k8s-label-rules-webhook \\\n  -p 8080:8080 \\\n  -v $PWD/rules.yaml:/rules.yaml \\\n  circa10a/k8s-label-rules-webhook\n```\n\n#### Build your own docker image\n\n```dockerfile\nFROM circa10a/k8s-label-rules-webhook\nCOPY rules.yaml /\n```\n\n### Kubernetes\n\n#### Deploy webhook application\n\n\u003e Kubernetes admission webhooks require https\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: label-rules-webhook\n  labels:\n    app: label-rules-webhook\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: label-rules-webhook\n  template:\n    metadata:\n      labels:\n        app: label-rules-webhook\n    spec:\n      containers:\n      - name: label-rules-webhook\n        image: circa10a/k8s-label-rules-webhook\n        volumeMounts:\n        - name: label-rules\n          mountPath: /rules.yaml\n          subPath: rules.yaml\n        readinessProbe:\n          httpGet:\n            path: /rules\n            port: gin-port\n          initialDelaySeconds: 5\n          periodSeconds: 15\n        livenessProbe:\n          httpGet:\n            path: /rules\n            port: gin-port\n          initialDelaySeconds: 5\n          periodSeconds: 15\n        ports:\n        - name: gin-port\n          containerPort: 8080\n      volumes:\n        - name: label-rules\n          configMap:\n            name: label-rules\n---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: label-rules\ndata:\n  rules.yaml: |\n    rules:\n      - name: require-phone-number\n        key: phone-number\n        value:\n          regex: \"[0-9]{3}-[0-9]{3}-[0-9]{4}\"\n      - name: require-number\n        key: number\n        value:\n          regex: \"[0-1]{1}\"\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: label-rules-webhook-service\nspec:\n  selector:\n    app: label-rules-webhook\n  ports:\n  - protocol: TCP\n    port: 8080\n    targetPort: gin-port\n  type: NodePort\n---\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n  name: label-rules-webhook-ingress\nspec:\n  backend:\n    serviceName: label-rules-webhook-service\n    servicePort: 8080\n```\n\n#### Deploy webhook application (TLS)\n\nTo have the web server listen on https, you need to supply a certificate and a key in conjunction with the appropriate [configuration options](#configuration).\n\nHere's an [example deployment](examples/tls.yaml) which supplies a cert, key and enables TLS in the application.\n\n\u003e Note: The TLS example only works in the `default` namespace. The subject alt name in the certificate is label-rules-webhook-service.default.svc\n\u003e Note: The default https port is `8443`\n\n#### Deploy admission webhook\n\n[More info on kubernetes admission webhooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)\n\n```yaml\napiVersion: admissionregistration.k8s.io/v1beta1\nkind: ValidatingWebhookConfiguration\nmetadata:\n  name: label-rules-webhook\nwebhooks:\n- name: my.application.domain\n  clientConfig:\n    clientConfig:\n    caBundle: \u003cbase64 encoded cert bundle\u003e\n    service:\n      namespace: \"default\"\n      name: \"label-rules-webhook-service\"\n      port: 8443\n  rules:\n  - operations:\n    - \"CREATE\"\n    - \"UPDATE\"\n    apiGroups:\n      - \"apps\"\n    apiVersions:\n      - \"v1\"\n      - \"v1beta1\"\n    resources:\n      - \"deployments\"\n      - \"replicasets\"\n  failurePolicy: Fail # Ignore, Fail\n```\n\n## Features\n\nCheckout the swagger api docs at `/swagger/index.html`\n\n### Hot reloading of ruleset\n\nUpdate the `rules.yaml` file used by your deployed instance then send a `POST` request to `/reload` to reload the rules into memory without downtime.\n\n### Rule validation\n\nThe regex supplied to each rule is compiled when the application starts and any problems are logged.\n\nYou can access the `/validate` endpoint via `GET` request to view any issues with the current ruleset that is loaded.\n\n### Easily view loaded ruleset\n\nAccess the `/rules` endpoint via `GET` request to see the current rules loaded.\n\n### Prometheus Metrics\n\nPrometheus metrics are enabled by default and are available at the `/metrics` endpoint. Simply unset the `METRICS` environment variable to disable.\n\n## Configuration\n\n|             |                                                                       |                      |                        |           |               |\n|-------------|-----------------------------------------------------------------------|----------------------|------------------------|-----------|---------------|\n| Name        | Description                                                           | Environment Variable | Command Line Argument  | Required | Default        |\n| Gin mode    | Runs web server in production or debug mode                           | `GIN_MODE`           | None                   | `false`  | `release`      |\n| Port        | Port for web server to listen on                                      | `PORT`               | None                   | `false`  | `8080`         |\n| Metrics     | Enables prometheus metrics on `/metrics`(unset for false)             | `METRICS`            | `--metrics`            | `false`  | `true`         |\n| Rules       | File containing user defined ruleset(default looks to `./rules.yaml`) | None                 | `--file`               | `true`   | `./rules.yaml` |\n| TLS         | Start web server listening on HTTPS                                   | `TLS_ENABLED`        | `--tls`                | `false`  | `false`        |\n| TLS Cert    | TLS Certificate file path                                             | `TLS_CERT`           | `--tls-cert`           | `false`  | None           |\n| TLS Key     | TLS key file path                                                     | `TLS_KEY`            | `--tls-key`            | `false`  | None           |\n| TLS Port    | TLS listening port                                                    | None                 | `--tls-port`           | `false`  | `8443`         |\n\n## Development\n\n### Build\n\n```shell\nmake build\n```\n\n### Run\n\n```shell\nmake run\n```\n\nAccess via http://localhost:8080\n\n### Test\n\n```shell\nmake test\n```\n\n## Changelog\n\nAutomated under [releases](https://github.com/circa10a/k8s-label-rules-webhook/tree/main)\n\n## Troubleshooting\n\n### Debug web server\n\nTry setting the debug environment variable for the gin web server which is `GIN_MODE=debug`.\n\n### Rule validation problems\n\nEnsure there are no regex compilation errors by accessing the `/validate` endpoint.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fk8s-label-rules-webhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirca10a%2Fk8s-label-rules-webhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fk8s-label-rules-webhook/lists"}