[v14] [docs] Add main documentation for Kubernetes Apps Discovery (#3…

…2076)

* Add main documentation for Kubernetes Apps Discovery

* Improve wording.

* Add internal link for annotation

* Improve wording.

Co-authored-by: Zac Bergquist <[email protected]>

* Remove unneeded symbol

Co-authored-by: Zac Bergquist <[email protected]>

* Improve wording.

Co-authored-by: Zac Bergquist <[email protected]>

* Make example cluster names consistent

* Restructure the Kubernetes app discovery guide (#31606)

- Move the docs to the Application Access section, since this material
  has to do with proxying applications via the Application Service.

- Split up the guide into separate guides for different documentation
  purposes: a how-to guide, configuration reference, and architecture
  guide.

- Fix linter/spelling issues

* Add not about running agent inside the Kuberentes cluster

* Add instruction how to enabled kube app discovery on existing installation

* Add example of configuration of teleport-kube-agent Helm chart

* convert tip to tabs

* fix wrong ref

---------

Co-authored-by: Zac Bergquist <[email protected]>
Co-authored-by: Paul Gottschling <[email protected]>
Co-authored-by: Tiago Silva <[email protected]>

docs/config.json

@@ -766,6 +766,24 @@
           "title": "Getting Started",
           "slug": "/application-access/getting-started/"
         },
