Skip to content

Commit

Permalink
Merge pull request #216 from datawire/move-install-pages
Browse files Browse the repository at this point in the history 
removed getting started content, as it is being replaced by docs [apro #830]
  • Loading branch information
@khussey
khussey authored Jan 14, 2020
2 parents a3c2030 + ff7ce52 commit 785897b
Show file tree
Hide file tree
Showing 3 changed files with 199 additions and 188 deletions.
8 changes: 5 additions & 3 deletions doc-links.yml
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
- title: Welcome
collapsable: false
items:
- title: Getting Started with the Ambassador Edge Stack
link: /user-guide/getting-started
- title: Welcome
link: /docs/
- title: Why the Ambassador Edge Stack?
link: /about/why-ambassador
- title: Need help?
Expand All @@ -11,11 +11,13 @@
- title: Install Ambassador Edge Stack
items:
- title: Quick Start Installation Guide
link: /user-guide/install
link: /user-guide/getting-started
- title: Edge Policy Console
link: /about/edge-policy-console
- title: Other Install & Upgrade Options
items:
- title: Install and Upgrade Overview
link: /user-guide/install
- title: Upgrade to the Ambassador Edge Stack
link: /user-guide/upgrade-to-edge-stack
- title: Upgrade to a Newer Version
Expand Down
184 changes: 165 additions & 19 deletions user-guide/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,178 @@
---
description: In this tutorial, we'll walk through the process of deploying Ambassador in Kubernetes for ingress routing.
---
# Getting Started with the Ambassador Edge Stack
# Quick Start Installation Guide

The Ambassador Edge Stack is a free comprehensive, self-service edge stack that is Kubernetes-native and built on [Envoy Proxy](https://www.envoyproxy.io/). With the Ambassador Edge Stack, application developers can *independently* manage their edge (e.g., authentication, routing, rate limiting) without centralized operational intervention, reducing toil. The Ambassador Edge Stack provides a comprehensive set of capabilities for the edge ranging from traffic management (e.g., rate limiting, load balancing), security (e.g., TLS, single sign-on, rate limiting), and developer onboarding (e.g., developer portal, Swagger/OpenAPI support).
In this guide, we'll walk you through installing and configuring the Ambassador Edge Stack in your Kubernetes cluster. Within a few minutes, your cluster will be routing HTTPS requests from the Internet to a backend service. You'll also have a sense of how the Ambassador Edge Stack is managed.

## Before You Begin

The Ambassador Edge Stack is designed to run in Kubernetes for production. The most essential requirements are:

* Kubernetes 1.11 or later
* The `kubectl` command-line tool

## Install the Ambassador Edge Stack

The Ambassador Edge Stack installs in minutes. There are three general methods for installing the Ambassador Edge Stack:
The Ambassador Edge Stack is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../../about/quickstart) to deploy the Ambassador Edge Stack locally.


1. In your terminal, run the following command:

```bash
kubectl apply -f https://www.getambassador.io/early-access/yaml/aes-crds.yaml && \
kubectl wait --for condition=established --timeout=90s crd -lproduct=aes && \
kubectl apply -f https://www.getambassador.io/early-access/yaml/aes.yaml && \
kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes
```

2. Determine the IP address of your cluster by running the following command:

```bash
kubectl get -n ambassador service ambassador -o 'go-template={{range .status.loadBalancer.ingress}}{{print .ip "\n"}}{{end}}'
```

Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address.

Note: If you are a **Minikube user**, Minikube does not natively support load balancers. Instead, use `minikube service list`. You should see something similar to the following:

```bash
(⎈ |minikube:ambassador)$ minikube service list
|-------------|------------------|--------------------------------|
| NAMESPACE | NAME | URL |
|-------------|------------------|--------------------------------|
| ambassador | ambassador | http://192.168.64.2:31230 |
| | | http://192.168.64.2:31042 |
| ambassador | ambassador-admin | No node port |
| ambassador | ambassador-redis | No node port |
| default | kubernetes | No node port |
| kube-system | kube-dns | No node port |
|-------------|------------------|--------------------------------|
```

Use any of the URLs listed next to `ambassador` to access the Ambassador Edge Stack.

3. Navigate to `http://<your-IP-address>` and click through the certificate warning for access the Edge Policy Console interface. The certificate warning appears because, by default, the Ambassador Edge Stack uses a self-signed certificate for HTTPS.
* Chrome users should click **Advanced > Proceed to website**.
* Safari users should click **Show details > visit the website** and provide your password.

4. To login to the [Edge Policy Console](../../about/edge-policy-console), download and install `edgectl`, the command line tool Edge Control, by following the provided instructions on the page. The Console lists the correct command to run, and provides download links for the edgectl binary.

The Edge Policy Console must authenticate your session using a Kubernetes Secret in your cluster. Edge Control accesses that secret using `kubectl`, then sends a URL to your browser that contains the corresponding session key. This extra step ensures that access to the Edge Policy Console is just as secure as access to your Kubernetes cluster.

For more information, see [Edge Control](../../reference/edge-control).

## Configure TLS for Automatic HTTPS

If you have the ability to update your DNS, Ambassador can automatically configure a valid TLS certificate for you, eliminating the TLS warning. If you do not have the ability to update your DNS, skip to the next section, "Create a Mapping."

1. Update your DNS so that your domain points to the IP address for your cluster.

2. In the Edge Policy Console, create a `Host` resource:
* On the "Hosts" tab, click the **Add** button on the right.
* Enter your hostname (domain) in the hostname field.
* Check the "Use ACME to manage TLS" box.
* Review the Terms of Service and check the box that you agree to the Terms of Service.
* Enter the email address to be associated with your TLS certificate.
* Click the **Save** button.
You'll see the newly created `Host` resource appear in the UI with a status of Pending. This will change to Ready once the certificate is fully provisioned. If you receive an error that your hostname does not qualify for ACME management, you can still configure TLS following [these instructions](../../reference/core/tls).
3. Once the Host is ready, navigate to `https://<hostname>` in your browser. Note that the certificate warning has gone away. In addition, the Ambassador Edge Stack automatically will redirect HTTP connections to HTTPS.
## Create a Mapping
In a typical configuration workflow, Custom Resource Definitions (CRDs) are used to define the intended behavior of Ambassador Edge Stack. In this example, we'll deploy a sample service and create a `Mapping` resource. Mappings allow you to associate parts of your domain with different URLs, IP addresses, or prefixes.

1. We'll start by deploying the `quote` service. Save the below configuration into a file named `quote.yaml`. This is a basic configuration that tells Kubernetes to deploy the `quote` container and create a Kubernetes `service` that points to the `quote` container.
```
---
apiVersion: v1
kind: Service
metadata:
name: quote
namespace: ambassador
spec:
ports:
- name: http
port: 80
targetPort: 8080
selector:
app: quote
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: quote
namespace: ambassador
spec:
replicas: 1
selector:
matchLabels:
app: quote
strategy:
type: RollingUpdate
template:
metadata:
labels:
app: quote
spec:
containers:
- name: backend
image: quay.io/datawire/quote:0.2.7
ports:
- name: http
containerPort: 8080
```
2. Deploy the `quote` service to the cluster by typing the command `kubectl apply -f quote.yaml`.
3. Now, create a `Mapping` configuration that tells Ambassador to route all traffic from `/backend/` to the `quote` service. Copy the YAML and save to a file called `quote-backend.yaml`.
```
---
apiVersion: getambassador.io/v2
kind: Mapping
metadata:
name: quote-backend
namespace: ambassador
spec:
prefix: /backend/
service: quote
```
4. Apply the configuration to the cluster by typing the command `kubectl apply -f quote-backend.yaml`.
5. Test the configuration by typing `curl -Lk https://<hostname>/backend/` or `curl -Lk https://<IP address>/backend/`. You should see something similar to the following:
```
(⎈ |rdl-1:default)$ curl -Lk https://aes.ri.k36.net/backend/
{
"server": "idle-cranberry-8tbb6iks",
"quote": "Non-locality is the driver of truth. By summoning, we vibrate.",
"time": "2019-12-11T20:10:16.525471212Z"
}
```
## A single source of configuration
1. In the Ambassador Edge Stack, Kubernetes serves as the single source of configuration. Changes made on the command line (via `kubectl`) are reflected in the UI, and vice versa. This enables a consistent configuration workflow. You can see this in action by navigating to the Mappings tab. You'll see an entry for the `quote-backend` Mapping that was just created on the command line.

* [Standard install](../install). If you're new to Kubernetes and/or Ambassador, use this method.
* [Docker](../../about/quickstart). Don't have Kubernetes, but want to try out Ambassador? The Ambassador Edge Stack can run locally on your laptop in a Docker container.
* [Helm](../helm). Helm is a popular package manager for Kubernetes. If you're using Helm, Ambassador Edge Stack comes pre-packaged as a Helm chart.
2. If you configured TLS, you can type `kubectl get hosts` to see the `Host` resource that was created:

## More about the Ambassador Edge Stack
```
(⎈ |rdl-1:default)$ kubectl get hosts
NAME HOSTNAME STATE PHASE COMPLETED PHASE PENDING AGE
aes.ri.k36.net aes.ri.k36.net Ready 158m
```

Want to learn more about the Ambassador Edge Stack? Read [Why Ambassador](../../about/why-ambassador) and review a summary of the features of the Ambassador Edge Stack below.
## Developer Onboarding

![Features](../../doc-images/features-table.jpg)
The Quote service we just deployed publishes its API as a Swagger document. This API is automatically detected by the Ambassador Edge Stack and published.

## Documentation and Help
1. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the documentation there for internal use.
Once you’ve installed the Ambassador Edge Stack, you can read about the best practices for configuration and usage in your production environment, along with tutorials and guides on just how to get you there.
2. Navigate to `https://<hostname>/docs/` or `https://<IP address>/docs/` to see the externally visible Developer Portal (make sure you include the trailing `/`). This is a fully customizable portal that you can share with third parties who need to information about your APIs.
We have several major sections to our documentation:
## What’s Next?
* [Core Concepts](../../concepts/overview) cover Ambassador's architecture and how it should be used.
* [Guides and tutorials](../../docs/guides) walk you through how to configure Ambassador for specific use cases, from rate limiting to Istio integration to gRPC.
* The [Reference](../../reference/configuration) section contains detailed documentation on configuring and managing all aspects of Ambassador.
The Ambassador Edge Stack has a comprehensive range of [features](/features/) to support the requirements of any edge microservice.
If the documentation doesn't have the answers you need, join our [Slack community](https://d6e.co/slack)! Bug reports, feature requests, and pull requests are also gratefully accepted on our [GitHub](https://github.com/datawire/ambassador/).
To learn more about how the Ambassador Edge Stack works, along with use cases, best practices, and more, check out the [Ambassador](../../about/why-ambassador) story.
Loading

0 comments on commit 785897b

Please sign in to comment.