F5 BIG-IP Controller for Cloud Foundry¶

Features¶

• Dynamically creates, manages, and destroys BIG-IP objects.
• Forwards traffic from the BIG-IP device to Cloud Foundry clouds via Diego cell virtual machine addressing.
• Supports Cloud Foundry HTTP and TCP routing.
• Supports use of BIG-IP profiles and policies with Cloud Foundry routes.

Guides¶

See the F5 BIG-IP Controller for Cloud Foundry user documentation.

Overview¶

The cf-bigip-ctlr is a Docker container that runs in a Cloud Foundry cell. It emulates the behavior of the Cloud Foundry Gorouter, by:

• subscribing to the Cloud Foundry NATS message bus and routing API;
• gathering application route information (HTTP and TCP); and
• configuring routing policy rules on the BIG-IP system.

The cf-bigip-ctlr receives route updates and transforms them into BIG-IP policy rules when the following events occur:

• push, delete, and scale applications (with mapped routes to the application);
• map and unmap routes.

For example:

1. Developer pushes “myApp” to Cloud Foundry (without the Cloud Foundry --no-route option).
2. cf-bigip-ctlr discovers new route information for myApp.
3. Controller creates a pool and pool member(s) for each myApp instance.
4. Controller updates BIG-IP routing policy directing App requests to the myApp pool.
5. Controller monitors Cloud Foundry routing table and, when it discovers changes, reconfigures the BIG-IP device.

The BIG-IP device handles traffic for every Cloud Foundry mapped route and load balances traffic to each application instance. The cf-bigip-ctlr can create a total of two (2) BIG-IP virtual servers for HTTP routes: one (1) for HTTP, one (1) for HTTPS. The Controller creates an additional virtual server for each TCP route.

All HTTP traffic goes through either the port 80 or port 443 virtual server. The Controller routes TCP traffic through dedicated virtual servers configured to listen on non-HTTP ports.

You can attach the BIG-IP objects listed below to the HTTP virtual servers the cf-bigip-ctlr creates for Cloud Foundry. To do so, create the desired objects on the BIG-IP manually before adding them to the Controller configuration in Cloud Foundry.

• policies
• profiles
• SSL profiles
• health monitors

Configuration Parameters¶

The configuration parameters below customize the cf-bigip-ctlr behavior. Define the parameters in the env section of your application manifest using the environment variable BIGIP_CTLR_CFG.

applications:
  - name: cf-bigip-ctlr
    health-check-type: http
    health-check-http-endpoint: /health
    env:
      BIGIP_CTLR_CFG: |
                      # Required for all modes
                      bigip:
                        url: https://bigip.example.com
                        user: admin
                        pass: password
                        partition:
                          - cf
                        external_addr: 192.168.1.1
                        policies:
                          - /Example/policy
                        profiles:
                          - /Example/profile
                        health_monitors:
                          - /Common/tcp_half_open

                      logging:
                        level: info

                      route_mode: all

                      # Required for HTTP routing
                      nats:
                        - host: 192.168.10.1
                          port: 4222
                          user: nats
                          pass: nats-password

                      # Required for TCP routing
                      oauth:
                        token_endpoint: uaa.system.pcf.local
                        client_name: uaa-client
                        client_secret: uaa-secret
                        port: 443
                        skip_ssl_validation: true
                        ca_certs:

                      routing_api:
                        uri: http://api.system.pcf.local
                        port: 80
                        auth_disabled: false

Route Types¶

The cf-bigip-ctlr accepts three (3) values for the route_type configuration parameter. Each of the supported route_mode options have different configuration requirements:

• all: Requires nats, routing_api, and oauth.
• http: Requires nats.
• tcp: Requires routing_api and oauth.

When managing HTTP routes, the cf-bigip-ctlr will create an HTTP virtual server (virtual address port 80) for routing into Cloud Foundry. If you define an SSL profile in the configuration (the ssl_profiles parameter), the Controller creates an additional HTTPS virtual server (virtual address port 443). You can attach multiple certificate/key pairs to the HTTPS virtual server. The BIG-IP device uses TLS Server Name Indication (SNI) to choose the correct certificate to present to the client; SNI allows the Cloud Foundry instance to support multiple hostnames (foo.mycf.com and bar.mycf.com). Some of these cert/key pairs can be wildcard (*.mycf.com).

Health Checks¶

The cf-bigip-ctlr supports native Cloud Foundry health checks for itself and will manage BIG-IP health checks for applications.

To configure Cloud Foundry health checks for the cf-bigip-ctlr (this ensures the orchestration system will manage the Controller availability for you), define the health-check-type and health-check-http-endpoint settings as follows:

health-check-type: http
health-check-http-endpoint: /health

The cf-bigip-ctlr will also manage BIG-IP health checking of the managed applications. To use any health monitor(s) that already exists on the BIG-IP system, add the name to the application manifest under bigip.health_monitors. Because these monitors apply to all applications in the system, the cf-bigip-ctlr uses the /Common/tcp_half_open monitor by default.

API Endpoints¶

• /health: The Controller health endpoint.

  The Controller returns 200 OK to indicate health; any other response is unhealthy. You can set the health Controller endpoint to the status.port property in the application configuration for development purposes. The Diego PORT value provided to the container environment will override this setting in production environments.

  curl -v http://10.0.32.15/health
  *   Trying 10.0.32.15..
  * Connected to 10.0.32.15 (10.0.32.15) port 80 (#0)
  > GET /health HTTP/1.1
  > Host: 10.0.32.15
  > User-Agent: curl/7.43.0
  > Accept: */*
  >
  < HTTP/1.1 200 OK
  < Cache-Control: private, max-age=0
  < Expires: 0
  < Date: Thu, 22 Sep 2016 00:13:54 GMT
  < Content-Length: 3
  < Content-Type: text/plain; charset=utf-8
  <
  ok
  * Connection #0 to host 10.0.32.15 left intact
  

• /routes: The routes endpoint returns the entire routing table as JSON. Each route has an associated array of host:port entries.

  Example¶

  curl "http://someuser:somepass@10.0.32.15/routes"
  {"api.catwoman.cf-app.com":[{"address":"10.244.0.138:9022","ttl":0,"tags":{"component":"CloudController"}}],"dora-dora.catwoman.cf-app.com":[{"address":"10.244.16.4:60035","ttl":0,"tags":{"component":"route-emitter"}},{"address":"10.244.16.4:60060","ttl":0,"tags":{"component":"route-emitter"}}]}
  

  Important

  Use of /routes requires HTTP basic authentication. You can find the authentication credentials in the application configuration:

  status:
     password: some_password
     user: some_user
  

Instrumentation and Logging¶

You can define the desired logging level for the cf-bigip-ctlr in the application manifest. The Controller supports the following log levels:

• info, debug - An expected event occurred.
• error - An unexpected error occurred.
• fatal - A fatal error occured which makes the Controller unable to execute.

[2017-02-01 22:54:08+0000] {"log_level":0,"timestamp":1485989648.0895808,"message":"endpoint-registered","source":"vcap.cf-bigip-ctlr.registry","data":{"uri":"0-*.login.bosh-lite.com","backend":"10.123.0.134:8080","modification_tag":{"guid":"","index":0}}}

• log_level: message log level
  • 0 = info
  • 1 = debug
  • 2 = error
  • 3 = fatal
• timestamp: Epoch time of the log
• message: Content of the log line
• source: The Controller function that initiated the log message
• data: Additional information, varies based on the message