{"id":13689292,"url":"https://github.com/pomerium/pomerium-operator","last_synced_at":"2025-05-01T23:33:37.838Z","repository":{"id":39879439,"uuid":"221198331","full_name":"pomerium/pomerium-operator","owner":"pomerium","description":"An operator for running Pomerium on a Kubernetes cluster.","archived":true,"fork":false,"pushed_at":"2022-05-23T18:37:38.000Z","size":333,"stargazers_count":28,"open_issues_count":0,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-08-03T15:16:53.474Z","etag":null,"topics":["beyondcorp","cloud-native","go","helm-chart","identity","kubernetes","kubernetes-operator","pomerium","zero-trust"],"latest_commit_sha":null,"homepage":"https://www.pomerium.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pomerium.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}},"created_at":"2019-11-12T11:09:21.000Z","updated_at":"2023-11-07T12:52:56.000Z","dependencies_parsed_at":"2022-08-28T02:01:12.269Z","dependency_job_id":null,"html_url":"https://github.com/pomerium/pomerium-operator","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pomerium%2Fpomerium-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pomerium%2Fpomerium-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pomerium%2Fpomerium-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pomerium%2Fpomerium-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pomerium","download_url":"https://codeload.github.com/pomerium/pomerium-operator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224282215,"owners_count":17285793,"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":["beyondcorp","cloud-native","go","helm-chart","identity","kubernetes","kubernetes-operator","pomerium","zero-trust"],"created_at":"2024-08-02T15:01:41.629Z","updated_at":"2024-11-12T13:31:23.651Z","avatar_url":"https://github.com/pomerium.png","language":"Go","funding_links":[],"categories":["go"],"sub_categories":[],"readme":"[![pomerium chat](https://img.shields.io/badge/chat-on%20slack-blue.svg?style=flat\u0026logo=slack)](http://slack.pomerium.io)\n![Build Status](https://img.shields.io/github/workflow/status/pomerium/pomerium-operator/Default)\n[![Go Report Card](https://goreportcard.com/badge/github.com/pomerium/pomerium-operator)](https://goreportcard.com/report/github.com/pomerium/pomerium-operator)\n[![Maintainability](https://api.codeclimate.com/v1/badges/df5235a61ea57d8816fc/maintainability)](https://codeclimate.com/github/pomerium/pomerium-operator/maintainability)\n[![Documentation](https://godoc.org/github.com/pomerium/pomerium-operator?status.svg)](http://godoc.org/github.com/pomerium/pomerium-operator)\n[![LICENSE](https://img.shields.io/github/license/pomerium/pomerium-operator.svg)](https://github.com/pomerium/pomerium-operator/blob/master/LICENSE)\n[![codecov](https://img.shields.io/codecov/c/github/pomerium/pomerium-operator.svg?style=flat)](https://codecov.io/gh/pomerium/pomerium-operator)\n![Docker Pulls](https://img.shields.io/docker/pulls/pomerium/pomerium-operator)\n\n- [:warning: Deprecation Notice](#warning-deprecation-notice)\n- [About](#about)\n  - [Initial discussion](#initial-discussion)\n- [Installing](#installing)\n- [Using](#using)\n  - [How it works](#how-it-works)\n  - [Annotations](#annotations)\n  - [Example](#example)\n- [Development](#development)\n  - [Building](#building)\n- [Roadmap](#roadmap)\n\n# :warning: Deprecation Notice\n\nWe've just released a new Ingress Controller (docs [here](https://www.pomerium.com/docs/k8s/ingress.html)), which supersedes the operator.\n\n[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.\n\nAs 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.\n\nWhile 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.\n\nSee 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.\n\nNote: Beginning in Helm chart `v25.0.0`, the operator deployment has been replaced with Pomerium Ingress Controller.\n# About\n\nAn operator for running Pomerium on a Kubernetes cluster.\n\npomerium-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.\n\n## Initial discussion \nhttps://github.com/pomerium/pomerium/issues/273\n\nhttps://github.com/pomerium/pomerium/issues/425\n\n# Installing\nThe pomerium operator should be installed with the pomerium helm chart at [https://helm.pomerium.io](https://helm.pomerium.io).\n\nThe 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.\n\n\n# Using\n\nDue 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\nfor your ingress controller to have pomerium protect your endpoint.  [Examples](https://www.pomerium.io/recipes/kubernetes.html) can be found in the pomerium documentation.\n\n## How it works\n\nWith the operator installed on your cluster (typically via helm chart), it will begin watching `Ingress` and `Service` resources in all namespaces or the\nnamespace specified by the `namespace` flag.  Following standard ingress controller behavior, pomerium-operator will respond only to resources that match \nthe configured `kubernetes.io/ingress.class` and `kubernetes.io/service.class` annotations, or resources without any annotation at all.  \n\nFor 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).  \n\nAnnotations will apply to all rules defined by an ingress resource.\n\nServices _must_ have an `ingress.pomerium.io/from` annotation or they will be ignored as invalid.\n\n## Annotations\n\npomerium-operator uses a similar syntax for proxying to endpoints based on both Ingress and Service resources.\n\nPolicy is set by annotation, as are typical Ingress Controller semantics.\n\n| Key                                             | Description                                                                                                                                                                                                                                            |\n| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| kubernetes.io/ingress.class                     | standard kubernetes ingress class                                                                                                                                                                                                                      |\n| kubernetes.io/service.class                     | class for service control. effectively signals pomerium-operator to watch/configure this resource                                                                                                                                                      |\n| pomerium.ingress.kubernetes.io/backend-protocol | set backend protocol to http or https. similar to nginx                                                                                                                                                                                                |\n| 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. |\n\n## Example\n\n```yaml\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n  annotations:\n    ingress.pomerium.io/allowed_domains: '[\"pomerium.io\"]'\n    nginx.ingress.kubernetes.io/auth-signin: https://forwardauth.pomerium.io/?uri=$scheme://$host$request_uri\n    nginx.ingress.kubernetes.io/auth-url: https://forwardauth.pomerium.io/verify?uri=$scheme://$host$request_uri\n  labels:\n    app: grafana\n    chart: grafana-4.3.2\n    heritage: Tiller\n    release: prometheus\n  name: prometheus-grafana\nspec:\n  rules:\n  - host: grafana.pomerium.io\n    http:\n      paths:\n      - backend:\n          serviceName: prometheus-grafana\n          servicePort: 80\n        path: /\n```\n\nThis ingress:\n\n1. Sets up external auth for nginx-ingress via the `nginx.ingress.kubernetes.io` annotations\n2. Maps `grafana.pomerium.io` to the service at `prometheus-grafana`\n3. Permits all users from domain `pomerium.io` to access this endpoint\n\nThe appropriate policy entry will be generated and injected into the pomerium config `Secret`:\n\n```yaml\napiVersion: v1\nstringData:\n  config.yaml: |\n    policy:\n    - from: https://grafana.pomerium.io\n      to: http://grafana.default.svc.cluster.local:80\n      allowed_domains:\n       - pomerium.io\n```\n\n# Development\n\n## Building\npomerium-operator utilizes [go-task](https://taskfile.dev/#/) for development related tasks:  \n\n`task build`\n\n# Roadmap \n\n- [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.  \n\n- [ ] Introduce a mutating webhook that speaks the 3 forward auth dialects and annotates your Ingress for you.  Maybe introduce this configuration via CRD.\n\n- [ ] 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.\n\n- [ ]  Introduce backend load balancing via Endpoint discovery to allow for skipping a second ingress for most configurations.\n\n- [ ]  Allow non-Ingress/Service based policy via CRD.  Helm chart does conversion on the backend.\n\n- [ ]  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.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpomerium%2Fpomerium-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpomerium%2Fpomerium-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpomerium%2Fpomerium-operator/lists"}