From 760428aa185180db9d78aae939dad08fadce1aff Mon Sep 17 00:00:00 2001 From: Jens Langhammer Date: Wed, 24 Nov 2021 10:58:23 +0100 Subject: [PATCH] website/docs: add outpost integrations docs Signed-off-by: Jens Langhammer --- Makefile | 2 +- website/docs/outposts/integrations/docker.md | 51 +++++++++++++++++++ .../docs/outposts/integrations/kubernetes.md | 46 +++++++++++++++++ website/docs/outposts/outposts.md | 14 +++-- website/sidebars.js | 8 +++ 5 files changed, 116 insertions(+), 5 deletions(-) create mode 100644 website/docs/outposts/integrations/docker.md create mode 100644 website/docs/outposts/integrations/kubernetes.md diff --git a/Makefile b/Makefile index 9809471ab..447c374a1 100644 --- a/Makefile +++ b/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 diff --git a/website/docs/outposts/integrations/docker.md b/website/docs/outposts/integrations/docker.md new file mode 100644 index 000000000..8c5a90b21 --- /dev/null +++ b/website/docs/outposts/integrations/docker.md @@ -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--router.rule`: `Host(...)` + - `traefik.http.routers.ak-outpost--router.service`: `ak-outpost--service` + - `traefik.http.routers.ak-outpost--router.tls`: "true" + - `traefik.http.services.ak-outpost--service.loadbalancer.healthcheck.path`: "/akprox/ping" + - `traefik.http.services.ak-outpost--service.loadbalancer.healthcheck.port`: "9300" + - `traefik.http.services.ak-outpost--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*. diff --git a/website/docs/outposts/integrations/kubernetes.md b/website/docs/outposts/integrations/kubernetes.md new file mode 100644 index 000000000..6d6a03d6f --- /dev/null +++ b/website/docs/outposts/integrations/kubernetes.md @@ -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. diff --git a/website/docs/outposts/outposts.md b/website/docs/outposts/outposts.md index 74dc51f9e..96d31f23e 100644 --- a/website/docs/outposts/outposts.md +++ b/website/docs/outposts/outposts.md @@ -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. diff --git a/website/sidebars.js b/website/sidebars.js index 516ab0bf6..7099cd2b2 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -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",