https://github.com/pomerium/pomerium-operator
An operator for running Pomerium on a Kubernetes cluster.
https://github.com/pomerium/pomerium-operator
beyondcorp cloud-native go helm-chart identity kubernetes kubernetes-operator pomerium zero-trust
Last synced: 5 months ago
JSON representation
An operator for running Pomerium on a Kubernetes cluster.
- Host: GitHub
- URL: https://github.com/pomerium/pomerium-operator
- Owner: pomerium
- License: apache-2.0
- Archived: true
- Created: 2019-11-12T11:09:21.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-05-23T18:37:38.000Z (almost 3 years ago)
- Last Synced: 2024-08-03T15:16:53.474Z (9 months ago)
- Topics: beyondcorp, cloud-native, go, helm-chart, identity, kubernetes, kubernetes-operator, pomerium, zero-trust
- Language: Go
- Homepage: https://www.pomerium.io/
- Size: 325 KB
- Stars: 28
- Watchers: 7
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - pomerium/pomerium-operator - An operator for running Pomerium on a Kubernetes cluster. (go)
README
[](http://slack.pomerium.io)
[](https://goreportcard.com/report/github.com/pomerium/pomerium-operator)
[](https://codeclimate.com/github/pomerium/pomerium-operator/maintainability)
[](http://godoc.org/github.com/pomerium/pomerium-operator)
[](https://github.com/pomerium/pomerium-operator/blob/master/LICENSE)
[](https://codecov.io/gh/pomerium/pomerium-operator)
- [:warning: Deprecation Notice](#warning-deprecation-notice)
- [About](#about)
- [Initial discussion](#initial-discussion)
- [Installing](#installing)
- [Using](#using)
- [How it works](#how-it-works)
- [Annotations](#annotations)
- [Example](#example)
- [Development](#development)
- [Building](#building)
- [Roadmap](#roadmap)
# :warning: Deprecation Notice
We've just released a new Ingress Controller (docs [here](https://www.pomerium.com/docs/k8s/ingress.html)), which supersedes the operator.
[Pomerium Ingress Controller](https://github.com/pomerium/ingress-controller) addresses shortcomings in the operator and allows Pomerium to directly handle `Ingress` resources without the need for an external/third-party ingress controller. Additionally, the ingress controller supports Pomerium's new [policy language](https://www.pomerium.com/enterprise/reference/manage.html#pomerium-policy-language) and other features introduced in the last year or so.
As such, pomerium-operator will no longer be receiving updates. Most practically, the operator will not be supported on Kubernetes v1.22+ due to the [deprecation](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#ingress-v122) of the `v1beta1/Ingress` API.
While it is possible to deploy the ingress controller in an "operator compatible" manner, the new project is meant to function as a first class ingress controller and we strongly recommend migrating to the native functionality. This provides higher performance, stronger security guarantees, lower complexity, and reduced error opportunities compared to using a third party ingress integration via forward-auth.
See https://github.com/pomerium/pomerium-helm/tree/master/charts/pomerium#2500-1 for upgrade steps if you'd like to continue using forward-auth and a separate proxy.
Note: Beginning in Helm chart `v25.0.0`, the operator deployment has been replaced with Pomerium Ingress Controller.
# About
An operator for running Pomerium on a Kubernetes cluster.
pomerium-operator intends to be the way to automatically configure pomerium based on the state of Ingress, Service and CRD resources in the Kubernetes API Server. It has aspects of both an Operator and a Controller and in many ways functions as an add-on Ingress Controller.
## Initial discussion
https://github.com/pomerium/pomerium/issues/273
https://github.com/pomerium/pomerium/issues/425
# Installing
The pomerium operator should be installed with the pomerium helm chart at [https://helm.pomerium.io](https://helm.pomerium.io).
The operator may be run from outside the cluster for development or testing. In this case, it will use the default configuration at `~/.kube/config`, or you may specify a kubeconfig via the `KUBECONFIG` env var. Your current context from the config will be used in either case.
# Using
Due to current capabilities, the pomerium-operator is most useful when utilizing [forward auth](https://www.pomerium.io/configuration/#forward-auth). At this time, you must provide the appropriate annotations
for your ingress controller to have pomerium protect your endpoint. [Examples](https://www.pomerium.io/recipes/kubernetes.html) can be found in the pomerium documentation.
## How it works
With the operator installed on your cluster (typically via helm chart), it will begin watching `Ingress` and `Service` resources in all namespaces or the
namespace specified by the `namespace` flag. Following standard ingress controller behavior, pomerium-operator will respond only to resources that match
the configured `kubernetes.io/ingress.class` and `kubernetes.io/service.class` annotations, or resources without any annotation at all.
For a given matching resource, pomerium-operator will process all `ingress.pomerium.io/*` annotations and create a policy based on ingress `host` rules (`from` in pomerium policy) and `backend` service names (`to` in pomerium policy).
Annotations will apply to all rules defined by an ingress resource.
Services _must_ have an `ingress.pomerium.io/from` annotation or they will be ignored as invalid.
## Annotations
pomerium-operator uses a similar syntax for proxying to endpoints based on both Ingress and Service resources.
Policy is set by annotation, as are typical Ingress Controller semantics.
| Key | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| kubernetes.io/ingress.class | standard kubernetes ingress class |
| kubernetes.io/service.class | class for service control. effectively signals pomerium-operator to watch/configure this resource |
| pomerium.ingress.kubernetes.io/backend-protocol | set backend protocol to http or https. similar to nginx |
| ingress.pomerium.io/[policy_config_key] | policy_config_key is mapped to a policy configuration of the same name in yaml form. eg, ingress.pomerium.io/allowed_groups is mapped to allowed_groups in the policy block for all service targets in this Ingress. This value should be JSON format. |
## Example
```yaml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
annotations:
ingress.pomerium.io/allowed_domains: '["pomerium.io"]'
nginx.ingress.kubernetes.io/auth-signin: https://forwardauth.pomerium.io/?uri=$scheme://$host$request_uri
nginx.ingress.kubernetes.io/auth-url: https://forwardauth.pomerium.io/verify?uri=$scheme://$host$request_uri
labels:
app: grafana
chart: grafana-4.3.2
heritage: Tiller
release: prometheus
name: prometheus-grafana
spec:
rules:
- host: grafana.pomerium.io
http:
paths:
- backend:
serviceName: prometheus-grafana
servicePort: 80
path: /
```
This ingress:
1. Sets up external auth for nginx-ingress via the `nginx.ingress.kubernetes.io` annotations
2. Maps `grafana.pomerium.io` to the service at `prometheus-grafana`
3. Permits all users from domain `pomerium.io` to access this endpoint
The appropriate policy entry will be generated and injected into the pomerium config `Secret`:
```yaml
apiVersion: v1
stringData:
config.yaml: |
policy:
- from: https://grafana.pomerium.io
to: http://grafana.default.svc.cluster.local:80
allowed_domains:
- pomerium.io
```
# Development
## Building
pomerium-operator utilizes [go-task](https://taskfile.dev/#/) for development related tasks:
`task build`
# Roadmap
- [x] Basic CM update functionality. Provide enough functionality to implement the Forward Auth deployment model. Basically this is just policy updates being automated and compatible with the current helm chart.
- [ ] Introduce a mutating webhook that speaks the 3 forward auth dialects and annotates your Ingress for you. Maybe introduce this configuration via CRD.
- [ ] Get "table stakes" Ingress features into pomerium. Target model is Inverted Double Ingress or Simple Ingress. We need cert handling up to snuff, but load balancing and path based routing can be offloaded to a next-hop ingress controller or kube-proxy via Service. CRD maps which "next-hop" service to use for the IDI model from the ingress class.
- [ ] Introduce backend load balancing via Endpoint discovery to allow for skipping a second ingress for most configurations.
- [ ] Allow non-Ingress/Service based policy via CRD. Helm chart does conversion on the backend.
- [ ] Pomerium deployment itself is managed by CRD. The helm chart becomes a wrapper to this CRD. Move the templating and resource generation logic into pomerium-operator.