Merge branch 'stable'

docs/doc-links.yml

@@ -27,6 +27,8 @@
         link: /user-guide/ambassador-pro-install
       - title: Early Access Releases
         link: /user-guide/early-access
+      - title: Certified Builds
+        link: /user-guide/certified-builds
 
 - title: Concepts
   link: /concepts/overview

docs/reference/rate-limits.md

@@ -6,7 +6,7 @@ Rate limits are a powerful way to improve availability and scalability for your
 
 In Ambassador 0.50 and later, each mapping in Ambassador can have multiple *labels* which annotate a given request. These labels are then passed to a rate limiting service through a gRPC interface. These labels are specified with the `labels` annotation:
 
-```
+```yaml
 apiVersion: ambassador/v1
 kind: Mapping
 name: catalog
@@ -47,6 +47,25 @@ Ambassador supports several special labels:
 
 Note: In Envoy, labels are referred to as descriptors.
 
+### Global Rate Limiting
+Rate limit labels can be configured on a global level within the [Ambassador Module](/reference/modules#the-ambassador-module).
+
+```yaml
+---
+apiVersion: ambassador/v1
+kind: Module
+name: ambassador
+config:
+  use_remote_address: true
+  default_label_domain: ambassador
+  default_labels:
+    ambassador:
+      defaults:
+      - default
+```
+
+This will annotate every request with the string `default`, creating a key for a rate limiting service to rate limit based off. 
+
 ## The `rate_limits` attribute
 
 In pre-0.50 versions of Ambassador, a mapping can specify the `rate_limits` list attribute and at least one `rate_limits` rule which will call the external [RateLimitService](/reference/services/rate-limit-service) before proceeding with the request. An example:

docs/reference/services/rate-limit-service.md

@@ -7,7 +7,7 @@ Rate limiting is a powerful technique to improve the [availability and resilienc
 Ambassador lets users add one or more labels to a given request. These labels are added as part of a `Mapping` object. For example:
 
 ```
-apiVersion: ambassador/v0
+apiVersion: ambassador/v1
 kind: Mapping
 name: catalog
 prefix: /catalog/

docs/user-guide/advanced-rate-limiting.md

@@ -27,7 +27,7 @@ Imagine the `qotm` service is a Rust-y application that can only handle 3 reques
 
 We update the mapping for the `qotm` service to add a request label `qotm` to the route as part of a `request_label_group`:
 
-```
+```yaml
 apiVersion: ambassador/v1
 kind: Mapping
 name: qotm
@@ -43,7 +43,7 @@ labels:
 
 We then need to configure the rate limit for the qotm service. Create a new YAML file, `qotm-ratelimit.yaml`, and put the following configuration into the file.
 
-```
+```yaml
 apiVersion: getambassador.io/v1beta1
 kind: RateLimit
 metadata:
@@ -64,7 +64,7 @@ Deploy the rate limit with `kubectl apply -f qotm-ratelimit.yaml`. (Make sure yo
 
 Suppose you've rewritten the `qotm` service in Golang, and it's humming along nicely. You then discover that some users are taking advantage of this speed to sometimes cause a big spike in requests. You want to make sure that your API doesn't get overwhelmed by any single user. We use the `remote_address` special value in our mapping, which will automatically label all requests with the calling IP address:
 
-```
+```yaml
 apiVersion: ambassador/v1
 kind: Mapping
 name: qotm
@@ -78,7 +78,7 @@ labels:
 
 We then update our rate limits to limit on `remote_address`:
 
-```
+```yaml
 apiVersion: getambassador.io/v1beta1
 kind: RateLimit
 metadata:
@@ -100,7 +100,7 @@ You've dramatically improved availability of the `qotm` service, thanks to the p
 * We're going to rate limit per user.
 * We're going to implement a global rate limit on `GET` requests, but not `POST` requests.
 
-```
+```yaml
 apiVersion: ambassador/v1
 kind: Mapping
 name: qotm
@@ -117,7 +117,7 @@ labels:
 
 When we add multiple criteria to a pattern, the entire pattern matches when ANY of the rules match (i.e., a logical OR). A pattern match then triggers a rate limit event. Our rate limiting configuration becomes:
 
-```
+```yaml
 apiVersion: getambassador.io/v1beta1
 kind: RateLimit
 metadata:
@@ -130,6 +130,69 @@ spec:
      unit: minute
 ```
 
+## Example 4: Global Rate Limiting
+Suppose, like [Example 2](/user-guide/advanced-rate-limiting#example-2-per-user-rate-limiting), you want to ensure a single user cannot overload your server with too many requests to any service. You need to add a request label to every request so you can rate limit off every request a calling IP makes. This can be configured with a [global rate limit](/reference/rate-limits#global-rate-limiting) that add the `remote_address` special value to every request:
+
+```yaml
+---
+apiVersion: ambassador/v1
+kind: Module
+name: ambassador
+config:
+  use_remote_address: true
+  default_label_domain: ambassador
+  default_labels:
+    ambassador:
+      defaults:
+      - remote_address
+```
+
+We can then configure a global `RateLimit` object that limits on `remote_address`:
+
+```yaml
+apiVersion: getambassador.io/v1beta1
+kind: RateLimit
+metadata:
+  name: global-rate-limit
+spec:
+  domain: ambassador
+  limits:
+   - pattern: [{remote_address: "*"}]
+     rate: 10
+     unit: minute
+```
+
+### Bypassing a Global Rate Limit
+Sometimes, you may have an API that cannot handle as much load as others in your cluster. In this case, a global rate limit may not be enough to ensure this API is not overloaded with requests from a user. To protect this API, you will need to create a label that tells Ambassador Pro to apply a stricter limit on requests. With the above global rate limit configuration rate limiting based off `remote_address`, you will need to add a request label to the services `Mapping`: 
+
+```yaml
+apiVersion: ambassador/v1
+kind: Mapping
+name: qotm
+prefix: /qotm/
+service: qotm
+labels:
+  ambassador:
+    - request_label_group:
+      - qotm
+```
+
+Now, the `request_label_group`, contains both the `generic_key: qotm` *and* the `remote_address` key applied from the global rate limit. This allows us to create a separate `RateLimit` object for this route:
+
+```yaml
+apiVersion: getambassador.io/v1beta1
+kind: RateLimit
+metadata:
+  name: qotm-rate-limit
+spec:
+  domain: ambassador
+  limits:
+   - pattern: [{remote_address: "*"}, {generic_key: qotm}]
+     rate: 3
+     unit: minute
+```
+Now, requests will `/qotm/` will be rate limited after only 3 requests.
+
 ## Rate limiting matching rules
 
 The following rules apply to the rate limit patterns:

docs/user-guide/ambassador-pro-install.md

@@ -1,7 +1,7 @@
 # Installing Ambassador Pro
 ---
 
-Ambassador Pro is a commercial version of Ambassador that includes integrated Single Sign-On, powerful rate limiting, and more. In this tutorial, we'll walk through the process of installing Ambassador Pro in Kubernetes.
+Ambassador Pro is a commercial version of Ambassador that includes integrated Single Sign-On, powerful rate limiting, and more. Ambassador Pro also uses a certified version of Ambassador OSS that undergoes additional testing and validation. In this tutorial, we'll walk through the process of installing Ambassador Pro in Kubernetes.
 
 ## 1. Create the Ambassador Pro registry credentials secret.
 Your credentials to pull the image from the Ambassador Pro registry were given in the sign up email. If you have lost this email, please contact us at [email protected].
@@ -60,7 +60,34 @@ ambassador-79494c799f-vj2dv            2/2       Running            0         1h
 ambassador-pro-redis-dff565f78-88bl2   1/1       Running            0         1h
 ```
 
-## 5. Configure Ambassador Pro services
+## 5. Defining the Ambassador Service
+
+After deploying Ambassador Pro, you will need to expose the service to the internet. This is done with a Kubernetes Service.
+
+Create the following YAML and put it in a file called `ambassador-service.yaml:
+```yaml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: ambassador
+spec:
+  type: LoadBalancer
+  externalTrafficPolicy: Local
+  ports:
+   - name: http
+     port: 80
+     targetPort: 80
+  selector:
+    service: ambassador
+```
+
+This will create a `LoadBalancer` service listening on and forwarding traffic to Ambassador on port `80`. `externalTrafficPolicy: Local` will configure the load balancer to to propagate [the original source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) of the client to Ambassador.
+
+**Note:** If you are not deploying in a cloud environment that supports the `LoadBalancer` type, you will need to change this to a different service type (e.g. `NodePort`).
+
+
+## 6. Configure Ambassador Pro services
 
 Ambassador should now be running, along with the Pro modules. To enable rate limiting and authentication, some additional configuration is required.
 

docs/user-guide/auth-tutorial.md

@@ -94,12 +94,14 @@ metadata:
   annotations:
     getambassador.io/config: |
       ---
-      apiVersion: ambassador/v0
+      apiVersion: ambassador/v1
       kind:  AuthService
       name:  authentication
       auth_service: "example-auth:3000"
       path_prefix: "/extauth"
-      allowed_headers:
+      allowed_request_headers:
+      - "x-qotm-session"
+      allowed_authorization_headers:
       - "x-qotm-session"
 spec:
   type: ClusterIP
@@ -195,3 +197,16 @@ TCP_NODELAY set
 ## More
 
 For more details about configuring authentication, read the documentation on [external authentication](/reference/services/auth-service).
+
+## Legacy v0 API
+If using Ambassador v0.40.2 or earlier, use the deprecated v0 `AuthService` API
+```yaml
+      ---
+      apiVersion: ambassador/v0
+      kind:  AuthService
+      name:  authentication
+      auth_service: "example-auth:3000"
+      path_prefix: "/extauth"
+      allowed_headers:
+      - "x-qotm-session"
+```

docs/user-guide/bare-metal.md

@@ -79,4 +79,4 @@ spec:
 ```
 This configuration does not require an Ambassador service be defined so you can remove that service if you have defined one. 
 
-**Note:** Before configuring Ambassador with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one Ambassador able to bind to port 80 or 443 per node and losing any load balancing that is typically performed by Kubernetes services. Join our [slack channel](https://join.slack.com/t/datawire-oss/shared_invite/enQtMzcwMDEwMTc5ODQ3LTE1NmIzZTFmZWE0OTQ1NDc2MzE2NTkzMDAzZWM0MDIxZTVjOGIxYmRjZjY3N2M2Mjk4NGI5Y2Q4NGY4Njc1Yjg) to ask any questions you have regarding running Ambassador on a bare-metal installation.
+**Note:** Before configuring Ambassador with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one Ambassador able to bind to port 80 or 443 per node and losing any load balancing that is typically performed by Kubernetes services. Join our [Slack channel](https://join.slack.com/t/datawire-oss/shared_invite/enQtMzcwMDEwMTc5ODQ3LTE1NmIzZTFmZWE0OTQ1NDc2MzE2NTkzMDAzZWM0MDIxZTVjOGIxYmRjZjY3N2M2Mjk4NGI5Y2Q4NGY4Njc1Yjg) to ask any questions you have regarding running Ambassador on a bare metal installation.

docs/user-guide/certified-builds.md

@@ -0,0 +1,11 @@
+# Certified Builds
+
+Ambassador Pro uses certified Ambassador builds. These builds are based on Ambassador OSS builds, but undergo additional testing. In addition, bug fixes and security issues may be backported to Ambassador Pro builds under specific situations.
+
+## Certified build testing
+
+In general, certified builds undergo several types of testing.
+
+* Community testing. All code in certified builds are first shipped as part of Ambassador OSS. With thousands of installs every week, the Ambassador community provides extensive testing.
+* Integration testing. Ambassador certified builds are integration tested with popular integration points such as Prometheus, Consul, and Istio, to insure that Ambassador works as expected with other infrastructure software.
+* Torture testing. Ambassador certified builds are subject to additional long-running torture tests designed to measure stability and reliability under various conditions.

docs/user-guide/early-access.md

@@ -4,9 +4,9 @@ From time to time, Ambassador may ship early access releases to test major chang
 
 Early access releases will always have names that include the string "-ea" followed by a build number, for example `0.50.0-ea1` is the first early access build of Ambassador 0.50.0.
 
-## Ambassador 0.50 Early Access
+## Early Access Status
 
-Ambassador 0.50 is a major revamp of Ambassador's architecture, with support for Envoy v2 configuration, ADS, and significant internal refactoring. For details on Ambassador 0.50, see the [Ambassador 0.50 Early Access blog post](https://blog.getambassador.io/announcing-ambassador-0-50-early-access-1-with-v2-config-ads-support-cd785276a60e).
+There are currently no early access releases available.
 
 ### Installing Ambassador Early Access releases