Skip to content

Commit

Permalink
(from getambassador.io) Merge pull request #646 from datawire/docs/tp…
Browse files Browse the repository at this point in the history 
…_qs_edits

Edits to Telepresence quick start
  • Loading branch information
@mattmcclure-dw
mattmcclure-dw authored Apr 8, 2021
2 parents ca431df + f69d0e8 commit 0287180
Showing 1 changed file with 51 additions and 116 deletions.
167 changes: 51 additions & 116 deletions quick-start/demo-node.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,42 +23,55 @@ import QSCards from './qs-cards'

</div>

In this guide we'll give you **everything you need in a preconfigured demo cluster**. If you want to use **your own cluster**, choose an option below to go to that language option and get started:
In this guide we'll give you **everything you need in a preconfigured demo cluster:** the Telepresence CLI, a config file for connecting to your demo cluster, and code to run a cluster service locally.

<div class="docs-language-toc">

* <a href="../qs-node/" title="Node.js">Node.js</a>
* <a href="../qs-go/" title="Go">Go</a>
* <a href="../qs-java/" title="Java">Java</a>
* <a href="../qs-python/" title="Python (Flask)">Python (Flask)</a>
* <a href="../qs-python-fastapi/" title="Python (FastAPI)">Python (FastAPI)</a>

</div>

## Prerequisites

There are none for this guide! Everything you need will be provided in the archive file below: the Telepresence CLI, a config file for connecting to our preconfigured demo cluster, and code for a service to run locally.
<Alert severity="info">
<strong>Already have a cluster?</strong> Switch over to a <a href="../qs-node">version of this guide</a> that takes you though the same steps using your own cluster.
</Alert>

## 1. Download the demo cluster archive

