Skip to content

Commit

Permalink
Respond to PR feedback
Browse files Browse the repository at this point in the history
I've made it more explicit that the minikube Docker driver is required
for the demo. I have also added a row to the required software table
that includes Docker Desktop/Docker Engine. I've tested this on my
Linux desktop, and modified commands to support Docker Engine as well
as Docker Desktop (i.e., "minikube tunnel" exposes a private IP address
beside 127.0.0.1 for the load balancer).

Also made a couple of minor tweaks, and removed the mention of
localhost in relation to the Web UI.
  • Loading branch information
ptgott committed Mar 22, 2022
1 parent 2cb05bb commit 51ae533
Showing 1 changed file with 49 additions and 49 deletions.
98 changes: 49 additions & 49 deletions docs/pages/kubernetes-access/getting-started/local.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ 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.
machine. The cluster will run Kubernetes Dashboard, the official browser 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
Expand Down Expand Up @@ -40,14 +41,7 @@ Make sure that the following tools are installed locally:
|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/)
|Docker Desktop (MacOS and Windows) or Docker Engine (Linux desktop) | Required minikube driver | [Get Started With Docker](https://www.docker.com/get-started)|

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.
Expand All @@ -56,10 +50,10 @@ mobile device. You will use this to authenticate to your Teleport cluster.

### Start minikube

Start minikube with the default driver:
Start minikube with the Docker driver:

```code
$ minikube start
$ minikube start --driver=docker
```

Add the Teleport Helm repository. Our Helm charts make it easier to deploy
Expand All @@ -77,7 +71,10 @@ You will deploy the Auth Service and Proxy Service by installing the
```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?}
$ helm install teleport-cluster teleport/teleport-cluster \
--create-namespace \
--namespace=teleport-cluster \
--set clusterName=${CLUSTER_NAME?}
$ kubectl config set-context --current --namespace teleport-cluster
```

Expand All @@ -91,33 +88,6 @@ 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.

<Notice type="warning">
Set yourself a reminder to clean up your `/etc/hosts`
file when you are done with this guide.
</Notice>

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
Expand Down Expand Up @@ -150,11 +120,13 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)
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:
The Proxy Service enables you to manage your cluster via an HTTP API. Assign the
external IP of the load balancer to an environment variable and verify that the
HTTP API is working:

```
$ curl --insecure https://localhost:443/webapi/ping
```code
$ EXTERNAL_IP=$(kubectl get service teleport-cluster -o jsonpath='{ .status.loadBalancer.ingress[0].ip }')
$ curl --insecure https://${EXTERNAL_IP?}: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"}%
```

Expand All @@ -167,6 +139,34 @@ In production setups, you will need to configure Teleport to use a certificate
from a certificate authority like Let's Encrypt.
</Admonition>

### 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.

<Notice type="warning">
Set yourself a reminder to clean up your `/etc/hosts`
file when you are done with this guide.
</Notice>

Append an entry to your `/etc/hosts` file that maps the external IP of your
Proxy Service to the DNS name Kubernetes assigns, plus a DNS name we will use
later for Kubernetes Dashboard.

```code
$ sudo -E bash -c "echo \"${EXTERNAL_IP?} teleport-cluster.teleport-cluster.svc.cluster.local kube-dash.teleport-cluster.teleport-cluster.svc.cluster.local\" >> /etc/hosts"
```

`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.

### Deploy Kubernetes Dashboard

Deploy Kubernetes Dashboard using the following command:
Expand Down Expand Up @@ -213,9 +213,9 @@ User "appuser" has been created but requires a password. Share this URL with the
https://teleport-cluster.teleport-cluster.svc.cluster.local:443/web/invite/<token>
```

Next, open a browser at `https://localhost:443/web/invite/<token>`, 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`.
Next, open a browser at the URL returned by `tctl users add` command. minikube's
reverse tunnel will allow you to access the Teleport Proxy Service at
`https://teleport-cluster.teleport-cluster.svc.cluster.local:443`.

(!docs/pages/includes/insecure-certificate.mdx!)

Expand Down Expand Up @@ -334,11 +334,11 @@ Terminate the `minikube tunnel` process you started earlier and run
## 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.
Kubernetes cluster, read our guides to setting up Teleport for Kubernetes in
production.

- Get started with Teleport on AWS EKS: [Running an HA Teleport cluster using
AWS, EKS, and Helm ](../helm/guides/aws)
AWS, EKS, and Helm](../helm/guides/aws.mdx)
- Manage access to your Kubernetes cluster with the Teleport Kubernetes Service:
[Connect Kubernetes Cluster to Teleport](./agent.mdx)
- Integrate Teleport with your SSO provider:
Expand Down

0 comments on commit 51ae533

Please sign in to comment.