https://github.com/athenz/garm

Garm is kubernetes authorization webhook (SubjectAccessReview API) server for Athenz
https://github.com/athenz/garm

athenz garm go kubernetes kubernetes-authorization subject-access-request

Last synced: 10 months ago
JSON representation

Garm is kubernetes authorization webhook (SubjectAccessReview API) server for Athenz

• Host: GitHub
• URL: https://github.com/athenz/garm
• Owner: AthenZ
• License: apache-2.0
• Created: 2022-04-15T10:46:58.000Z (about 4 years ago)
• Default Branch: master
• Last Pushed: 2025-03-05T02:19:58.000Z (over 1 year ago)
• Last Synced: 2025-04-02T23:41:39.772Z (about 1 year ago)
• Topics: athenz, garm, go, kubernetes, kubernetes-authorization, subject-access-request
• Language: Go
• Homepage:
• Size: 1.45 MB
• Stars: 4
• Watchers: 6
• Forks: 1
• Open Issues: 9
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Governance: GOVERNANCE.md

Awesome Lists containing this project

README

          
# Garm

[![License: Apache](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)

[![GitHub release (latest by date)](https://img.shields.io/github/v/release/AthenZ/garm?style=flat-square&label=Github%20version)](https://github.com/AthenZ/garm/releases/latest)

[![Docker Image Version (tag latest)](https://img.shields.io/docker/v/athenz/garm/latest?style=flat-square&label=Docker%20version)](https://hub.docker.com/r/athenz/garm/tags)

[![Go Report Card](https://goreportcard.com/badge/github.com/AthenZ/garm)](https://goreportcard.com/report/github.com/AthenZ/garm)

[![GoDoc](http://godoc.org/github.com/AthenZ/garm?status.svg)](http://godoc.org/github.com/AthenZ/garm)

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](code_of_conduct.md)

![logo](./images/logo.png)

- [What is Garm](#what-is-garm)

- [Use Case](#use-case)

  - [Authorization](#authorization)

  - [Docker](#docker)

  - [Usage](#usage)

- [About releases](#about-releases)

## What is Garm

![concept](./docs/assets/concept.png)

Garm implements the Kubernetes authorization webhook interface to provide access control on your K8s resources with [Athenz](https://github.com/AthenZ/athenz) RBAC policy. It allows flexible resource mapping from K8s resources to Athenz ones, mutli-tenancy, and black/white list.

By default, Garm replies the native Kubernetes authentication for authorization. However, it also supports the Kubernetes authentication webhook. Using the authentication hook requires Athenz to be able to sign tokens for users.

Requires go 1.18 or later.

## Use Case

### Authorization

![use case](./docs/assets/use-case.png)

1. K8s webhook request (SubjectAccessReview) ([Webhook Mode - Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/webhook/))

    - the K8s API server wants to know if the user is allowed to do the requested action

2. Athenz RBAC request ([Athenz](http://www.athenz.io/))

    - Athenz server contains the user authorization information for access control

    - ask Athenz server is the user action is allowed based on pre-configured policy

Garm convert the K8s request to Athenz request based on the mapping rules in `config.yaml` ([example](./config/testdata/example_config.yaml)).

- [Conversion logic](./docs/garm-functional-overview.md)

- [Config details](./docs/config-detail.md)

P.S. It is just a sample deployment solution above. Garm can work on any environment as long as it can access both the API server and the Athenz server.

### Docker

```shell

$ docker pull docker.io/athenz/garm

```

### Usage

- [install Garm](https://github.com/AthenZ/garm/blob/master/docs/installation/02.%20install-garm.md)

- [configure k8s webhook](https://github.com/AthenZ/garm/blob/master/docs/installation/03.%20config-k8s-in-webhook-mode.md)

- [configure Athenz & Garm yaml](./docs/config-detail.md)

## About releases

- Releases

  - [![GitHub release (latest by date)](https://img.shields.io/github/v/release/AthenZ/garm?style=flat-square&label=Github%20version)](https://github.com/AthenZ/garm/releases/latest)

  - [![Docker Image Version (tag latest)](https://img.shields.io/docker/v/athenz/garm/latest?style=flat-square&label=Docker%20version)](https://hub.docker.com/r/athenz/garm/tags)