No description, website, or topics provided.
aaronshurley import the proper package
- this became an issue when we removed the symlinks from routing-release
packaging

[#159337504]
Latest commit b308b1a Jul 26, 2018
Permalink
Failed to load latest commit information.
admin admin listener is on localhost tcp port, not unix socket Oct 23, 2017
bin Enable locket TLS only when db CA is specified Oct 24, 2017
cmd/routing-api import the proper package Jul 26, 2018
config allow for individual ports array Jan 29, 2018
db Fix non-tls connections to postgres Oct 27, 2017
docs added ttl and isolation_segment to example response for list tcp routes May 24, 2017
example_config Revert "Revert "Allow tls connection to mysql and postgres"" Oct 24, 2017
fake_routing_api Changes the way RoutingAPI config is shared in test suite Oct 4, 2017
handlers replace hardcoded certs, generate instead Jun 25, 2018
helpers Split lock acquire and lock release Oct 14, 2016
matchers Update the isolation segment for an existing tcp route Jun 6, 2017
metrics Remove etcd client and all associated enablers [#151415096] Oct 12, 2017
migration Revert "Revert "Allow tls connection to mysql and postgres"" Oct 24, 2017
models allow for individual ports array Jan 29, 2018
test_helpers admin listener is on localhost tcp port, not unix socket Oct 23, 2017
.gitignore Renamed total_routes and total_subscriptions Feb 8, 2016
LICENSE Update NOTICE Jan 19, 2017
NOTICE Update NOTICE Jan 19, 2017
README.md remove incubator Feb 3, 2018
client.go TCP routes can be filtered by isolation segment param May 18, 2017
client_test.go TCP routes can be filtered by isolation segment param May 18, 2017
client_tls_test.go Move routing-api to code.cloudfoundry.org import path Aug 4, 2016
errors.go Generate guid for router group on creation Apr 28, 2017
event_source.go Move routing-api to code.cloudfoundry.org import path Aug 4, 2016
event_source_test.go Refactor: Handle errors better in SQL facing packages Oct 25, 2016
routes.go Changes the way RoutingAPI config is shared in test suite Oct 4, 2017
routing_api_suite_test.go Refactor EventSource to return RoutingApi Events Apr 2, 2015

README.md

CF Routing API Server

The purpose of the Routing API is to present a RESTful interface for registering and deregistering routes for both internal and external clients. This allows easier consumption by different clients as well as the ability to register routes from outside of the CF deployment.

Note: This repository should be imported as code.cloudfoundry.org/routing-api.

Downloading and Installing

External Dependencies

  • Go should be installed and in the PATH
  • This repo is part of routing-release bosh release repo, which also acts as cannonical GOPATH. So to work on routing-api you will need to checkout routing-release and follow instructions in its README to setup GOPATH.

Development Setup

Refer to routing-release README for development setup.

Development

To run the tests you need a running RDB(either Postgres or MySQL). Currently there is a helper script under routing-release which runs tests in docker container. cf-routing-pipeline docker image used in the below script is configured with correct version of MySQL and Postgres for testing purposes. To run the tests for routing-api

./scripts/unit-tests-in-docker routing-api

If you choose to run unit-tests without docker(mentioned above), you will need to run SQL locally with the below configuration: MySQL Postgres

Running the API Server

Server Configuration

jwt token

To run the routing-api server, a configuration file with the public uaa jwt token must be provided. This configuration file can then be passed in with the flag -config [path_to_config]. An example of the configuration file can be found under example_config/example.yml for bosh-lite.

To generate your own config file, you must provide a uaa_verification_key in pem format, such as the following:

uaa_verification_key: "-----BEGIN PUBLIC KEY-----

      MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHFr+KICms+tuT1OXJwhCUtR2d

      KVy7psa8xzElSyzqx7oJyfJ1JZyOzToj9T5SfTIq396agbHJWVfYphNahvZ/7uMX

      qHxf+ZH9BL1gk9Y6kCnbM5R60gfwjyW1/dQPjOzn9N394zd2FJoFHwdq9Qs0wBug

      spULZVNRxq7veq/fzwIDAQAB

      -----END PUBLIC KEY-----"

This can be found in your Cloud Foundry manifest under uaa.jwt.verification_key

Oauth Clients

The Routing API uses OAuth tokens to authenticate clients. To obtain a token from UAA that grants the API client permission to register routes, an OAuth client must first be created for the API client in UAA. An API client can then authenticate with UAA using the registered OAuth client credentials, request a token, then provide this token with requests to the Routing API.

Registering OAuth clients can be done using the cf-release BOSH deployment manifest, or manually using the uaac CLI for UAA.

  • For API clients that wish to register/unregister routes with the Routing API, the OAuth client in UAA must be configured with the routing.routes.write authority.
  • For API clients that wish to list routes with the Routing API, the OAuth client in UAA must be configured with the routing.routes.read authority.
  • For API clients that wish to list router groups with the Routing API, the OAuth client in UAA must be configured with the routing.router_groups.read authority.

For instructions on fetching a token, see Using the API manually.

Configure OAuth clients in the cf-release BOSH Manifest

E.g:

uaa:
   clients:
      routing_api_client:
         authorities: routing.routes.write,routing.routes.read,routing.router_groups.read
         authorized_grant_type: client_credentials
         secret: route_secret
Configure OAuth clients manually using uaac CLI for UAA
  1. Install the uaac CLI

    gem install cf-uaac
    
  2. Get the admin client token

    uaac target uaa.bosh-lite.com
    uaac token client get admin # You will need to provide the client_secret, found in your CF manifest.
  3. Create the OAuth client.

    uaac client add routing_api_client --authorities "routing.routes.write,routing.routes.read,routing.router_groups.read" --authorized_grant_type "client_credentials"

Starting the Server

To run the API server you need to provide RDB configuration for the Postgres or MySQL, a configuration file containing the public UAA jwt key, plus some optional flags.

Example 1:

routing-api -ip 127.0.0.1 -systemDomain 127.0.0.1.xip.io -config example_config/example.yml -port 3000 -maxTTL 60

Profiling the Server

The Routing API runs the cf_debug_server, which is a wrapper around the go pprof tool. In order to generate this profile, do the following:

# Establish a SSH tunnel to your server (not necessary if you can connect directly)
ssh -L localhost:8080:[INTERNAL_SERVER_IP]:17002 vcap@[BOSH_DIRECTOR]
# Run the profile tool.
go tool pprof http://localhost:8080/debug/pprof/profile

Note: Debug server should run on loopback interface i.e., 0.0.0.0 for the SSH tunnel to work. Current default value for interface is set to localhost

Using the API

The Routing API uses OAuth tokens to authenticate clients. To obtain a token from UAA an OAuth client must first be created for the API client in UAA. For instructions on registering OAuth clients, see Server Configuration.

Using the API with the rtr CLI

A CLI client called rtr has been created for the Routing API that simplifies interactions by abstracting authentication.

Using the API manually

Please refer to the API documentation.

Known issues

  • The routing-api will return a 404 if you attempt to hit the endpoint http://[router host]/routing/v1/routes/ as opposed to http://[router host]/routing/v1/routes