t.behrendt
2f46a10388
CI / install-dependencies (pull_request) Successful in 22s
CI / image check (pull_request) Failing after 7s
CI / check lint (pull_request) Successful in 26s
CI / test (pull_request) Successful in 22s
CI / check format (pull_request) Successful in 1m31s
CI / build check (pull_request) Successful in 14m44s
100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
# authentik-kubernetes-operator
|
|
|
|
Authentik Kubernetes Operator allows to manage Authentik resources directly in Kubernetes using Custom Kubernetes Resources.
|
|
|
|
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 |
|
|
| Application | [`application.yaml`](`artifacts/crd/application.yaml`) | app |
|
|
| PolicyBinding | [`policyBinding.yaml`](`artifacts/crd/policyBinding.yaml`) | pb |
|
|
|
|
### 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 ID of the outpost, which at current point in time can only be retrieved from Authentik directly. In this example: "Proxy-Forward-Auth-Auto"
|
|
outpost: e004ffe7-4af6-4ac1-9e9d-522354799e1f
|
|
```
|
|
|
|
The ProxyProvider will be created in Authentik and assigned to the configured outpost.
|
|
|
|
### Application
|
|
|
|
The Application only supports a reduced set of fields.
|
|
|
|
Example [`application.yaml`](`artifacts/examples/application.yaml`):
|
|
|
|
```yaml
|
|
apiVersion: application.t000-n.de/v1alpha1
|
|
kind: Application
|
|
metadata:
|
|
name: application-example
|
|
spec:
|
|
name: Application Example
|
|
slug: application-example
|
|
# The ID of the provider, which can be retrieved from e.g. the ProxyPRovider via "kubectl get pp proxy-provider-example -o jsonpath='{.status.pk}'"
|
|
provider: 105
|
|
```
|
|
|
|
### PolicyBinding
|
|
|
|
The PolicyBinding is used to bind a policy to a target, e.g. allow a group or user to access an application.
|
|
The PolicyBinding only supports a reduced set of fields.
|
|
|
|
Example [`policyBinding.yaml`](`artifacts/examples/policyBinding.yaml`):
|
|
|
|
```yaml
|
|
apiVersion: policybinding.t000-n.de/v1alpha1
|
|
kind: PolicyBinding
|
|
metadata:
|
|
name: policy-binding-example
|
|
spec:
|
|
group: 14ab813f-a7f9-481b-9b08-781953ae9ebf
|
|
# The ID of the target, e.g. an Application, which can be retrieved from e.g. the Application via "kubectl get app application-example -o jsonpath='{.status.pk}'"
|
|
target: 8dd85627-9c48-49c2-8afc-d73dd122ffc2
|
|
# The order in which the policy is applied. This needs to be unique for each PolicyBinding.
|
|
order: 1
|
|
```
|
|
|
|
## 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)
|