generated from kubewarden/go-policy-template
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1 from viccuad/hostpaths
Add implementation of hostpaths policy
- Loading branch information
Showing
27 changed files
with
1,532 additions
and
1,317 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,115 +1,43 @@ | ||
| # go-policy-template | ||
| # psp-hostpaths-policy | ||
|
|
||
| This is a template repository that can be used to to quickly scaffold a | ||
| Kubewarden policy written with Go language. | ||
| Replacement for the Kubernetes Pod Security Policy that controls the usage of | ||
| `hostPath` volumes. The policy inspects both the containers and the init | ||
| containers that are using `hostPath` volumes. | ||
|
|
||
| Don't forget to checkout Kubewarden's [official documentation](https://docs.kubewarden.io) | ||
| for more information about writing policies. | ||
| ## Settings | ||
|
|
||
| ## Introduction | ||
|
|
||
| This repository contains a working policy written in Go. | ||
|
|
||
| The policy looks at the `name` of a Kubernetes resource and rejects the request | ||
| if the name is on a deny list. | ||
|
|
||
| The deny list is configurable by the user via the runtime settings of the policy. | ||
| The configuration of the policy is expressed via this structure: | ||
|
|
||
| ```json | ||
| { | ||
| "denied_names": [ "badname1", "badname2" ] | ||
| } | ||
| ```yaml | ||
| allowedHostPaths: | ||
| - pathPrefix: "/foo" | ||
| readOnly: true | ||
| - pathPrefix: "/bar" | ||
| readOnly: false | ||
| ``` | ||
| ## Code organization | ||
|
|
||
| The code that takes care of parsing the settings can be found inside of the | ||
| `settings.go` file. | ||
|
|
||
| The actual validation code is defined inside of the `validate.go` file. | ||
|
|
||
| The `main.go` contains only the code which registers the entry points of the | ||
| policy. | ||
|
|
||
| ## Implementation details | ||
|
|
||
| > **DISCLAIMER:** WebAssembly is a constantly evolving topic. This document | ||
| > describes the status of the Go ecosystem at April 2021. | ||
| Currently the official Go compiler cannot produce WebAssembly binaries | ||
| that can be run **outside** of the browser. Because of that, Kubewarden Go | ||
| policies can be built only with the [TinyGo](https://tinygo.org/) compiler. | ||
|
|
||
| TinyGo doesn't yet support all the Go features (see [here](https://tinygo.org/lang-support/) | ||
| to see the current project status). Currently its biggest limitation | ||
| is the lack of a fully supported `reflect` package. Among other things, that | ||
| leads to the inability to use the `encoding/json` package against structures | ||
| and user defined types. | ||
| `allowedHostPaths` is a list of host paths that are allowed to be used by | ||
| `hostPath` volumes. | ||
|
|
||
| Kubewarden policies need to process JSON data like the policy settings and | ||
| the actual request received by Kubernetes. | ||
| However it's still possible to write a Kubewarden policy by using some 3rd party | ||
| libraries. | ||
| An empty `allowedHostPaths` list means there is no restriction on host paths | ||
| used. | ||
|
|
||
| This is a list of libraries that can be useful when writing a Kubewarden | ||
| policy: | ||
| Each entry of `allowedHostPaths` must have: | ||
| - A `pathPrefix` field, which allows `hostPath` volumes to mount a path that | ||
| begins with an allowed prefix. | ||
| - a `readOnly` field indicating it must be mounted read-only. | ||
|
|
||
| * Parsing JSON: queries against JSON documents can be written using the | ||
| [gjson](https://github.com/tidwall/gjson) library. The library features a | ||
| powerful query language that allows quick navigation of JSON documents and | ||
| data retrieval. | ||
| * Mutating JSON: changing the contents of a JSON document can be done using the | ||
| [sjson](https://github.com/tidwall/sjson) library. | ||
| * Generic `set` implementation: using [Set](https://en.wikipedia.org/wiki/Set_(abstract_data_type)) | ||
| data types can significantly reduce the amount of code inside of a policy, | ||
| see the `union`, `intersection`, `difference`,... operations provided | ||
| by a Set implementation. | ||
| The [mapset](https://github.com/deckarep/golang-set) can be used when writing | ||
| policies. | ||
| ### Special behaviour | ||
|
|
||
| Last but not least, this policy takes advantage of helper functions provided | ||
| by [Kubewarden's Go SDK](https://github.com/kubewarden/policy-sdk-go). | ||
| It's possible to have host paths sharing part of the prefix. In that case, the | ||
| `readOnly` attribute of the most specific path takes precedence. | ||
|
|
||
| ## Testing | ||
| For example, given the following configuration: | ||
|
|
||
| This policy comes with a set of unit tests implemented using the Go testing | ||
| framework. | ||
|
|
||
| As usual, the tests are defined inside of the `_test.go` files. Given these | ||
| tests are not part of the final WebAssembly binary, the official Go compiler | ||
| can be used to run them. Hence they can take advantage of the `encoding/json` | ||
| package to reduce some testing boiler plate. | ||
|
|
||
| The unit tests can be run via a simple command: | ||
|
|
||
| ```shell | ||
| make test | ||
| ```yaml | ||
| allowedHostPaths: | ||
| - pathPrefix: "/foo" | ||
| readOnly: false | ||
| - pathPrefix: "/foo/bar" | ||
| readOnly: true | ||
| ``` | ||
|
|
||
| It's also important the test the final result of the TinyGo compilation: | ||
| the actual WebAssembly module. | ||
|
|
||
| This is done by a second set of end-to-end tests. These tests use the | ||
| `policicy-testdrive` cli provided by the Kubewarden project to load and execute | ||
| the policy. | ||
|
|
||
| The e2e tests are implemented using [bats](https://github.com/sstephenson/bats): | ||
| the Bash Automated Testing System. | ||
|
|
||
| The end-to-end tests are defined inside of the `e2e.bats` file and can | ||
| be run via this commmand: | ||
|
|
||
| ```shell | ||
| make e2e-tests | ||
| ``` | ||
|
|
||
| ## Automation | ||
|
|
||
| This project contains the following [GitHub Actions](https://docs.github.com/en/actions): | ||
|
|
||
| * `e2e-tests`: this action builds the WebAssembly policy, installs | ||
| the `bats` utility and then runs the end-to-end test | ||
| * `unit-tests`: this action runs the Go unit tests | ||
| * `release`: this action builds the WebAssembly policy and pushes it to a | ||
| user defined OCI registry ([ghcr](https://ghcr.io) is a perfect candidate) | ||
| Paths such as `/foo/bar/dir1`, `/foo/bar` must be read only. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.