diff --git a/docs/config.json b/docs/config.json index d57ae33b2a23d..afe25b61a547c 100644 --- a/docs/config.json +++ b/docs/config.json @@ -321,14 +321,18 @@ { "title": "Getting Started", "slug": "/kubernetes-access/getting-started/", - "entries": [ - { - "title": "Cluster", - "slug": "/kubernetes-access/getting-started/cluster/" - }, - { - "title": "Agent", - "slug": "/kubernetes-access/getting-started/agent/" + "entries": [ + { + "title": "Local Demo Cluster", + "slug": "/kubernetes-access/getting-started/local/" + }, + { + "title": "Cluster", + "slug": "/kubernetes-access/getting-started/cluster/" + }, + { + "title": "Agent", + "slug": "/kubernetes-access/getting-started/agent/" } ] }, diff --git a/docs/img/connected-app.png b/docs/img/connected-app.png new file mode 100644 index 0000000000000..17e0a9083be03 Binary files /dev/null and b/docs/img/connected-app.png differ diff --git a/docs/pages/getting-started.mdx b/docs/pages/getting-started.mdx index f1fc2951e082a..1be9501b5e4e0 100644 --- a/docs/pages/getting-started.mdx +++ b/docs/pages/getting-started.mdx @@ -11,7 +11,7 @@ layout: tocless-doc Try Teleport locally using Docker Compose. - + Get started with Teleport and Kubernetes. diff --git a/docs/pages/kubernetes-access/getting-started.mdx b/docs/pages/kubernetes-access/getting-started.mdx index 1456dea2f9acc..bc57dd10edead 100644 --- a/docs/pages/kubernetes-access/getting-started.mdx +++ b/docs/pages/kubernetes-access/getting-started.mdx @@ -6,6 +6,10 @@ layout: tocless-doc --- + + ![Teleport ](../../img/k8s/mini-diagrams/teleport-in-k8s-mono.svg) + Quickly see how Teleport works with Kubernetes on your laptop. + ![Teleport ](../../img/k8s/mini-diagrams/teleport-in-k8s-mono.svg) Deploy a standalone Teleport cluster in a Kubernetes cluster. diff --git a/docs/pages/kubernetes-access/getting-started/local.mdx b/docs/pages/kubernetes-access/getting-started/local.mdx new file mode 100644 index 0000000000000..09e86c43e3a0d --- /dev/null +++ b/docs/pages/kubernetes-access/getting-started/local.mdx @@ -0,0 +1,349 @@ +--- +title: Try Teleport on a Local Kubernetes Cluster +description: Use this local demo to get started with Teleport on Kubernetes in 10 minutes. +--- + +In this guide, we will show you how to set up Teleport on a local Kubernetes +cluster. You will see how Teleport enables users to access private resources in +your cluster—all from a single ingress port—so you can manage authentication, +authorization, and audit. + +## The demo environment + +Our demo will run using minikube, which deploys Kubernetes on your local +machine. The cluster will run the official dashboard UI for Kubernetes. + +While it is possible to expose the dashboard outside the cluster using the +`kubectl proxy` command, in our demo the dashboard will only be accessible via +Teleport. + +The **Teleport Auth Service** is the certificate authority for your cluster. It +issues certificates and conducts authentication challenges. The **Teleport Proxy +Service** is the cluster frontend, and handles user requests, forwards user +credentials to the Auth Service, and communicates with other Teleport +instances—called **Nodes**—that enable access to your infrastructure. + +In our demo, one Node is a pod that runs Teleport's Application Service to +enable access to Kubernetes Dashboard for authorized end-users. A second pod +runs the Teleport Auth Service and Proxy Service. + +## Prerequisites + +While this guide deploys resources only on your local development machine, you +will need access to the Internet in order to pull Helm charts and container +images. + +Make sure that the following tools are installed locally: + +|Tool|Purpose|Installation link| +|---|---|---| +|minikube|Local Kubernetes deployment tool|[Install minikube](https://minikube.sigs.k8s.io/docs/start/)| +|Helm|Kubernetes package manager|[Install Helm](https://helm.sh/docs/intro/install/)| +|kubectl|Kubernetes admin CLI|[Install kubectl](https://kubernetes.io/docs/tasks/tools/)| + +To run minikube, you will need to install a supported driver, i.e., a local +virtualization or isolation environment that can run the cluster. + +Docker Desktop is a good cross-platform solution, and the one we will assume you +are using in this guide. You can read about all supported platforms here: + +[Drivers](https://minikube.sigs.k8s.io/docs/drivers/) + +You should also install a one-time passcode (OTP) application like Authy on your +mobile device. You will use this to authenticate to your Teleport cluster. + +## Step 1/4 Deploy resources + +### Start minikube + +Start minikube with the default driver: + +```code +$ minikube start +``` + +Add the Teleport Helm repository. Our Helm charts make it easier to deploy +Teleport on your local Kubernetes cluster: + +```code +$ helm repo add teleport https://charts.releases.teleport.dev +``` + +### Install the Teleport Auth Service and Proxy Service + +You will deploy the Auth Service and Proxy Service by installing the +`teleport-cluster` Helm chart. To do so, run the following commands: + +```code +# This is the DNS name Kubernetes will assign to the Proxy Service +$ CLUSTER_NAME="teleport-cluster.teleport-cluster.svc.cluster.local" +$ helm install teleport-cluster teleport/teleport-cluster --create-namespace --namespace=teleport-cluster --set clusterName=${CLUSTER_NAME?} +$ kubectl config set-context --current --namespace teleport-cluster +``` + +Any `kubectl` commands you run will now use the `teleport-cluster` namespace. + +Verify that Teleport is running. + +```code +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +teleport-cluster-b9dc6c68b-d75fb 1/1 Running 0 46s +``` + +### Configure DNS + +For the Proxy Service to communicate with end-users and Teleport Nodes, it needs +a domain name that is resolvable both inside and outside your Kubernetes +cluster. + +Production Teleport deployments achieve this by either using a registered domain +name or an internal DNS infrastructure. For this demonstration, we will +edit the `/etc/hosts` file instead. + + +Set yourself a reminder to clean up your `/etc/hosts` +file when you are done with this guide. + + +Append the following to your `/etc/hosts` file: + +``` +127.0.0.1 teleport-cluster.teleport-cluster.svc.cluster.local kube-dash.teleport-cluster.teleport-cluster.svc.cluster.local +``` + +`teleport-cluster.teleport-cluster.svc.cluster.local` is the DNS name that +Kubernetes assigns to the Proxy Service. As you complete this guide, the +Application Service will make Kubernetes Dashboard available at the +`kube-dash` subdomain of the Proxy Service's domain name. + + +### Expose the Proxy Service to your local machine + +The `teleport-cluster` service is of type `LoadBalancer`, meaning that your +platform needs to supply a load balancer to route traffic to the service. + +The `minikube tunnel` command provides a load balancer and establishes a reverse +SSH tunnel to ports on your local machine. + +Open a new terminal and run the following command to create a reverse tunnel. In +this case, the tunnel forwards port 443, so you will need to enter your +password. + +```code +$ minikube tunnel +✅ Tunnel successfully started + +📌 NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ... + +❗ The service/ingress teleport-cluster requires privileged ports to be exposed: [443] +🔑 sudo permission will be asked for it. +🏃 Starting tunnel for service teleport-cluster. +Password: +``` + +The `teleport-cluster` service should now have an external IP: + +```code +$ kubectl get services +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +teleport-cluster LoadBalancer 10.107.218.212 127.0.0.1 443:32143/TCP,3023:30618/TCP,3026:32750/TCP,3024:32406/TCP,3036:30687/TCP 6m18s +``` + +The Proxy Service enables you to manage your cluster via an HTTP API. Verify +that this is working: + +``` +$ curl --insecure https://localhost:443/webapi/ping +{"auth":{"type":"local","second_factor":"otp","preferred_local_mfa":"otp","has_motd":false},"proxy":{"kube":{"enabled":true,"listen_addr":"0.0.0.0:3026"},"ssh":{"listen_addr":"[::]:3023","tunnel_listen_addr":"0.0.0.0:3024","public_addr":"teleport-cluster:443"},"db":{"mysql_listen_addr":"0.0.0.0:3036"},"tls_routing_enabled":false},"server_version":"8.2.0","min_client_version":"7.0.0"}% +``` + + +The Teleport Proxy Service requires a TLS certificate and private key. In this +guide, Teleport runs with a self-signed certificate. For convenience, we +configure HTTP clients not to verify the certificate. + +In production setups, you will need to configure Teleport to use a certificate +from a certificate authority like Let's Encrypt. + + +### Deploy Kubernetes Dashboard + +Deploy Kubernetes Dashboard using the following command: + +```code +$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.4.0/aio/deploy/recommended.yaml +``` + +Verify that the dashboard and metrics scraper services are running: + +```code +$ kubectl get services -n kubernetes-dashboard +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +dashboard-metrics-scraper ClusterIP 10.100.9.163 8000/TCP 8s +kubernetes-dashboard ClusterIP 10.100.80.65 443/TCP 8s +``` + +The `kubernetes-dashboard` service has an open HTTPS port but is not accessible +outside the cluster (i.e., it has no external IP). By enabling Teleport +Application Access, we will alow users to securely access the dashboard. + + + +If installing the dashboard leads to an unexpected result, +check the following documentation for updated installation steps: +[Deploying the Dashboard UI](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/#deploying-the-dashboard-ui). + + + +## Step 2/4 Create a user + +We will create a Teleport user who can access Kubernetes Dashboard from +outside the cluster. To do this, we will use the `tctl` administrative tool from +inside the pod that runs the Auth Service and Proxy Service. + +Run the following commands to get the name of the relevant pod and execute a +`tctl` command to create a user: + +```code +# We will use this variable for subsequent commands +$ PROXY_POD=$(kubectl get po -l app=teleport-cluster -o jsonpath='{.items[0].metadata.name}') +$ kubectl exec $PROXY_POD -- tctl users add --roles=access appuser +User "appuser" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h: +https://teleport-cluster.teleport-cluster.svc.cluster.local:443/web/invite/ +``` + +Next, open a browser at `https://localhost:443/web/invite/`, copying the +output of the `tctl` command you executed. minikube's reverse tunnel will allow +you to access the Teleport Proxy Service on `https://localhost`. + +(!docs/pages/includes/insecure-certificate.mdx!) + +![Teleport User Registration](../../../img/quickstart/login.png) + +In the Teleport Web UI, enter a password and scan the QR code with your OTP +application to create your user. + +
+We recommend requiring a second factor for all Teleport users. However, for +convenience while setting up your local demo, you can run the following command +to create a dynamic configuration resource that disables MFA for your demo user: + +```code +$ kubectl exec -i $PROXY_POD -- bash -c "cat<>/home/cp.yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: 'off' +EOF +tctl create --force --confirm /home/cp.yaml" +``` +
+ +After signing in, you will navigate to the Teleport Web UI. + + +## Step 3/4 Enable access to Kubernetes Dashboard + +We will configure the Teleport Application Service to proxy traffic to +Kubernetes Dashboard so we can access it securely from outside the cluster. + +To do so, we will generate a token that our Application Service Node can use to +register itself with the cluster, then run the Application Service with the +token, configuring it to access Kubernetes Dashboard. + +Run the following commands to generate the token, which is specific to +Kubernetes Dashboard: + +```code +# The cluster IP of Kubernetes Dashboard +$ DASH_ADDR=$(kubectl -n kubernetes-dashboard get service kubernetes-dashboard -o jsonpath="{.spec.clusterIP}") +$ kubectl exec -i $PROXY_POD -- tctl tokens add \ +--type=app \ +--app-name=kube-dash \ +--app-uri=https://$DASH_ADDR +The invite token: . +This token will expire in 60 minutes. +... +``` + +Copy the join token so you can assign it to `JOIN_TOKEN` below, then launch the +Teleport Application service: + +```code +# If you need to retrieve this again you can run "tctl tokens ls" +$ JOIN_TOKEN= +$ PROXY_ADDR="$(kubectl get service teleport-cluster -o jsonpath="{.spec.clusterIP}"):443" +$ helm install teleport-kube-agent teleport/teleport-kube-agent \ + --namespace teleport-cluster \ + --set roles=app \ + --set proxyAddr=${PROXY_ADDR?} \ + --set authToken=${JOIN_TOKEN?} \ + --set "apps[0].name"="kube-dash" \ + --set "apps[0].uri"=https://${DASH_ADDR?} \ + --set insecureSkipProxyTLSVerify=true +``` + +
+In this `helm install` command, we use the `insecureSkipProxyTLSVerify=true` +option to prevent the Application Service from verifying the TLS certificate of +the Proxy Service. + +This is because, in our environment, the TLS certificate is +valid for `127.0.0.1`, the external IP of the Proxy Service, while the +Application Service sees the Proxy Service's cluster IP. + +Production environments must not skip TLS certificate verification. +
+ + +Run the following command: + +```code +$ kubectl exec $PROXY_POD -- tctl tokens ls +``` + + +Visit the Teleport Web UI at the following link: + +[Applications](https://teleport-cluster.teleport-cluster.svc.cluster.local/web/cluster/teleport-cluster.teleport-cluster.svc.cluster.local/apps) + +You will now see Kubernetes Dashboard as connected to your cluster. + +![An application connected to your Teleport cluster](../../../img/connected-app.png) + +To access Kubernetes Dashboard, click "LAUNCH." If you see an authentication +form with the title, "Kubernetes Dashboard," you have successfully gained access +via Teleport on Kubernetes. + +If you want to play around with the dashboard, read the following guide: + +[Deploy and Access the Kubernetes Dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/) + +## Step 4/4 Clean up + +Now that you have successfully accessed Kubernetes Dashboard, make sure to +remove the entry you added to your `/etc/hosts` file. + +Terminate the `minikube tunnel` process you started earlier and run +`minikube delete` to tear down your demo cluster. + +## Next steps + +Now that you have used Teleport to securely access resources in your local +Kubernetes cluster, read our guides to setting up Teleport for usage with +Kubernetes in production. + +- Get started with Teleport on AWS EKS: [Running an HA Teleport cluster using + AWS, EKS, and Helm ](../helm/guides/aws) +- Manage access to your Kubernetes cluster with the Teleport Kubernetes Service: + [Connect Kubernetes Cluster to Teleport](./agent.mdx) +- Integrate Teleport with your SSO provider: + [Single Sign-On and Kubernetes RBAC](../controls.mdx) +- Have a Kubernetes cluster but don't want to run Teleport there? + [Kubernetes Access from Standalone Teleport](../guides/standalone-teleport.mdx) + +