website/docs: clean up Kubernetes outpost integration page (#21587)

Author: dominic-r

website/docs/add-secure-apps/outposts/integrations/kubernetes.md

@@ -2,51 +2,71 @@
 title: Kubernetes
 ---
 
-The kubernetes integration will 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 for protocol access
-- Service for metrics access
-- Secret to store the token
-- Prometheus ServiceMonitor (if the Prometheus Operator is installed in the target cluster)
-- Ingress (only Proxy outposts)
-- HTTPRoute (only Proxy outposts, when the Gateway API resources are installed in the target cluster, and the `kubernetes_httproute_parent_refs` setting is set, see below)
-- 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](../../../install-config/configuration/configuration.mdx) 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, can be empty to disable TLS config
-- `kubernetes_ingress_class_name`: Optionally set the ingress class used for the generated ingress, requires authentik 2022.11.0
-- `kubernetes_httproute_parent_refs`: Define which Gateways the HTTPRoute wants to be attached to.
-- `kubernetes_httproute_annotations`: Any additional annotations to add to the HTTPRoute object
-- `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'
-    - 'service-metrics'
-    - 'prometheus servicemonitor'
-    - 'ingress'
-    - 'traefik middleware'
-    - 'httproute'
-- `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.)
-- `kubernetes_json_patches`: Applies an RFC 6902 compliant JSON patch to the Kubernetes objects.
+The Kubernetes integration automatically deploys and manages outposts in a Kubernetes cluster.
+
+Compared with a [manual Kubernetes deployment](../manual-deploy-kubernetes.md), this integration keeps managed outposts aligned with authentik updates and reduces the amount of cluster-side configuration that you need to maintain.
+
+## Created resources
+
+This integration creates the following Kubernetes resources:
+
+- A `Deployment` for the outpost container.
+- A `Service` for protocol traffic.
+- A `Service` for metrics traffic.
+- A `Secret` that stores the outpost token.
+- A `ServiceMonitor` if the Prometheus Operator is installed in the target cluster.
+- An `Ingress` for proxy outposts.
+- An `HTTPRoute` for proxy outposts if Gateway API resources are installed in the target cluster and `kubernetes_httproute_parent_refs` is configured.
+- A Traefik `Middleware` resource for proxy outposts that use forward auth.
+
+## Supported settings
+
+These settings control how authentik creates and manages Kubernetes resources. For the full shared outpost configuration reference, see [Outposts configuration](../index.mdx#configuration).
+
+### General settings
+
+- `object_naming_template`: Configures the names of created Kubernetes resources.
+- `container_image`: Overrides the default outpost image. You can also configure the global default in [Configuration](../../../install-config/configuration/configuration.mdx#authentik_outposts).
+- `kubernetes_replicas`: Sets the number of replicas in the generated deployment.
+- `kubernetes_namespace`: Sets the namespace where authentik deploys the outpost. By default, this uses the namespace where authentik is installed, if available.
+- `kubernetes_service_type`: Sets the generated Service type, for example `ClusterIP` or `LoadBalancer`.
+- `kubernetes_image_pull_secrets`: Uses existing image pull secrets for private registries. Create these secrets in the target namespace before you use this setting.
+- `kubernetes_json_patches`: Applies [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) JSON patches to generated Kubernetes objects.
+
+### Ingress settings
+
+- `kubernetes_ingress_annotations`: Adds annotations to the generated Ingress, for example for cert-manager.
+- `kubernetes_ingress_secret_name`: Sets the TLS secret name for the generated Ingress. Leave this empty to disable TLS configuration on the Ingress.
+- `kubernetes_ingress_class_name`: Sets the ingress class for the generated Ingress.
+- `kubernetes_ingress_path_type`: Sets the Ingress `pathType`. If unset, authentik uses the controller default.
+
+### Gateway API settings
+
+- `kubernetes_httproute_parent_refs`: Defines which Gateway resources the generated `HTTPRoute` attaches to.
+- `kubernetes_httproute_annotations`: Adds annotations to the generated `HTTPRoute`.
+
+### Disabled components
+
+Use `kubernetes_disabled_components` to prevent authentik from creating specific resources. Supported values are:
+
+- `secret`
+- `deployment`
+- `service`
+- `service-metrics`
+- `prometheus servicemonitor`
+- `ingress`
+- `traefik middleware`
+- `httproute`
 
 ## 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/clusterrolebinding.yaml) and [Namespace-level](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/rolebinding.yaml).
+The required permissions for this integration are documented in the Helm chart:
+
+- [Cluster-level permissions](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/clusterrolebinding.yaml)
+- [Namespace-level permissions](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/rolebinding.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
+To connect a remote cluster, install the [`authentik-remote-cluster` Helm chart](https://artifacthub.io/packages/helm/goauthentik/authentik-remote-cluster) in the target cluster and namespace.
 
-After installation, the helm chart outputs an example kubeconfig file, that you can enter in authentik to connect to the cluster.
+After installation, the chart outputs an example kubeconfig file. Add that kubeconfig to authentik to connect to the cluster.