1. [Go to this page on Ambassador Cloud](https://app.getambassador.io/cloud/demo-cluster) and sign in to download your demo cluster archive.
1. <a href="https://app.getambassador.io/cloud/demo-cluster-download-popup" onClick={(e) => {window.open('https://app.getambassador.io/cloud/demo-cluster-download-popup', 'ambassador-cloud-demo-cluster', 'menubar=no,location=no,resizable=yes,scrollbars=yes,status=no,width=550,height=750'); e.preventDefault(); }} target="_blank">Sign in to Ambassador Cloud to download your demo cluster archive.</a> The archive contains all the tools and configurations you need to complete this guide.

2. Extract the archive file, open the `ambassador-demo-cluster` folder, and run the installer script (the commands below might vary based on where your browser saves downloaded files).

2. Extract the content of the archive and run the installer:
`./install.sh`
<Alert severity="info">
This step will also install some dependency packages onto your laptop using npm, you can see those packages at <code>ambassador-demo-cluster/edgey-corp-nodejs/DataProcessingService/package.json</code>.
</Alert>

3. List the Kubernetes services after running the installer:
```
cd ~/Downloads
unzip ambassador-demo-cluster.zip -d ambassador-demo-cluster
./ambassador-demo-cluster/install.sh
```

3. The demo cluster we provided already has a demo app running. List the app's services:
`kubectl get services`

```
$ kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.43.0.1 <none> 443/TCP 14h
dataprocessingservice ClusterIP 10.43.159.239 <none> 3000/TCP 14h
verylargejavaservice ClusterIP 10.43.223.61 <none> 8080/TCP 14h
verylargedatastore ClusterIP 10.43.203.19 <none> 8080/TCP 14h
```

4. Confirm that the Telepresence CLI is now installed, we expect to see that the daemons are not yet running:
`telepresence status`

```
$ telepresence status
Root Daemon: Not running
User Daemon: Not running
```

<Alert severity="info">
<strong>macOS users:</strong> If you receive an error when running Telepresence that the developer cannot be verified, open <strong>System Preferences → Security & Privacy → General</strong>. Click <strong>Open Anyway</strong> at the bottom to bypass the security block. Then retry the <code>telepresence status</code> command.
</Alert>

<Alert severity="success">
You now have Telepresence installed on your workstation and a Kubernetes cluster configured in your terminal.
</Alert>
Expand All @@ -67,7 +80,7 @@ There are none for this guide! Everything you need will be provided in the archi

Telepresence connects your local workstation to a remote Kubernetes cluster.

1. Connect to the cluster:
1. Connect to the cluster (this requires root privileges and will ask for your password):
`telepresence connect`

```
Expand All @@ -78,17 +91,9 @@ Telepresence connects your local workstation to a remote Kubernetes cluster.
Connected to context default (https://<cluster-public-IP>)
```

<Alert severity="info">
macOS users: If you receive an error when running Telepresence that the developer cannot be verified, open <strong>System Preferences → Security & Privacy → General</strong>. Click <strong>Open Anyway</strong> at the bottom to bypass the security block. Then retry the <code>telepresence connect</code> command.
</Alert>

2. Test that Telepresence is working properly by connecting to the Kubernetes API server:
`curl -ik https://kubernetes.default`

<Alert severity="info">
<strong>Didn't work?</strong> Make sure you are using Telepresence 2.0.3 or greater, check with <code>telepresence version</code> and upgrade <a href="../../install/upgrade/">here</a> if needed.
</Alert>

```
$ curl -ik https://kubernetes.default
Expand All @@ -98,9 +103,14 @@ Telepresence connects your local workstation to a remote Kubernetes cluster.
...
```
<Alert severity="info">

<Alert severity="info">
<strong>Didn't work?</strong> Make sure you are using Telepresence 2.0.3 or greater, check with <code>telepresence version</code> and upgrade <a href="../../install/upgrade/">here</a> if needed.
</Alert>

<Alert severity="info">
The 401 response is expected. What's important is that you were able to contact the API.
</Alert>
</Alert>

<Alert severity="success">
<strong>Congratulations!</strong> You’ve just accessed your remote Kubernetes API server, as if you were on the same network! With Telepresence, you’re able to use any tool that you have locally to connect to any service in the cluster.
Expand All @@ -112,40 +122,6 @@ Your local workstation may not have the compute or memory resources necessary to

We'll use a sample app that is already installed in your demo cluster. Let's take a quick look at it's architecture before continuing.

<Alert severity="info">
While Telepresence works with any language, this guide uses a sample app written in Node.js. We have versions in <a href="../qs-go/">Go</a>, <a href="../qs-java/">Java</a>,<a href="../qs-python/">Python using Flask</a>, and <a href="../qs-python-fastapi/">Python using FastAPI</a> if you prefer.
</Alert>

<!--
1. Start by installing a sample application that consists of multiple services:
`kubectl apply -f https://raw.githubusercontent.com/datawire/edgey-corp-nodejs/main/k8s-config/edgey-corp-web-app-no-mapping.yaml`
```
$ kubectl apply -f https://raw.githubusercontent.com/datawire/edgey-corp-nodejs/main/k8s-config/edgey-corp-web-app-no-mapping.yaml
deployment.apps/dataprocessingservice created
service/dataprocessingservice created
...
```
2. Give your cluster a few moments to deploy the sample application.
Use `kubectl get pods` to check the status of your pods:
```
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
verylargedatastore-855c8b8789-z8nhs 1/1 Running 0 78s
verylargejavaservice-7dfddbc95c-696br 1/1 Running 0 78s
dataprocessingservice-5f6bfdcf7b-qvd27 1/1 Running 0 79s
```
3. Once all the pods are in a `Running` state, go to the frontend service in your browser at [http://verylargejavaservice.default:8080](http://verylargejavaservice.default:8080).
-->

1. Use `kubectl get pods` to check the status of your pods:

```
Expand All @@ -165,55 +141,24 @@ We'll use a sample app that is already installed in your demo cluster. Let's ta
<strong>Congratulations</strong>, you can now access services running in your cluster by name from your laptop!
</Alert>

<!--
## 4. Set up a local development environment
You will now download the repo containing the services' code and run the DataProcessingService service locally. This version of the code has the UI color set to <strong style="color:blue">blue</strong> instead of <strong style="color:green">green</strong>.
<Alert severity="info">
Confirm first that nothing is running locally on port 3000! If <code>curl localhost:3000</code> returns <code>Connection refused</code> then you should be good to go.
</Alert>
1. Clone the web app’s GitHub repo:
`git clone https://github.com/datawire/edgey-corp-nodejs.git`
## 4. Run a service on your laptop

```
$ git clone https://github.com/datawire/edgey-corp-nodejs.git
Cloning into 'edgey-corp-nodejs'...
remote: Enumerating objects: 441, done.
...
```
Now start up the DataProcessingService service on your laptop. This version of the code has the UI color set to <strong style="color:blue">blue</strong> instead of <strong style="color:green">green</strong>.

2. Change into the repo directory, then into DataProcessingService:
`cd edgey-corp-nodejs/DataProcessingService/`
1. **In a <u>new</u> terminal window**, go the demo application directory in the extracted archive folder:
`cd ambassador-demo-cluster/edgey-corp-nodejs/DataProcessingService`

3. Install the dependencies and start the Node server:
`npm install && npm start`
2. Start the application:
`npm start`

```
$ npm install && npm start
$ npm start
...
Welcome to the DataProcessingService!
{ _: [] }
Server running on port 3000
```
-->

## 4. Run a service on your laptop

Now start up the DataProcessingService service on your laptop. This version of the code has the UI color set to <strong style="color:blue">blue</strong> instead of <strong style="color:green">green</strong>.

1. **In a <u>new</u> terminal window**, go the demo application directory:
`cd <extracted archive directory>/edgey-corp-nodejs/DataProcessingService`

2. Start the application:
`npm start`

<Alert severity="info">
<a href="https://nodejs.org/en/download/package-manager/">Install Node.js from here</a> if needed.
</Alert>

4. **Back in your <u>previous</u> terminal window**, curl the service running locally to confirm it’s set to <strong style="color:blue">blue</strong>:
`curl localhost:3000/color`
Expand All @@ -234,9 +179,9 @@ Next, we’ll create an intercept. An intercept is a rule that tells Telepresenc
1. Start the intercept with the `intercept` command, setting the service name and port:
`telepresence intercept dataprocessingservice --port 3000`

<Alert severity="info">
<Alert severity="info">
<strong>Didn't work?</strong> Make sure you are working in the terminal window where you ran the script because it sets environment variables to access the demo cluster. Those variables will only will apply to that terminal session.
</Alert>
</Alert>

```
$ telepresence intercept dataprocessingservice --port 3000
Expand All @@ -245,21 +190,11 @@ Next, we’ll create an intercept. An intercept is a rule that tells Telepresenc
intercepted
Intercept name: dataprocessingservice
State : ACTIVE
Destination : 127.0.0.1:3000
Intercepting : all TCP connections
...
```




2. Go to the frontend service again in your browser at [http://verylargejavaservice:8080](http://verylargejavaservice:8080). You will now see the <strong style="color:blue">blue</strong> elements in the app.

<!--
<Alert severity="info">
See <a href="../../reference/dns">this doc</a> for more information on how Telepresence resolves DNS.
</Alert>
-->

<Alert severity="success">
The frontend’s request to DataProcessingService is being <strong>intercepted and rerouted</strong> to the Node server on your laptop!
</Alert>
Expand Down Expand Up @@ -351,4 +286,4 @@ Normal traffic coming to your app gets the <strong style="color:green">green</st

## <img class="os-logo" src="../../images/logo.png"/> What's Next?

<QSCards/>
<QSCards/>

0 comments on commit 0287180

Please sign in to comment.