Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jainishshah17/tugger
Kubernetes Admission Webhook to enforce pulling of Docker images from the private registry.
https://github.com/jainishshah17/tugger
admission-controllers docker docker-registry enforce-pulling kubernetes kubernetes-admission-webhook mutatingadmissionwebhook
Last synced: about 1 month ago
JSON representation
Kubernetes Admission Webhook to enforce pulling of Docker images from the private registry.
- Host: GitHub
- URL: https://github.com/jainishshah17/tugger
- Owner: jainishshah17
- License: apache-2.0
- Created: 2019-01-18T00:06:49.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-11-30T18:42:19.000Z (about 1 year ago)
- Last Synced: 2024-08-04T18:01:11.612Z (5 months ago)
- Topics: admission-controllers, docker, docker-registry, enforce-pulling, kubernetes, kubernetes-admission-webhook, mutatingadmissionwebhook
- Language: Go
- Homepage:
- Size: 591 KB
- Stars: 50
- Watchers: 5
- Forks: 21
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Tugger
### What does Tugger do?
Tugger is Kubernetes Admission webhook to enforce pulling of docker images from private registry.
### Prerequisites
Kubernetes 1.9.0 or above with the `admissionregistration.k8s.io/v1` API enabled. Verify that by the following command:
```
kubectl api-versions | grep admissionregistration.k8s.io/v1beta1
```
The result should be:
```
admissionregistration.k8s.io/v1beta1
```
In addition, the `MutatingAdmissionWebhook` and `ValidatingAdmissionWebhook` admission controllers should be added and listed in the correct order in the admission-control flag of kube-apiserver.
### Build and Push Tugger Docker Image
```bash
# Build docker image
docker build -t jainishshah17/tugger:0.1.8 .
# Push it to Docker Registry
docker push jainishshah17/tugger:0.1.8
```
### Create [Kubernetes Docker registry secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)
```bash
# Create a Docker registry secret called 'regsecret'
kubectl create secret docker-registry regsecret --docker-server=${DOCKER_REGISTRY} --docker-username=${DOCKER_USER} --docker-password=${DOCKER_PASS} --docker-email=${DOCKER_EMAIL}
```
**Note**: Create Docker registry secret in each non-whitelisted namespaces.
### Generate TLS Certs for Tugger
```bash
./tls/gen-cert.sh
```
### Get CA Bundle
```bash
./webhook/webhook-patch-ca-bundle.sh
```
### Deploy Tugger to Kubernetes
#### Deploy using Helm Chart
The helm chart can generate certificates and configure webhooks in a single step. See the notes on webhooks below for more information.
```bash
# Add Tugger Helm repository
helm repo add tugger https://jainishshah17.github.io/tugger
# Update Helm repository index
helm repo update
```
```bash
helm install --name tugger \
--set docker.registrySecret=regsecret, \
--set docker.registryUrl=jainishshah17, \
--set whitelistNamespaces={kube-system,default}, \
--set whitelistRegistries={jainishshah17} \
--set createValidatingWebhook=true \
--set createMutatingWebhook=true \
tugger/tugger
```
#### Deploy using kubectl
1. Create deployment and service
```bash
# Run deployment
kubectl create -f deployment/tugger-deployment.yaml
# Create service
kubectl create -f deployment/tugger-svc.yaml
```
2. Configure `MutatingAdmissionWebhook` and `ValidatingAdmissionWebhook`
**Note**: Replace `${CA_BUNDLE}` with value generated by running `./webhook/webhook-patch-ca-bundle.sh`
```bash
# re MutatingAdmissionWebhook
kubectl create -f webhook/tugger-mutating-webhook ration.yaml
```
Note: Use MutatingAdmissionWebhook only if you want to enforce pulling of docker image from Private Docker Registry e.g [JFrog Artifactory](https://jfrog.com/artifactory/).
If your container image is `nginx` then Tugger will append `REGISTRY_URL` to it. e.g `nginx` will become `jainishshah17/nginx`
```bash
# Configure ValidatingWebhookConfiguration
kubectl create -f webhook/tugger-validating-webhook ration.yaml
```
Note: Use ValidatingWebhookConfiguration only if you want to check pulling of docker image from Private Docker Registry e.g [JFrog Artifactory](https://jfrog.com/artifactory/).
If your container image does not contain `REGISTRY_URL` then Tugger will deny request to run that pod.
### Test Tugger
```bash
# Deploy nginx
kubectl apply -f test/nginx.yaml
```
## Configure
The mutation or validation policy can be defined as a list of rules in a YAML file.
The YALM file can be specified with the command line argument `--policy-file=FILE`, or when using the Helm chart, populate `rules:` in values.
### Schema
```yaml
rules:
- pattern: regex
replacement: template (optional)
condition: policy (optional)
- ...
```
_pattern_ is a regex pattern
_replacement_ is a template comprised of the captured groups to use to generate the new image name in the mutating admission controller. When _replacement_ is `null` or undefined, the image name is allowed without patching. Rules with this field are ignored by the validating admission controller, where mutation is not supported.
_condition_ is a special condition to test before committing the replacement. Initially `Always` and `Exists` will be supported. `Always` is the default and performs the replacement regardless of any condition. `Exists` implements the behavior from #7; it only rewrites the image name if the target name exists in the remote registry.
Each rule will be evaluated in order, and if the list is exhausted without a match, the admission controller will return `allowed: false`.
### Examples
This example allows all images without rewriting:
```yaml
rules:
- pattern: .*
```
This example implements the default behavior of rewriting all image names to start with `jainishshah17`:
```yaml
rules:
- pattern: ^jainishshah17/.*
- pattern: (.*)
replacement: jainishshah17/$1
```
Or the same thing, but only if the image exists in `jainishshah17/`, and allowing all other images:
```yaml
rules:
- pattern: ^jainishshah17/.*
- pattern: (.*)
replacement: jainishshah17/$1
condition: Exists
- pattern: .*
```
Allow the nginx image, but rewrite everything else:
```yaml
rules:
- pattern: ^nginx(:.*)?$
- pattern: (?:jainishshah17)?(.*)
replacement: jainishshah17/$1
```