diff --git a/README.md b/README.md index 075735d50..c9da99c90 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,47 @@ # Routing Release -This repository is a [BOSH release](https://github.com/cloudfoundry/bosh) for -deploying Gorouter, TCP Routing, and other associated tasks that provide HTTP and TCP routing in Cloud Foundry foundations. - -## Downloads - -Our BOSH release is available on [bosh.io](http://bosh.io/releases/github.com/cloudfoundry/routing-release) -and on our [GitHub Releases page](https://github.com/cloudfoundry/routing-release/releases). - -## Getting Help - -If you have a concrete issue to report or a change to request, please create a -[Github issue on -routing-release](https://github.com/cloudfoundry/routing-release/issues/new/choose). - -Issues with any related submodules -([Gorouter](https://github.com/cloudfoundry/gorouter), [Routing -API](https://github.com/cloudfoundry/routing-api), [Route -Registrar](https://github.com/cloudfoundry/route-registrar), [CF TCP -Router](https://github.com/cloudfoundry/cf-tcp-router)) should be created here -instead. - -You can also reach us on Slack at -[cloudfoundry.slack.com](https://cloudfoundry.slack.com) in the -[`#cf-for-vms-networking`](https://cloudfoundry.slack.com/app_redirect?channel=C01ABMVNE9E). -channel. - -## Contributing -See the [Contributing.md](./.github/CONTRIBUTING.md) for more information on how to contribute. - -## Table of Contents -1. [Routing Operator Resources](#routing-operator-resources) -1. [Routing App Developer Resources](#routing-app-developer-resources) -1. [Routing Contributor Resources](#routing-contributor-resources) - ---- -## Routing Operator Resources -### High Availability - -The TCP Router and Routing API are stateless and horizontally scalable. The TCP -Routers must be fronted by a load balancer for high-availability. The Routing -API depends on a database, that can be clustered for high-availability. For high -availability, deploy multiple instances of each job, distributed across regions -of your infrastructure. - -### Routing API -For details refer to [Routing API](https://github.com/cloudfoundry/routing-api/blob/master/README.md). - -### Metrics -For documentation on metrics available for streaming from Routing components -through the Loggregator -[Firehose](https://docs.cloudfoundry.org/loggregator/architecture.html), visit -the [CloudFoundry -Documentation](http://docs.cloudfoundry.org/loggregator/all_metrics.html#routing). -You can use the [NOAA Firehose sample app](https://github.com/cloudfoundry/noaa) -to quickly consume metrics from the Firehose. -## Routing App Developer Resources - -### Session Affinity -For more information on how Routing release accomplishes session affinity, i.e. -sticky sessions, refer to the [Session Affinity document](docs/session-affinity.md). - -### Headers -[X-CF Headers](/docs/x_cf_headers.md) describes the X-CF headers that are set on requests and responses inside of CF. - +This repository is a [BOSH](https://github.com/cloudfoundry/bosh) +release for deploying Gorouter, TCP Routing, and other associated tasks +that provide HTTP and TCP routing in Cloud Foundry foundations. + +For information on getting started with Cloud Foundry look at the docs +for [CF Deployment](https://github.com/cloudfoundry/cf-deployment). + +# Docs + +- [How To enable Quotas for TCP + Routing](./docs/03-how-to-enable-quota-tcp-routing.md) +- [How To Limit Trusted CAs for + Gorouter](./docs/03-how-to-limit-trusted-cas-for-gorouter.md) +- [How To Use NATS Client](./docs/03-how-to-use-nats-client.md) +- [How To Use Session + Affinity](./docs/03-how-to-use-session-affinity.md) +- [How To Use X-CF Headers](./docs/03-how-to-use-x-cf-headers.md) +- [(go1.15) Fixing Bad + Transfer-Encoding](./docs/04-go1.15-fixing-bad-transfer-encoding.md) +- [(go1.15) X.509 CommonName + deprecation](./docs/04-go1.15-x509-commonname-deprecation.md) +- [(go1.20) Multiple Expect 100-continue + responses](./docs/04-go1.20-multiple-expect-100-continue.md) +- [(routing-release-0.262.0) Healthy App Route + Pruning](./docs/04-routing-0.262.0-healthy-app-route-pruning.md) +- [(routing-release-0.277.0) TCP Router Port + Conflict](./docs/04-routing-0.277.0-tcp-router-port-conflict.md) +- [High Availability & Scaling](./docs/05-high-availbility-scaling.md) + +# Contributing + +See the [Contributing.md](./.github/CONTRIBUTING.md) for more +information on how to contribute. + +# Working Group Charter + +This repository is maintained by [App Runtime +Platform](https://github.com/cloudfoundry/community/blob/main/toc/working-groups/app-runtime-platform.md) +under `Networking` area. + +> \[!IMPORTANT\] +> +> Content in this file is managed by the [CI task +> `sync-readme`](https://github.com/cloudfoundry/wg-app-platform-runtime-ci/blob/c83c224ad06515ed52f51bdadf6075f56300ec93/shared/tasks/sync-readme/metadata.yml) +> and is generated by CI following a convention. diff --git a/docs/tcp_route_quota.md b/docs/03-how-to-enable-quota-tcp-routing.md similarity index 92% rename from docs/tcp_route_quota.md rename to docs/03-how-to-enable-quota-tcp-routing.md index 88d6aa0b0..36b8d6a46 100644 --- a/docs/tcp_route_quota.md +++ b/docs/03-how-to-enable-quota-tcp-routing.md @@ -1,4 +1,10 @@ -# Enable Quotas for TCP Routing +--- +title: How To enable Quotas for TCP Routing +expires_at: never +tags: [routing-release] +--- + +# How To Enable Quotas for TCP Routing As ports can be a limited resource in some environments, the default quotas in Cloud Foundry for IaaS other than BOSH Lite do not allow reservation of route diff --git a/docs/limiting-trusted-cas-for-gorouter.md b/docs/03-how-to-limit-trusted-cas-for-gorouter.md similarity index 95% rename from docs/limiting-trusted-cas-for-gorouter.md rename to docs/03-how-to-limit-trusted-cas-for-gorouter.md index bf26d9ecb..1192352aa 100644 --- a/docs/limiting-trusted-cas-for-gorouter.md +++ b/docs/03-how-to-limit-trusted-cas-for-gorouter.md @@ -1,4 +1,10 @@ -# Limiting Trusted CAs for Gorouter +--- +title: How To Limit Trusted CAs for Gorouter +expires_at: never +tags: [routing-release] +--- + +# How to Limit Trusted CAs for Gorouter This doc is for operators who want to use the new "only trust client CA certs" feature for gorouter to limit the CA certs that gorouter trusts. diff --git a/docs/nats-client.md b/docs/03-how-to-use-nats-client.md similarity index 97% rename from docs/nats-client.md rename to docs/03-how-to-use-nats-client.md index 2f5775e1b..e2208dd8b 100644 --- a/docs/nats-client.md +++ b/docs/03-how-to-use-nats-client.md @@ -1,4 +1,10 @@ -# NATS Client +--- +title: How To Use NATS Client +expires_at: never +tags: [routing-release] +--- + +# How To Use NATS Client ## What is it? @@ -109,4 +115,4 @@ There are many scenarios where you may use `nats_client` to debug gorouter issue - Set up large deployments with hundreds of apps and thousands of routes, without having to actually deploy all of them - Simulate outages where large numbers of backends no longer respond (e.g. AZ outages) - Simulate NATS outages where apps have moved elsewhere but gorouter didn't get the proper `router.unregister` message -- etc. \ No newline at end of file +- etc. diff --git a/docs/session-affinity.md b/docs/03-how-to-use-session-affinity.md similarity index 98% rename from docs/session-affinity.md rename to docs/03-how-to-use-session-affinity.md index fd674d83c..afcfee918 100644 --- a/docs/session-affinity.md +++ b/docs/03-how-to-use-session-affinity.md @@ -1,4 +1,10 @@ -# Session Affinity +--- +title: How To Use Session Affinity +expires_at: never +tags: [routing-release] +--- + +# How To Use Session Affinity ## What is it? diff --git a/docs/x_cf_headers.md b/docs/03-how-to-use-x-cf-headers.md similarity index 94% rename from docs/x_cf_headers.md rename to docs/03-how-to-use-x-cf-headers.md index 332862aa7..346443e3f 100644 --- a/docs/x_cf_headers.md +++ b/docs/03-how-to-use-x-cf-headers.md @@ -1,4 +1,10 @@ -# X-CF Headers +--- +title: How To Use X-CF Headers +expires_at: never +tags: [routing-release] +--- + +# How To Use X-CF Headers | Header | If a client provides this header will that affect routing decisions? | Value | More info | | -- | -- | -- | -- | diff --git a/docs/fixing-bad-transfer-encoding-apps.md b/docs/04-go1.15-fixing-bad-transfer-encoding.md similarity index 91% rename from docs/fixing-bad-transfer-encoding-apps.md rename to docs/04-go1.15-fixing-bad-transfer-encoding.md index dd9406fcc..2655348bd 100644 --- a/docs/fixing-bad-transfer-encoding-apps.md +++ b/docs/04-go1.15-fixing-bad-transfer-encoding.md @@ -1,3 +1,11 @@ +--- +title: (go1.15) Fixing Bad Transfer-Encoding +expires_at: 2025-11-20 +tags: [routing-release,1.15] +--- + +# (go1.15) Fixing Bad Transfer-Encoding + ### Context To read more about the problem that this doc is fixing, see the [release notes for routing-release 0.209.0](https://github.com/cloudfoundry/routing-release/releases/tag/0.209.0). @@ -6,7 +14,7 @@ In general, to resolve this issue you need to review applications experiencing t 1. For streaming results from the server to a client, use Spring's built-in support for this. Using a ResponseBodyEmitter or a SseEmitter, you can easily stream content back to your clients and Spring & Tomcat will ensure that the transfer-encoding header is set correctly. -2. If you created a route service based on this example code, https://github.com/nebhale/route-service-example (no longer published due to this bug), you will be impacted as the example code was copying all response headers, include transfer-encoding headers from the proxied response to the client response (see the πŸ‘ˆ line below). +2. If you created a route service based in the following format, you will be impacted as the example code was copying all response headers, include transfer-encoding headers from the proxied response to the client response (see the πŸ‘ˆ line below). ``` return this.webClient .method(request.getMethod()) diff --git a/docs/golang1.15-remove-x509ignoreCN=0-flag-certificates-now-require-SANs.md b/docs/04-go1.15-x509-commonname-deprecation.md similarity index 96% rename from docs/golang1.15-remove-x509ignoreCN=0-flag-certificates-now-require-SANs.md rename to docs/04-go1.15-x509-commonname-deprecation.md index fe6f0e884..8a970f1a1 100644 --- a/docs/golang1.15-remove-x509ignoreCN=0-flag-certificates-now-require-SANs.md +++ b/docs/04-go1.15-x509-commonname-deprecation.md @@ -1,4 +1,10 @@ -# golang 1.15 X.509 CommonName deprecation +--- +title: (go1.15) X.509 CommonName deprecation +expires_at: 2027-03-07 +tags: [routing-release,1.15] +--- + +# (go1.15) X.509 CommonName deprecation This doc helps operators understand why certificates used by network Load Balancers and the gorouter to serve TLS traffic must contain at least one diff --git a/docs/go-1.20-expect-100-continue-known-issue.md b/docs/04-go1.20-multiple-expect-100-continue.md similarity index 95% rename from docs/go-1.20-expect-100-continue-known-issue.md rename to docs/04-go1.20-multiple-expect-100-continue.md index 25ff18885..a00f3259b 100644 --- a/docs/go-1.20-expect-100-continue-known-issue.md +++ b/docs/04-go1.20-multiple-expect-100-continue.md @@ -1,4 +1,10 @@ -# Known Issue: Multiple Expect 100-continue responses +--- +title: (go1.20) Multiple Expect 100-continue responses +expires_at: 2028-06-29 +tags: [routing-release,1.20] +--- + +# (go1.20) Multiple Expect 100-continue responses ## πŸ› Bug 1 Summary Previously clients that sent a request with the header β€œExpect: 100-continue” @@ -61,7 +67,7 @@ However, if the server app takes more than 1 second to send a response with stat then there is a chance that the client will again get 2 responses with status code 100. ## πŸ“– RFC Says -[The RFC says that proxies like gorouter must not filter 1XX responses.]([url](https://datatracker.ietf.org/doc/html/rfc7231#section-6.2)) +The RFC says that proxies like gorouter must not filter 1XX responses.[url](https://datatracker.ietf.org/doc/html/rfc7231#section-6.2) > β€œA proxy MUST forward 1xx responses unless the proxy itself requested > the generation of the 1xx response. For example, if a proxy adds an diff --git a/docs/healthy-app-route-pruning.md b/docs/04-routing-0.262.0-healthy-app-route-pruning.md similarity index 91% rename from docs/healthy-app-route-pruning.md rename to docs/04-routing-0.262.0-healthy-app-route-pruning.md index f5a9d54a5..dbf8b673f 100644 --- a/docs/healthy-app-route-pruning.md +++ b/docs/04-routing-0.262.0-healthy-app-route-pruning.md @@ -1,10 +1,17 @@ -# Issue +--- +title: (routing-release-0.262.0) Healthy App Route Pruning +expires_at: 2028-05-08 +tags: [routing-release,0.262.0] +--- + +# (routing-release-0.262.0) Healthy App Route Pruning + Cloud Foundry environments may experience many 503 errors with `x_cf_routererror:"no_endpoints"` even though all of the apps appear to up and functional without error. There is an entry in the route table for the desired route, but there are no healthy endpoints available. This is caused by Changes introduced in routing-release 0.262.0 to enable Gorouter to retry more types of idempotent requests to failed backends. -# How to detect if your app has experienced this bug +## How to detect if your app has experienced this bug The following commands can be run on the gorouter log file to check for possible occurrences. What you need to look for is when data.error has a value of "context canceled" followed by a prune-failed-endpoint error. @@ -25,6 +32,6 @@ egrep -A5 -Hn 27116dd3-f047-4a35-7873-e9ef7e1d3f71 ./router.d60e75ac-5459-49f8-b ./router.d60e75ac-5459-49f8-b029-543579d74ed0.2023-05-05-18-05-52/gorouter/gorouter.stdout.log-193-{"log_level":3,"timestamp":"2023-05-04T19:38:42.838565797Z","message":"prune-failed-endpoint","source":"vcap.gorouter.registry","data":{"route-endpoint":{"ApplicationId":"d45e4b57-3420-40b3-b13d-9ef0562d58c5",REDACTED,"process_instance_id":"2ea1596c-a745-4fdc-53a4-d885","process_type":"web","source_id":"d45e4b57-3420-40b3-b13d-9ef0562d58c5",REDACTED,"RouteServiceUrl":""}}} ``` -# Resolution +## Resolution To resolve this issue, upgrade routing-release to v0.266.0 or above. diff --git a/docs/tcp-router-port-conflict-known-issue.md b/docs/04-routing-0.277.0-tcp-router-port-conflict.md similarity index 92% rename from docs/tcp-router-port-conflict-known-issue.md rename to docs/04-routing-0.277.0-tcp-router-port-conflict.md index af404979d..7ac33ecba 100644 --- a/docs/tcp-router-port-conflict-known-issue.md +++ b/docs/04-routing-0.277.0-tcp-router-port-conflict.md @@ -1,8 +1,47 @@ -# Known Issue: TCP Router Fails when Port Conflicts with Local Process +--- +title: (routing-release-0.277.0) TCP Router Port Conflict +expires_at: 2028-08-17 +tags: [routing-release,0.277.0] +--- + + + +* [(routing-release-0.277.0) TCP Router Port Conflict](#routing-release-02770-tcp-router-port-conflict) + * [πŸ“‘ Context](#-context) + * [πŸ”₯ Affected Versions](#-affected-versions) + * [βœ”οΈ Operator Checklist](#-operator-checklist) + * [πŸ› Bug Variation 1 - TCP Router claims the port first](#-bug-variation-1---tcp-router-claims-the-port-first) + * [Symptoms](#symptoms) + * [Explanation](#explanation) + * [🐞 Bug Variation 2 - Internal component claims the port first](#-bug-variation-2---internal-component-claims-the-port-first) + * [Symptoms](#symptoms-1) + * [Explanation](#explanation-1) + * [🧰 Fix](#-fix) + * [Overview](#overview) + * [New Bosh Properties](#new-bosh-properties) + * [Runtime Check Details](#runtime-check-details) + * [Deploytime Check Details](#deploytime-check-details) + * [πŸ—¨οΈ FAQ](#-faq) + * [πŸ“ Appendix A: Default System Component Ports](#-a-namelist-of-portsaappendix-a-default-system-component-ports) + + +# (routing-release-0.277.0) TCP Router Port Conflict + +## πŸ“‘ Context + +Each TCP route requires one port on the TCP Router VM. Ports for TCP routes are managed via [router groups](https://github.com/cloudfoundry/routing-api/blob/main/docs/api_docs.md#create-router-groups). Each router group has a list of `reservable_ports`. +The [Cloud Foundry documentation for "Enabling and Configuring TCP Routing"](https://docs.cloudfoundry.org/adminguide/enabling-tcp-routing.html#-modify-tcp-port-reservations) has the following warning and suggestions for valid port ranges: + +> Do not enter reservable_ports that conflict with other TCP router instances or ephemeral port ranges. Cloud Foundry recommends using port ranges within 1024-2047 and 18000-32767 on default installations. + +These port suggestions do not overlap with any ports used by system components. +However, there is nothing (until now) preventing users from expanding this range into ports that *do* overlap with ports used by system components. + +This port conflict can result in two different buggy outcomes. ## πŸ”₯ Affected Versions -* All versions of routing-release +* All versions of routing-release before 0.277.0 ## βœ”οΈ Operator Checklist * [ ] Read this doc. @@ -13,17 +52,6 @@ * [ ] Fix invalid router groups. See routing-api documentation [here](https://github.com/cloudfoundry/routing-api/blob/main/docs/api_docs.md#update-router-group). * [ ] Re-run the check to make sure all router groups are valid. See how [here](#how-to-rerun). -## πŸ“‘ Context - -Each TCP route requires one port on the TCP Router VM. Ports for TCP routes are managed via [router groups](https://github.com/cloudfoundry/routing-api/blob/main/docs/api_docs.md#create-router-groups). Each router group has a list of `reservable_ports`. -The [Cloud Foundry documentation for "Enabling and Configuring TCP Routing"](https://docs.cloudfoundry.org/adminguide/enabling-tcp-routing.html#-modify-tcp-port-reservations) has the following warning and suggestions for valid port ranges: - -> Do not enter reservable_ports that conflict with other TCP router instances or ephemeral port ranges. Cloud Foundry recommends using port ranges within 1024-2047 and 18000-32767 on default installations. - -These port suggestions do not overlap with any ports used by system components. -However, there is nothing (until now) preventing users from expanding this range into ports that *do* overlap with ports used by system components. - -This port conflict can result in two different buggy outcomes. ## πŸ› Bug Variation 1 - TCP Router claims the port first @@ -64,7 +92,7 @@ The fix for this issues focuses on preventing the creation of router groups that * a runtime check for creating and updating router groups * a deploytime check for exising router groups -These fixes are available in routing release XYZ+ (will update when released). If you cannot update at this time, you can fix your routing groups manually. See [here](#how-to-manually-fix) for instructions. +These fixes are available in routing release v0.277.0+. If you cannot update at this time, you can fix your routing groups manually. See [here](#how-to-manually-fix) for instructions. ### New Bosh Properties @@ -227,7 +255,7 @@ Some of these ports are configurable and may not match what is running on your d | 14823 | loggr-forwarder-agent | metrics.port | no | See bosh property [here](https://github.com/cloudfoundry/loggregator-agent-release/blob/acfbb6b015d897c11f715ac9e1a226eb5b96875c/jobs/loggr-forwarder-agent/spec#L51-L53) | | 14824 | loggregator_agent | metrics.port | no | See bosh property [here](https://github.com/cloudfoundry/loggregator-agent-release/blob/acfbb6b015d897c11f715ac9e1a226eb5b96875c/jobs/loggregator_agent/spec#L78-L80). | | 14829 | loggr-udp-forwarder | metrics.port | no | See bosh property [here](https://github.com/cloudfoundry/loggregator-agent-release/blob/acfbb6b015d897c11f715ac9e1a226eb5b96875c/jobs/loggr-udp-forwarder/spec#L44-L46). | -| 14830 | otel-collector | TBD | n/a | This port is used for the collector's metrics. This port was previously used by loggr-udp-forwarder, however it was disabled there. See bosh property [here](TBD). See [this issue](https://github.com/cloudfoundry/loggregator-agent-release/issues/44) for more historical information. | +| 14830 | otel-collector | TBD | n/a | This port is used for the collector's metrics. This port was previously used by loggr-udp-forwarder, however it was disabled there. See [this issue](https://github.com/cloudfoundry/loggregator-agent-release/issues/44) for more historical information. | | 14920* | system-metrics-scraper | metrics_port | no | *This job does not run on TCP router or Gorouter! However you should not use it for an agent that will be deployed along side that job. See bosh property [here](https://github.com/cloudfoundry/system-metrics-scraper-release/blob/473caa08af286e617e7391111639a70846d35de0/jobs/loggr-system-metric-scraper/spec#L58-L60). | | ~14921*~ | ~system-metrics-scraper~ | ~n/a~ | ~n/a~ | *This port was considered for a debug port, but it turns out it's in use by leadership-election which does not run on tcp-router. It is not reserved in TCP Router. See [this issue](https://github.com/cloudfoundry/system-metrics-scraper-release/issues/2) for more information. | | 14922 | system-metrics-agent | debug_port | no | See bosh property [here](https://github.com/cloudfoundry/system-metrics-release/blob/4e22e11ba4d72c5bd6895b94a75d67c212cfaa22/jobs/loggr-system-metrics-agent/spec#L20) | diff --git a/docs/05-high-availbility-scaling.md b/docs/05-high-availbility-scaling.md new file mode 100644 index 000000000..7675269e7 --- /dev/null +++ b/docs/05-high-availbility-scaling.md @@ -0,0 +1,13 @@ +--- +title: High Availability & Scaling +expires_at: never +tags: [routing-release] +--- + +# High Availability & Scaling + +The TCP Router and Routing API are stateless and horizontally scalable. The TCP +Routers must be fronted by a load balancer for high-availability. The Routing +API depends on a database, that can be clustered for high-availability. For high +availability, deploy multiple instances of each job, distributed across regions +of your infrastructure. diff --git a/docs/demo.md b/docs/demo.md deleted file mode 100644 index f8719e899..000000000 --- a/docs/demo.md +++ /dev/null @@ -1,120 +0,0 @@ -# TCP Routing demo -This page gives step by step instructions to do the TCP routing demo as done in Cloud Foundry Summit 2016. - -The demo at Cloud Foundry Summit 2016 was to push MQTT broker (`mosquitto`) as -CF app and create and bind a TCP route to it. To showcase that MQTT broker -running as CF app is accessible for publishing and subscribing using TCP route, -a subscriber web app and publisher android app was used. - -## Pushing MQTT broker as CF app -We will be using [mosquitto](http://mosquitto.org/) broker's docker image to -push mqtt broker as CF app. We will use -[toke/mosquitto](https://github.com/toke/docker-mosquitto) docker image. - -1. Create a tcp domain if you don't have one. - - To discover whether you have a TCP domain available: - ``` - cf domains - Getting domains in org my-org as my-user... - name status type - example.com shared - tcp.example.com shared tcp - ``` - - If you don't find a domain of type tcp, create one as admin user: - ``` - cf create-shared-domain --router-group default-tcp - ``` - Replace `` with the name of the domain you want to give to your - tcp domain. Of course, here we are assuming that dns entries for above - created tcp domain will resolve to load balancer in front of tcp router - groups or if tcp routers have public IP addresses then it will resolve to tcp - routers. This has to be done by the operator/administrator of your Cloud - Foundry deployment. - -1. Push mosquitto as CF app as follows: - ``` - cf push mqttbroker --docker-image toke/mosquitto -d --random-route - ``` - This will download the required docker image and push it as CF app and create and bind a tcp route. - -1. Now you are ready to supply this tcp route information to your publisher and subscriber. - -## Pushing MQTT subscriber app - -This web app subscribes to `accelerometer` topic of MQTT broker and displays the -data published on this topic in a chart. It expects numeric data to be published -on this topic. - -1. Fetch the repo for [sample-mqtt-subscriber](https://github.com/GESoftware-CF/sample-mqtt-subscriber) - ``` - mkdir -p ~/workspace - cd ~/workspace - git clone https://github.com/GESoftware-CF/sample-mqtt-subscriber.git - cd sample-mqtt-subscriber/ - ``` - -1. Build the project as follows. - - Install maven if you don't already have it. Maven require java: - - ``` - brew install Caskroom/cask/java - brew install maven - ``` - - Once you have maven installed: - ``` - mvn clean package - ``` - -1. Push the resulting jar as CF app - ``` - cf push mqttsub -p target/mqttsubscriber-0.0.1-SNAPSHOT.jar - ``` - -1. Verify that the app is successfully deployed and running by hitting endpoint `mqttsub.`. You should see web page like this: - -![Image of mqttsubscriber landing page] -(images/mqttsub_landing_page.png) - -## Installing MQTT publisher android app - -This android app registers itself to accelerometer sensor of the device and -publishes y-axis acceleration to `accelerometer` topic of MQTT broker. - -1. Fetch the repo for [sample-android-mqtt](https://github.com/atulkc/sample-android-mqtt) - ``` - mkdir -p ~/workspace - cd ~/workspace - git clone https://github.com/atulkc/sample-android-mqtt.git - cd sample-android-mqtt/ - ``` - -1. Load the project in android studio. - -1. Install the application on your favorite android phone using android studio. - -1. Verify that the app is successfully installed and running by tapping the `Accelerometer` icon on your smartphone. You should see something like this: - - Image of android app landing page - - -## Putting it all together -This is where we tie together the subscriber web app, android app and mqtt broker. - -1. Enter `` as host name on landing page of web app and port of tcp route as `port`. You should see an empty chart as follows: - - ![Image of mqttsubscriber landing page] - (images/mqttsub_empty_chart_page.png) - -1. Now enter same information on android accelerometer app. You should see the next screen on android app indicating the y-axis acceleration: - - Image of android app connected page - -1. The y-axis acceleration of your device should now start showing up on chart on web app: - - ![Image of chart of web app] - (images/mqttsub_chart_page.png) - diff --git a/docs/historical_deployment_info.md b/docs/historical_deployment_info.md deleted file mode 100644 index 565b533e2..000000000 --- a/docs/historical_deployment_info.md +++ /dev/null @@ -1,307 +0,0 @@ -These are historical instructions for deploying Routing for Cloud Foundry. -Routing is built into -[cf-deployment](https://github.com/cloudfoundry/cf-deployment) and no longer -needs to be installed separately. - -## Deploying Routing for Cloud Foundry - -1. For [high availability](#high-availability), configure a load balancer in - front of the routers. If high-availability is not required allocate a public - IP to a single instance of each router. See [Port Requirements for TCP - Routing](#port-requirements-for-tcp-routing). - -1. If you are using a load balancer see [Configuring Load Balancer - Healthcheck](https://docs.cloudfoundry.org/adminguide/configure-lb-healthcheck.html). - -1. Choose domain names from which developers will configure HTTP and TCP routes - for their applications. Separate domain names will be required for HTTP and - TCP routing. Configure DNS to resolve these domain names to the load balancer - in front of the routers. You may use the same or separate load balancers for - the HTTP and TCP domains. If high-availability is not required configure DNS - to resolve the domains directly to a single instance of the routers. - -1. If your manifest is configured with self-signed certificates for UAA, - configure routing components to skip validation of the TLS certificate; see - [Validation of TLS Certificates from Route Services and - UAA](#validation-of-tls-certificates-from-route-services-and-uaa). - -1. Deploy Cloud Foundry using the instructions for - [cf-deployment](https://github.com/cloudfoundry/cf-deployment/blob/master/deployment-guide.md). - -### Port Requirements for TCP Routing - -Choose how many TCP routes you'd like to offer. For each TCP route, a port must -be opened on your load balancer. Configure your load balancer to forward the -range of ports you choose to the IP addresses of the TCP Router instances. - -Routing API must be configured with the same range of ports. By default -`cf-deployment` will enable 100 ports in the range 1024-1123. If you choose a -range other than 1024-1123, you must configure this using the deployment -manifest property `routing-api.router_groups.reservable_ports`. This is a seeded -value only; after deploy, changes to this property will be ignored. To modify -the reservable port range after deployment, use the [Routing -API](https://github.com/cloudfoundry/routing-api#using-the-api-manually); (see -"To update a Router Group's reservable_ports field with a new port range"). - -```yaml -- name: routing_api - properties: - routing_api: - router_groups: - - name: default-tcp - reservable_ports: 1024-1123 - type: tcp - - name: test1 - reservable_ports: - - 1066 - - 1266 - type: tcp - - name: test2 - reservable_ports: 1111-2222,4444 - type: tcp - -``` - -### Validation of TLS Certificates from Route Services and UAA - -The following components communicate with UAA via TLS: -- Routing API -- GoRouter -- TCP Router - -Additionally, GoRouter communicates with [Route -Services](http://docs.cloudfoundry.org/services/route-services.html) via TLS. - -In all cases, these components will validate that certificates are signed by a -known CA and that they match the requested domains. To disable this validation, -as when deploying the routing subsystem to an environment with self-signed -certificates, configure the `skip_ssl_validation` property for GoRouter, -Routing API and TCP Router. - - -```yaml -- name: routing-api - properties: - skip_ssl_validation: true -- name: tcp_router - properties: - skip_ssl_validation: true -- name: gorouter - properties: - router: - ssl_skip_validation: true -``` - -## Post Deploy Steps - -### Create a Shared Domain in CF - - After deploying this release you must add the domain you chose (see [Domain - Names](#domain-names)) to CF as a Shared Domain, associating it - with the Router Group. - - The CLI commands below require version 6.17+ of the [`cf` - CLI](https://github.com/cloudfoundry/cli), and must be run as `admin`. - - List available router-groups - - ``` - $ cf router-groups - Getting router groups as admin ... - - name type - default-tcp tcp - ``` - - **Note**: If you receive this error: `FAILED This command requires the - Routing API. Your targeted endpoint reports it is not enabled`. This is due - to the CF CLI's `~/.cf/config.json` having an old cached `RoutingEndpoint` - value. To fix this, just do a `cf login` again and this error should go away. - - Create a shared-domain for the TCP router group - - ``` - $ cf create-shared-domain tcp-apps-domain.com --router-group default-tcp - Creating shared domain tcp-apps-domain.com as admin... - OK - ``` - - See [Router Groups](#router-groups) for details on that concept. - -## Manual Configuration of BOSH Deployment Manifest - -If you use the canonical manifest provided with cf-deployment the following prerequisites will be configured -for you automatically. - -### UAA - -1. UAA must be configured to terminate TLS for internal requests. Set the - following properties in your environment stub for cf-release when using the - manifest generation scripts, or set it directly in your manifest. The - routing-release's manifest generation scripts will set `uaa.tls_port` to the - value of `uaa.ssl.port` from the cf-release manifest. - - ``` - - name: uaa - properties: - uaa: - ssl: - port: - sslCertificate: | - - sslPrivateKey: | - - ``` -1. You must add the `routing.router_groups.read` and - `routing.router_groups.write` scopes to your admin user. - - ``` - - name: uaa - properties: - uaa: - scim: - users: - - name: admin - password: PASSWORD - groups: - - scim.write - - scim.read - - openid - - cloud_controller.admin - - clients.read - - clients.write - - doppler.firehose - - routing.router_groups.read - - routing.router_groups.write - ``` - -1. The following OAuth clients must be configured for UAA. All but the `cf` - client are new; the important change to the `cf` client is adding the - `routing.router_groups.read` and `routing.router_groups.write` scopes. If - you're using the manifest generation scripts for cf-release, you can skip - this step as the necessary clients are in the Spiff templates. If you're - handrolling your manifest for cf-release, you'll need to add them. - - ``` - - name: uaa - properties: - uaa: - clients: - cc_routing: - authorities: routing.router_groups.read - authorized-grant-types: client_credentials - secret: - cf: - override: true - authorized-grant-types: password,refresh_token - scope: cloud_controller.read,cloud_controller.write,openid,password.write,cloud_controller.admin,cloud_controller.admin_read_only,scim.read,scim.write,doppler.firehose,uaa.user,routing.router_groups.read,routing.router_groups.write - authorities: uaa.none - access-token-validity: 600 - refresh-token-validity: 2592000 - gorouter: - authorities: routing.routes.read - authorized-grant-types: client_credentials,refresh_token - secret: - tcp_emitter: - authorities: routing.routes.write,routing.routes.read - authorized-grant-types: client_credentials,refresh_token - secret: - tcp_router: - authorities: routing.routes.read - authorized-grant-types: client_credentials,refresh_token - secret: - ``` -1. UAA must be configured to accept requests using an internal hostname. The - manifest generation scripts for cf-release will do this for you (both BOSH - Lite and non). However, if you override the `uaa.zones.internal.hostnames` - property yourself, be sure to include `uaa.service.cf.internal` in your - stub. - - ``` - - name: uaa - properties: - uaa: - internal_url: https://uaa.service.cf.internal:8443 - ca_cert: "((uaa_ca.certificate))" - ``` - -### Routing API Database - -1. Routing API requires a relational database as a data store; MySQL and PostgreSQL are supported. Routing API does not create the database; one must exist on startup. cf-deployment uses [CF MySQL Release](https://github.com/cloudfoundry/cf-mysql-release) by default. For any deployment you can use this or provide your own MySQL or PostgreSQL database. Configure the credentials for the database with the following properties. - - ``` - - name: routing-api - properties: - routing_api: - sqldb: - type: - host: - port: - schema: - username: - password: - ``` - - If you are using [cf-mysql-release](https://github.com/cloudfoundry/cf-mysql-release), then the values for these properties can be obtained from the following properties in the manifest for that release. - - `type` should be `mysql` - - `host` corresponds to the IP address of the `proxy_z1` job - - `port` is `3306` - - `schema` corresponds to `cf_mysql.mysql.seeded_databases[].name` - - `username` corresponds to `cf_mysql.mysql.seeded_databases[].username` - - `password` corresponds to `cf_mysql.mysql.seeded_databases[].password` - -1. If you use the CF MySQL Release, you can seed the required database on deploy using the manifest property `cf_mysql.mysql.seeded_databases`. Do not use the same deployment of cf-mysql-release that is exposed as a CF marketplace service. Instead, use a deployment intended for internal platform use; for these deployments you should set broker instances to zero. Update the following manifest properties before deploying. - - ``` - - name: database - properties: - cf_mysql: - mysql: - seeded_databases: - - name: routing-api - username: - password: - ``` - -### Enable Support for TCP Routing in Route Emitter - -The Diego Route Emitter component must be configured to emit TCP routes in order to support TCP routing. - - ``` - - name: route_emitter - properties: - tcp: - enabled: true - ``` - -## Router Groups - -A Router Group represents a horizontally scalable cluster of identically -configured routers. Only one router group is currently supported. Shared -domains in Cloud Foundry are associated with one router group; see [Post Deploy -Configuration](#post-deploy-configuration). To create a TCP route for their -application, a developer creates it from a TCP domain; see [Create a TCP -Route](#create-a-tcp-route). For each TCP route, Cloud Foundry reserves a port -on the CF router. Each port is dedicated to that route; route ports may not be -shared by multiple routes. The number of ports available for reservation -dictates how many TCP routes can be created. - -A router group is limited to maximum port range 1024-65535; defaulting to -1024-1123. As one router group is supported, the maximum number of TCP routes -than can be created in CF is 64512 (65535-1024). Though multiple Shared Domains -can be assigned to the router group, they share a common pool of ports. E.g. -given Shared Domains `tcp-1.example.com` and `tcp-2.example.com` are assigned to -the `default-tcp` router group, and a route for port 1024 is created from -domain `tcp-1.example.com`, the same port could not be reserved for a route -from domain `tcp-2.example.com`. Eventually we may support multiple router -groups and/or TCP routes that share a port. - -The same reservable port range must be configured both on the load balancer, -and in this release using the manifest property -`routing-api.router_groups.reservable_ports`. The port range can be modified -after deploying using [the Routing -API](https://github.com/cloudfoundry/routing-api#using-the-api-manually). - -**Note:** when modifying the port range using the Routing API, consider that -the new port range must include those ports that have already been reserved. - diff --git a/src/code.cloudfoundry.org/gorouter b/src/code.cloudfoundry.org/gorouter index c58cdbb1c..f1cee7fed 160000 --- a/src/code.cloudfoundry.org/gorouter +++ b/src/code.cloudfoundry.org/gorouter @@ -1 +1 @@ -Subproject commit c58cdbb1c782e980f64abbf3fa6c36346524b76b +Subproject commit f1cee7fed03bd54e6c7db34ad46aeaac3dd1879b diff --git a/src/code.cloudfoundry.org/multierror b/src/code.cloudfoundry.org/multierror index 633a03531..4146ece3d 160000 --- a/src/code.cloudfoundry.org/multierror +++ b/src/code.cloudfoundry.org/multierror @@ -1 +1 @@ -Subproject commit 633a03531b34e25057fda58455256a515b104ad1 +Subproject commit 4146ece3d02a2f816257f7503e2e5a209669ae33 diff --git a/src/code.cloudfoundry.org/route-registrar b/src/code.cloudfoundry.org/route-registrar index 9863c875c..b2cf58b67 160000 --- a/src/code.cloudfoundry.org/route-registrar +++ b/src/code.cloudfoundry.org/route-registrar @@ -1 +1 @@ -Subproject commit 9863c875c5876689aab9c1dafacd2b15164f2a08 +Subproject commit b2cf58b67a7e74cf0a84763b0e4a1a2643f5a47f diff --git a/src/code.cloudfoundry.org/routing-acceptance-tests b/src/code.cloudfoundry.org/routing-acceptance-tests index 74228bf0b..123598e54 160000 --- a/src/code.cloudfoundry.org/routing-acceptance-tests +++ b/src/code.cloudfoundry.org/routing-acceptance-tests @@ -1 +1 @@ -Subproject commit 74228bf0b03c28d0db270bc731c243935522ce60 +Subproject commit 123598e54383dfc239236eff3df9582578525773 diff --git a/src/code.cloudfoundry.org/routing-api b/src/code.cloudfoundry.org/routing-api index 4008efac0..567e4a6e1 160000 --- a/src/code.cloudfoundry.org/routing-api +++ b/src/code.cloudfoundry.org/routing-api @@ -1 +1 @@ -Subproject commit 4008efac0b84793806c49445be23404d29f8c32b +Subproject commit 567e4a6e1498709d65b031f00f745809ad8b5060 diff --git a/src/code.cloudfoundry.org/routing-api-cli b/src/code.cloudfoundry.org/routing-api-cli index bb8e53412..b1ec1a6da 160000 --- a/src/code.cloudfoundry.org/routing-api-cli +++ b/src/code.cloudfoundry.org/routing-api-cli @@ -1 +1 @@ -Subproject commit bb8e53412d0df196140cab063d17ee6a9d170d1b +Subproject commit b1ec1a6da2c91737b29aa1afb56d7f070c94ef33