feat: adjust sample to mvp (#1)

Reviewed-on: #1 Co-authored-by: Timo Behrendt <t.behrendt@t00n.de> Co-committed-by: Timo Behrendt <t.behrendt@t00n.de>
2026-05-17 14:39:46 +02:00
parent efe2b34116
commit bc8e7e10e1
54 changed files with 6697 additions and 24 deletions
@@ -2,4 +2,56 @@

 Authentik Kubernetes Operator allows to manage Authentik resources directly in Kubernetes using Custom Kubernetes Resources.

-## Features
+The custom resources of this operator ultimately will mirror the Authentik resources. New resources will be added as there is a need for them.
+
+Manual changes to the resources in Authentik will be overwritten by the operator. So always manage the resources in Kubernetes.
+
+## Custom Resources
+
+| Custom Resource | CRD File                                                   | Short Name |
+| --------------- | ---------------------------------------------------------- | ---------- |
+| ProxyProvider   | [`proxyProvider.yaml`](`artifacts/crd/proxyProvider.yaml`) | pp         |
+
+### ProxyProvider
+
+Currently only the "Forward Single" ProxyProvider is supported and only a reduced set of fields are exposed by the custom resources.
+
+Example [`proxyProvider.yaml`](`artifacts/examples/proxyProvider.yaml`):
+
+```yaml
+apiVersion: proxyprovider.t000-n.de/v1alpha1
+kind: ProxyProvider
+metadata:
+  name: proxy-provider-example
+  namespace: kube-system
+spec:
+  name: proxy-provider-example
+  # The ID of the authorization flow. In this example: "default-provider-authorization-implicit-consent (Authorize Application)"
+  authorization_flow: 16896c6d-b326-42d1-8d3f-93f32921962e
+  # The ID of the invalidation flow. In this example: "default-provider-invalidation-flow (Logged out of application)"
+  invalidation_flow: 7acac1ef-19e3-4a6f-8d8d-14ca7031d184
+  # The external host of your application.
+  external_host: https://example.t00n.de
+```
+
+The ProxyProvider will be created in Authentik, but will not be assigned to an outpost or an application (Resources are TBD).
+
+## Versioning
+
+As soon as the operator covers an entire use case, the version will be raised to v1 and follow default versioning rules. Before that, the version will be v1alpha1.
+
+## Development
+
+### Guidelines & Tips
+
+- Only do a single reconciliation at a time and then return.
+  - This is because your references from the k8s API get stale after each update.
+  - Whenever you update a resource, k8s API will send a new event to your controller, which will trigger a new reconciliation.
+- The API will periodically send a resource to the controller for re-syncing, giving the controller a chance to reconcile the state with the outside world.
+- Use finalizers to ensure that the controller gets a chance to reconcile the state with the outside world before the object is deleted. If no finalizer is present, the object is deleted immediately without the controller seeing it.
+- Use the resource's state to keep track of the current state of the outside world, e.g. identifiers of external resources, etc.
+
+### References
+
+- [Extend Kubernetes](https://kubernetes.io/docs/concepts/extend-kubernetes/#api-extensions)
+- [Example Controller Implementation](https://github.com/kubernetes/sample-controller)