+	{
+	    "title": "Enroll Kubernetes Applications",
+	    "slug": "/application-access/enroll-kubernetes-applications/",
+	    "entries":[
+		{
+		    "title": "Get Started",
+		    "slug": "/application-access/enroll-kubernetes-applications/get-started/"
+		},
+		{
+		    "title": "Architecture",
+		    "slug": "/application-access/enroll-kubernetes-applications/architecture/"
+		},
+		{
+		    "title": "Reference",
+		    "slug": "/application-access/enroll-kubernetes-applications/reference/"
+		}
+	    ]
+	},
         {
           "title": "Securing Cloud Provider APIs",
           "slug": "/application-access/cloud-apis/",

docs/cspell.json

@@ -74,7 +74,6 @@
     "Goland",
     "Grafana's",
     "Gtczk",
-    "highavailabilitycertmanageraddcommonname",
     "HKEY",
     "HSTS",
     "Hqlo",
@@ -148,7 +147,6 @@
     "Pbbd",
     "Pluggable",
     "Println",
-    "privateca",
     "Quickstart",
     "Quicktime's",
     "REDISCLI",
@@ -188,7 +186,6 @@
     "Tatham",
     "Tele",
     "Templating",
-    "tlsexistingcasecretname",
     "Tmkx",
     "Toboth",
     "Traefik",
@@ -431,6 +428,7 @@
     "healthz",
     "highavailability",
     "highavailabilitycertmanager",
+    "highavailabilitycertmanageraddcommonname",
     "hostcert",
     "hostdb",
     "hostedzone",
@@ -480,6 +478,7 @@
     "kubeconfig",
     "kubeconfigs",
     "kubectl",
+    "kubernetesdiscovery",
     "kvno",
     "lastname",
     "ldapsearch",
@@ -626,6 +625,7 @@
     "preconfigured",
     "prereqs",
     "prioritise",
+    "privateca",
     "privkey",
     "priya",
     "programatically",
@@ -741,6 +741,10 @@
     "teleportauditlogssofailed",
     "teleportblob",
     "teleportdemo",
+    "teleportdev",
+    "teleportdevdiscovery",
+    "teleportdevname",
+    "teleportdevprotocol",
     "teleporters",
     "teleportproxy",
     "teleportroles",
@@ -755,6 +759,7 @@
     "timechart",
     "tlscacerts",
     "tlscert",
+    "tlsexistingcasecretname",
     "tmpfs",
     "tocless",
     "tokenconfig",

docs/pages/application-access/enroll-kubernetes-applications.mdx

@@ -0,0 +1,26 @@
+---
+title: "Enroll Kubernetes Services as Teleport Applications"
+description: "Teleport can automatically detect applications running in your Kubernetes clusters and register them with Teleport for secure access."
+---
+
+Teleport can automatically detect applications running in your Kubernetes
+clusters and register them with your Teleport cluster. In this setup, users with
+Kubernetes-hosted infrastructure can configure secure access to any new
+applications they deploy with no need for manual intervention beyond the initial
+setup step.
+
+To enroll Kubernetes applications automatically, your Teleport cluster requires
+the Teleport Discovery Service and Teleport Application Service. The Teleport
+Discovery Service queries your Kubernetes clusters to detect running
+applications, and registers these applications with your cluster. The Teleport
+Application Service then detects the new application resources and proxies user
+traffic to them.
+
+- [Get started](./enroll-kubernetes-applications/get-started.mdx): Set up automatic
+  application discovery with the `teleport-kube-agent` Helm chart.
+- [Architecture](./enroll-kubernetes-applications/architecture.mdx): Learn how
+  automatic application discovery works.
+- [Reference](./enroll-kubernetes-applications/reference.mdx): Consult this guide
+  for options and Kubernetes annotations you can use to configure automatic
+  Kubernetes application discovery.
+

docs/pages/application-access/enroll-kubernetes-applications/architecture.mdx

@@ -0,0 +1,56 @@
+---
+title: Kubernetes App Discovery Architecture
+description: Learn how Teleport automatically discovers applications running on Kubernetes.
+---
+
+Kubernetes application auto-discovery consists of two parts:
+
+- Periodically polling list of services in a Kubernetes cluster
+- Creating Teleport apps based on that list and proxying requests to them.
+
+<Admonition type="note">
+  This will only work when the Teleport agent runs inside the target Kubernetes cluster
+</Admonition>
+
+### Polling Kubernetes services
+
+The Discovery Service running in a Kubernetes cluster will periodically list services and filter them out
+according to the matchers specified in `kubernetes` filed of the service config. You can filter services based on
+types, namespaces and service labels. All services by default currently 
+are considered of an "app" type, but it can be changed for a service by Kubernetes annotation [`teleport.dev/discovery-type`](./reference.mdx#teleportdevdiscovery-type).
+If type of a service doesn't equal the one specified in the matcher, service is ignored.
+
+By default name of the created Teleport app will consist of Kubernetes service name, namespace and 
+Kubernetes cluster name: `$SERVICE_NAME-$NAMESPACE-$KUBE_CLUSTER_NAME`. That name can be changed by Kubernetes annotation 
+[`teleport.dev/name`](./reference.mdx#teleportdevname).
+
+Every port that is exposed by the service is considered separately, so one Kubernetes service can result in creation of multiple Teleport app resources, 
+if more than one port is exposed on the service. In that case port name will be added to the app name.
+
+By default, the Discovery Service will only try to expose ports that serve HTTP/HTTPS. To understand if this port serves HTTP, discovery 
+will use several heuristics or will try to probe exposed port with a HEAD HTTP request.
+
+Heuristics for determining if port serves HTTP/HTTPS are:
+- if Kubernetes service port definition has `appProtocol` field, and it contains
+values `http`/`https` it will be used in the URI.
+- if exposed port's name is `https` or it has numeric value 443, `https` will be used.
+- Teleport will perform HTTP request to the port to see if it serves HTTP/HTTPS requests
+- if exposed port's name is `http` or it has numeric value 80 or 8080, `http` will be used.
+
+Otherwise, this port is ignored. But if annotation [`teleport.dev/protocol`](./reference.mdx#teleportdevprotocol) is used on the service and its value is
+"tcp", then this port will be exposed as a TCP app. 
+
+### Creating Teleport apps and proxying requests to them
+
+After relevant Kubernetes services were listed and filtered, the Discovery Service will create Teleport apps, reconciling
+existing and new ones: 
+- If a discovered app was not present at the Teleport backend, it will be created
+- If a discovered app was already present at the backend, it will be updated
+- If a discovered app was already present at the backend, but it was not found in the Kubernetes cluster anymore, it will be deleted.
+
+App service runs on the Kubernetes cluster and proxies apps based on labels specified in the `resources` field. All apps created by the
+Discovery Service will have labels copied from the service of origin. In addition, label `teleport.dev/kubernetes-cluster` will be set for
+the app and it will be equal to the name of the Kubernetes cluster of origin. Discovery service uses `discovery_group` property to get Kubernetes
+cluster name.
+
+

docs/pages/application-access/enroll-kubernetes-applications/get-started.mdx

@@ -0,0 +1,107 @@
+---
+title: Get Started with Kubernetes Application Discovery
+description: Detailed guide for configuring Kubernetes Application Discovery.
+---
+
+Teleport can automatically detect applications running in your Kubernetes
+clusters and register them with your Teleport cluster. In this setup, users with
+Kubernetes-hosted infrastructure can configure secure access to any new
+applications they deploy with no need for manual intervention beyond the initial
+setup step.
+
+In this guide, we show you how to enable Kubernetes application auto-discovery.
+
+## Prerequisites
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+- A Kubernetes cluster version >=
+  v(=kubernetes.major_version=).(=kubernetes.minor_version=).0
+
+- Helm >= (=helm.version=)
+
+  (!docs/pages/includes/helm.mdx!)
+
+- (!docs/pages/includes/tctl.mdx!)
+
+## Step 1/2. Create a join token
+
+Create a join token for a new Teleport agent that will run the Teleport
+Kubernetes Service, Application Service, and Discovery Service:
+
+```code
+$ tctl tokens add --type=kube,app,discovery
+```
+
+Enabling the `discovery` role by default will automatically start the discovery
+of Kubernetes services and registration of Teleport applications from them. And
+enabling `app` role on the chart will start the process of proxying all new
+Teleport applications created from discovered Kubernetes services.
+
+## Step 2/2. Deploy the agent
+
+If you want to install a new Teleport agent in your Kubernetes cluster, you can
+use the `teleport-kube-agent` Helm chart. If you already have a Teleport agent
+installed, you can upgrade it to enable the Kubernetes Application Discovery
+by adding the `kube`, `app`, and `discovery` to roles as shown below.
+
+<Tabs>
+<TabItem label="Install a new agent">
+
+Deploy a new Teleport agent running your configured services by installing the
+`teleport-kube-agent` Helm chart:
+
+```code
+$ helm install teleport-agent teleport/teleport-kube-agent \
+  --set roles=kube\,app\,discovery \
+  --set kubeClusterName=main-cluster \
+  --set proxyAddr=<Var name="proxy-address" /> \
+  --set authToken=<Var name="token" /> \
+  --create-namespace \
+  --namespace=teleport
+```
+
+</TabItem>
+
+<TabItem label="Upgrade an existing agent">
+
+If you want to have an existing `teleport-kube-agent` installation and want to enable
+Kubernetes App Discovery, you need to update the existing installation role to
+include `kube`, `app`, and `discovery` roles:
+
+```code
+$ helm upgrade teleport-agent teleport/teleport-kube-agent \
+  --reuse-values \
+  --set roles=kube\,app\,discovery \
+  --set authToken=<Var name="token" /> \
+  --namespace=teleport
+```
+</TabItem>
+
+</Tabs>
+
+## Troubleshooting
+
+First, make sure that all expected agents for the Teleport Discovery,
+Application, and Kubernetes Services are running. The token you created for them
+must have the required roles.
+
+If agents are running, but you don't see expected apps appearing in Teleport,
+there could be two main reasons:
+- The Teleport Discovery Service can't find relevant Kubernetes services.
+- The Teleport Application Service can't proxy discovered applications.
+
+Make sure that Kubernetes service account under which the Discovery Service is
+running has enough permissions to list the cluster's services. Also make sure
+that labels and namespaces configuration is correct.
+
+For the Application Service, make sure that labels in `resources` field are defined correctly, specifically that label
+`teleport.dev/kubernetes-cluster` matches `discovery_group` field of the Discovery Service running in the Kubernetes cluster.
+
+## Next steps
+
+You can configure the scope of the Discovery Service. For more information, see
+[`teleport-kube-agent` helm chart
+documentation](../../reference/helm-reference/teleport-kube-agent.mdx).
+
+

docs/pages/application-access/enroll-kubernetes-applications/reference.mdx

@@ -0,0 +1,114 @@
+---
+title: Reference
+description: This guide is a comprehensive reference of configuration options for automatically enrolling Kubernetes applications with Teleport.
+---
+
+## Configuring Teleport agent Helm chart
+
+You can configure scope of services discovery by setting value `kubernetesDiscovery` of the chart. For more information
+please see [helm chart documentation](../../reference/helm-reference/teleport-kube-agent.mdx#kubernetesdiscovery).
+
+`values.yaml` example:
+
+```yaml
+kubernetesDiscovery:
+- types: ["app"]
+  namespaces: [ "toronto", "porto" ]
+  labels:
+    env: staging
+- types: ["app"]
+  namespaces: [ "seattle", "oakland" ]
+  labels:
+    env: testing
+```
+
+## Configuring Kubernetes Apps Discovery manually
+
+While the `teleport-kube-agent` Helm chart will set up configuration for you
+automatically, you can also configure the required services manually. To do so,
+adjust the configuration files for the Teleport Application Service and Teleport
+Discovery Service, then restart the agents running these services.
+
+Configuration for the Discovery Service is controlled by the `kubernetes` field,
+example:
+
+```yaml
+# This section configures the Discovery Service
+discovery_service:
+  enabled: yes
+  discovery_group: main-cluster
+  kubernetes:
+  - types: ["app"]
+    namespaces: [ "toronto", "porto" ]
+    labels:
+      env: staging
+  - types: ["app"]
+    namespaces: [ "seattle", "oakland" ]
+    labels:
+      env: testing
+```
+
+Configuration for the Application Service is controlled by the `resources` field, example:
+
+```yaml
+app_service:
+  enabled: yes
+  resources:
+  - labels:
+    "teleport.dev/kubernetes-cluster": "main-cluster"
+    "teleport.dev/origin": "discovery-kubernetes"
+```
+
+Label `teleport.dev/kubernetes-cluster` should match value of `discovery_group` field in the Discovery Service config.
+
+For more information you can take a look at [`discovery_service`](../../reference/config.mdx#discovery-service) and [`app_service`](../../reference/config.mdx#application-service) configuration references.
+
+## Annotations
+
+Kubernetes annotations on services can be used to fine tune transformation of services to apps.
+All annotations are optional - they will override default behaviour, but they are not required for import of services.
+
+### `teleport.dev/discovery-type`
+
+Controls what type this service is considered to be. If annotation is missing,
+by default all services are considered to be of "app" type. If matchers in the Discovery Service
+config match service type it will be imported. Currently the only supported value is
+`app`, which means Teleport application will be imported from this service. In the future there are plans to expand to database importing.
+
+### `teleport.dev/protocol`
+
+Controls protocol for the uri of the Teleport app we create. If annotation is not set,
+heuristics will be used to try to determine protocol of an exposed port.
+If all heuristics didn't work, the port will be skipped. For app to be imported with `tcp` protocol, the
+service should have explicit annotation `teleport.dev/protocol: "tcp"`
+
+### `teleport.dev/port`
+
+Controls preferred port for the Kubernetes service, only this one will be used even if service
+has multiple exposed ports. Its value should be one of the exposed service ports; otherwise, the app will not be imported.
+Value can be matched either by numeric value or by the name of the port defined on the service.
+
+### `teleport.dev/name`
+
+Controls resulting app name. If present it will override default app name pattern
+`$SERVICE_NAME-$NAMESPACE-$KUBE_CLUSTER_NAME`. If multiple ports are exposed, resulting apps will have port names added
+as a suffix to the annotation value, as `$APP_NAME-$PORT1_NAME`, `$APP_NAME-$PORT2_NAME` etc, where `$APP_NAME` is the name
+set by the annotation.
+
+### `teleport.dev/app-rewrite`
+
+Controls rewrite configuration for Teleport app, if needed. It should
+contain full rewrite configuration in YAML format, same as one would put into `rewrite` config section of an
+app (see [documentation](../guides/connecting-apps.mdx#rewrite-redirect)).
+
+```yaml
+annotations:
+  teleport.dev/app-rewrite: |
+    redirect:
+    - "localhost"
+    - "jenkins.internal.dev"
+    headers:
+    - "X-Custom-Header: example"
+    - "Authorization: Bearer {{internal.jwt}}"
+```
+