website/docs: add outpost integrations docs
Signed-off-by: Jens Langhammer <jens.langhammer@beryju.org>
This commit is contained in:
Jens Langhammer
parent
49bbac7441
commit
760428aa18
2
Makefile
2
Makefile
|
|
@ -10,7 +10,7 @@ test-integration:
|
|||
coverage run manage.py test tests/integration
|
||||
|
||||
test-e2e:
|
||||
coverage run manage.py test --failfast tests/e2e
|
||||
coverage run manage.py test tests/e2e
|
||||
|
||||
test:
|
||||
coverage run manage.py test authentik
|
||||
|
|
|
|||
51
website/docs/outposts/integrations/docker.md
Normal file
51
website/docs/outposts/integrations/docker.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
title: Docker
|
||||
---
|
||||
|
||||
The docker integration will automatically deploy and manage outpost containers using the Docker HTTP API.
|
||||
|
||||
This integration has the advantage over manual deployments of automatic updates (whenever authentik is updated, it updates the outposts), and authentik can (in a future version) automatically rotate the token that the outpost uses to communicate with the core authentik server.
|
||||
|
||||
The following outpost settings are used:
|
||||
|
||||
- `object_naming_template`: Configures how the container is called
|
||||
- `container_image`: Optionally overwrites the standard container image (see [Configuration](../../installation/configuration.md) to configure the global default)
|
||||
- `docker_network`: The docker network the container should be added to. This needs to be modified if you plan to connect to authentik using the internal hostname.
|
||||
- `docker_map_ports`: Enable/disable the mapping of ports. When using a proxy outpost with traefik for example, you might not want to bind ports as they are routed through traefik.
|
||||
|
||||
The container is created with the following hardcoded properties:
|
||||
|
||||
- Labels
|
||||
|
||||
- `io.goauthentik.outpost-uuid`: Used by authentik to identify the container, and to allow for name changes.
|
||||
|
||||
Additionally, the proxy outposts have the following extra labels to add themselves into traefik automatically.
|
||||
|
||||
- `traefik.enable`: "true"
|
||||
- `traefik.http.routers.ak-outpost-<outpost-id>-router.rule`: `Host(...)`
|
||||
- `traefik.http.routers.ak-outpost-<outpost-id>-router.service`: `ak-outpost-<outpost-id>-service`
|
||||
- `traefik.http.routers.ak-outpost-<outpost-id>-router.tls`: "true"
|
||||
- `traefik.http.services.ak-outpost-<outpost-id>-service.loadbalancer.healthcheck.path`: "/akprox/ping"
|
||||
- `traefik.http.services.ak-outpost-<outpost-id>-service.loadbalancer.healthcheck.port`: "9300"
|
||||
- `traefik.http.services.ak-outpost-<outpost-id>-service.loadbalancer.server.port`: "9000"
|
||||
|
||||
## Permissions
|
||||
|
||||
To minimise the potential risks of mapping the docker socket into a container/giving an application access to the docker API, many people use Projects like [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy). authentik requires these permissions from the docker API:
|
||||
|
||||
- Images/Pull: authentik tries to pre-pull the custom image if one is configured, otherwise falling back to the default image.
|
||||
- Containers/Read: Gather infos about currently running container
|
||||
- Containers/Create: Create new containers
|
||||
- Containers/Kill: Cleanup during upgrades
|
||||
- Containers/Remove: Removal of outposts
|
||||
|
||||
## Remote hosts
|
||||
|
||||
To connect remote hosts, you can follow this Guide from Docker [Use TLS (HTTPS) to protect the Docker daemon socket](https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket) to configure Docker.
|
||||
|
||||
Afterwards, create two Certificate-keypairs in authentik:
|
||||
|
||||
- `Docker CA`, with the contents of `~/.docker/ca.pem` as Certificate
|
||||
- `Docker Cert`, with the contents of `~/.docker/cert.pem` as Certificate and `~/.docker/key.pem` as Private key.
|
||||
|
||||
Create an integration with `Docker CA` as *TLS Verification Certificate* and `Docker Cert` as *TLS Authentication Certificate*.
|
||||
46
website/docs/outposts/integrations/kubernetes.md
Normal file
46
website/docs/outposts/integrations/kubernetes.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
title: Kubernetes
|
||||
---
|
||||
|
||||
The kubernetes integration with automatically deploy outposts on any Kubernetes Cluster.
|
||||
|
||||
This integration has the advantage over manual deployments of automatic updates (whenever authentik is updated, it updates the outposts), and authentik can (in a future version) automatically rotate the token that the outpost uses to communicate with the core authentik server.
|
||||
|
||||
This integration creates the following objects:
|
||||
|
||||
- Deployment for the outpost container
|
||||
- Service
|
||||
- Secret to store the token
|
||||
- Prometheus ServiceMonitor (if the Prometheus Operator is installed in the target cluster)
|
||||
- Ingress (only Proxy outposts)
|
||||
- Traefik Middleware (only Proxy outposts with forward auth enabled)
|
||||
|
||||
The following outpost settings are used:
|
||||
|
||||
- `object_naming_template`: Configures how the container is called
|
||||
- `container_image`: Optionally overwrites the standard container image (see [Configuration](../../installation/configuration.md) to configure the global default)
|
||||
- `kubernetes_replicas`: Replica count for the deployment of the outpost
|
||||
- `kubernetes_namespace`: Namespace to deploy in, defaults to the same namespace authentik is deployed in (if available)
|
||||
- `kubernetes_ingress_annotations`: Any additional annotations to add to the ingress object, for example cert-manager
|
||||
- `kubernetes_ingress_secret_name`: Name of the secret that is used for TLS connections
|
||||
- `kubernetes_service_type`: Service kind created, can be set to LoadBalancer for LDAP outposts for example
|
||||
- `kubernetes_disabled_components`: Disable any components of the kubernetes integration, can be any of
|
||||
- 'secret'
|
||||
- 'deployment'
|
||||
- 'service'
|
||||
- 'prometheus servicemonitor'
|
||||
- 'ingress'
|
||||
- 'traefik middleware'
|
||||
- `kubernetes_image_pull_secrets`: If the above docker image is in a private repository, use these secrets to pull.
|
||||
|
||||
NOTE: The secret must be created manually in the namespace first.
|
||||
|
||||
## Permissions
|
||||
|
||||
The permissions required for this integration are documented in the helm chart, see [Cluster-level](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/cluster-role-binding.yaml) and [Namespace-level](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/role-binding.yaml).
|
||||
|
||||
## Remote clusters
|
||||
|
||||
To add a remote cluster, you can simply install this helm chart in the target cluster and namespace: https://artifacthub.io/packages/helm/goauthentik/authentik-remote-cluster
|
||||
|
||||
After installation, the helm chart outposts an example kubeconfig file, that you can enter in authentik to connect to the cluster.
|
||||
|
|
@ -8,12 +8,12 @@ An outpost is a single deployment of a authentik component, which can be deploye
|
|||
|
||||
Upon creation, a service account and a token is generated. The service account only has permissions to read the outpost and provider configuration. This token is used by the Outpost to connect to authentik.
|
||||
|
||||
authentik can manage the deployment, updating and general lifecycle of an Outpost. To communicate with the underlying platforms on which the outpost is deployed, authentik has "Service Connections".
|
||||
authentik can manage the deployment, updating and general lifecycle of an Outpost. To communicate with the underlying platforms on which the outpost is deployed, authentik has several built-in integrations.
|
||||
|
||||
- If you've deployed authentik on docker-compose, authentik automatically creates a Service Connection for the local docker socket.
|
||||
- If you've deployed authentik on Kubernetes, with `kubernetesIntegration` set to true (default), authentik automatically creates a Service Connection for the local Kubernetes Cluster.
|
||||
- If you've deployed authentik on docker-compose, authentik automatically creates an integration for the local docker socket (See [Docker](./integrations/docker.md)).
|
||||
- If you've deployed authentik on Kubernetes, with `kubernetesIntegration` set to true (default), authentik automatically creates an integrations for the local Kubernetes Cluster (See [Kubernetes](./integrations/kubernetes.md)).
|
||||
|
||||
To deploy an outpost with these service connections, simply select them during the creation of an Outpost. A background task is started, which creates the container/deployment. You can see that Status on the System Tasks page.
|
||||
To deploy an outpost with these integrations, simply select them during the creation of an Outpost. A background task is started, which creates the container/deployment. You can see that Status on the System Tasks page.
|
||||
|
||||
To deploy an outpost manually, see:
|
||||
|
||||
|
|
@ -77,3 +77,9 @@ kubernetes_disabled_components: []
|
|||
# NOTE: The secret must be created manually in the namespace first.
|
||||
kubernetes_image_pull_secrets: []
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
Each authentik outpost has a Prometheus metrics endpoint accessible under port `:9300/metrics`. This endpoint is not mapped via docker, as the endpoint doesn't have any authentication.
|
||||
|
||||
For the embedded outpost, the metrics of the outpost and the metrics of the core authentik server are both returned under the same endpoint.
|
||||
|
|
|
|||
|
|
@ -49,6 +49,14 @@ module.exports = {
|
|||
items: [
|
||||
"outposts/outposts",
|
||||
"outposts/embedded/embedded",
|
||||
{
|
||||
type: "category",
|
||||
label: "Integrations",
|
||||
items: [
|
||||
"outposts/integrations/docker",
|
||||
"outposts/integrations/kubernetes",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Running and upgrading",
|
||||
|
|
|
|||
Reference in a new issue