The F5 BIG-IP Controller for Kubernetes lets you manage your F5 BIG-IP device from Kubernetes or OpenShift using either environment’s native CLI/API.
See the F5 BIG-IP Controller for Kubernetes user documentation.
The F5 BIG-IP Controller for Kubernetes is a Docker container that runs in a Kubernetes Pod. It uses F5 Resource s to determine:
The k8s-bigip-ctlr
watches the Kubernetes API for the creation, modification, or deletion of Kubernetes objects.
For some Kubernetes objects, the Controller responds by creating, modifying, or deleting objects in the BIG-IP system.
The k8s-bigip-ctlr
handles the following Kubernetes objects:
One Controller can handle a mix of these objects simultaneously. See below for specifics regarding the handling of these objects.
For example, when run in NodePort mode, the k8s-bigip-ctlr
does the following:
virtualServer
resource.The BIG-IP system handles traffic for the Service at the specified virtual address and load balances to all nodes in the cluster. Within the cluster, the allocated NodePort load balances traffic to all pods.
Danger
The k8s-bigip-ctlr
monitors the BIG-IP partition it manages for configuration changes. If it discovers changes, the Controller reapplies its own configuration to the BIG-IP system.
F5 does not recommend making configuration changes to objects in any partition managed by the k8s-bigip-ctlr
via any other means (for example, the configuration utility, TMOS, or by syncing configuration with another device or service group). Doing so may result in disruption of service or unexpected behavior.
The configuration parameters below are global to the k8s-bigip-ctlr
.
Parameter | Type | Required | Default | Description | Allowed Values |
---|---|---|---|---|---|
bigip-username | string | Required | n/a | BIG-IP iControl REST username | |
bigip-password | string | Required | n/a | BIG-IP iControl REST password [4] | |
bigip-url | string | Required | n/a | BIG-IP admin IP address | |
bigip-partition | string | Required | n/a | The BIG-IP partition in which to configure objects. | |
namespace | string | Optional | All | Kubernetes namespace(s) to watch
|
|
namespace-label | string | Optional | n/a | Tells the k8s-bigip-ctlr to watch
any namespace with this label |
|
kubeconfig | string | Optional | ./config | Path to the kubeconfig file | |
python-basedir | string | Optional | /app/python | Path to python utilities directory | |
running-in-cluster | boolean | Optional | true | Indicates whether or not a
kubernetes cluster started
k8s-bigip-ctlr |
true, false |
use-node-internal | boolean | Optional | true | filter Kubernetes InternalIP addresses for pool members | true, false |
verify-interval | integer | Optional | 30 | In seconds, interval at which to verify the BIG-IP configuration. | |
node-poll-interval | integer | Optional | 30 | In seconds, interval at which to poll the cluster for its node members. | |
node-label-selector | string | Optional | n/a | Tells the k8s-bigip-ctlr to watch
only nodes with this label |
|
log-level | string | Optional | INFO | Log level | INFO, DEBUG, CRITICAL, WARNING, ERROR |
pool-member-type | string | Optional | nodeport | The type of BIG-IP pool members you want to create. Use Use |
cluster, nodeport |
openshift-sdn-name | string | Optional | n/a | Name of the VXLAN set up on the BIG-IP system that corresponds to an Openshift SDN HostSubnet. | |
manage-routes | boolean | Optional | false | Indicates if Only applicable in OpenShift. |
true, false |
route-vserver-addr | string | Optional | n/a | Bind address for virtual server for OpenShift Route objects. Only applicable in OpenShift. |
|
route-label | string | Optional | n/a | Tells the Only applicable in OpenShift. |
|
route-http-vserver | string | Optional | ose-vserver | The name of the http virtual server for OpenShift Routes. Only applicable in OpenShift. |
|
route-https-vserver | string | Optional | https-ose-vserver | The name of the https virtual server for OpenShift Routes. Only applicable in OpenShift. |
|
default-client-ssl | string | Optional | n/a | Specify the name of a user created client ssl profile that will be attached to the route https vserver and used as default for SNI. This profile must have the Default for SNI field enabled. Only applicable in OpenShift. |
|
default-server-ssl | string | Optional | n/a | Specify the name of a user created server ssl profile that will be attached to the route https vserver and used as default for SNI. This profile must have the Default for SNI field enabled. Only applicable in OpenShift. |
Note
Use the node-label-selector
parameter if you only want the controller to manage specific nodes from the cluster.
For example, the BIG-IP device may not be able to reach certain nodes, or the BIG-IP device already manages certain
nodes. Therefore, the controller should only watch the nodes that match the environmental constraints (by using a label).
Note
If the default-client-ssl
or default-server-ssl
parameters are not provided, then the controller creates default
clientssl and serverssl profiles for the OpenShift Route HTTPS virtual server. The controller sets these profiles as
Default for SNI.
F5 Resource ConfigMap objects tell the k8s-bigip-ctlr
how to configure the BIG-IP system.
See the Integration Overview for more information about F5 resources.
Property | Description | Allowed Values |
---|---|---|
f5type | Tells k8s-bigip-ctlr about resources it
should watch |
|
schema | Verifies the data blob |
f5schemadb://bigip-virtual-server_v0.1.3.json |
data | Defines the F5 resource | |
frontend | Defines object(s) created on the BIG-IP | See Frontend |
backend | Identifes the Kubernets Service acting as the server pool | See Backend |
The frontend.virtualServer
properties define BIG-IP virtual server, pool, and pool member objects.
Property | Type | Required | Default | Description | Allowed Values |
---|---|---|---|---|---|
partition | string | Required | Define the BIG-IP partition to manage | ||
virtualAddress | JSON object | Optional | Allocate a virtual address from the BIG-IP | ||
|
string | Required | Virtual IP address | ||
|
integer | Required | Port number | ||
mode | string | Optional | tcp | Set the proxy mode | http, tcp |
balance | string | Optional | round-robin | Set the load balancing mode | round-robin |
sslProfile [1] | JSON object | Optional | BIG-IP SSL profile to apply to the virtual server. | ||
|
string | Optional | Name of the BIG-IP SSL profile you want to use. Uses format Example: |
||
|
array of strings | Optional | Array of BIG-IP SSL profile names. Each SSL profile name uses the format
Example: [
'Common/testcert1',
'Common/testcert2'
]
|
If you don’t define bindAddr
in the Frontend configuration, you must include it in a Kubernetes Annotation to the ConfigMap.
The Controller watches for the annotation key virtual-server.f5.com/ip
.
This annotation must contain the IP address you want to assign to the virtual server.
status.virtual-server.f5.com/ip
annotation set by the Controller via the Kubernetes API.
This allows you to see the bindAddr
assigned to the virtual server.If you don’t define virtualAddress
or bindAddr
in the Frontend configuration, the Controller configures and manages pools, pool members, and healthchecks for the Service without a BIG-IP virtual server.
In such cases, you should already have a BIG-IP virtual server that handles client connections configured with an iRule or local traffic policy that can forward the request to the correct pool.
The stable name of the pool will be the Kubernetes namespace the Service runs in, followed by an underscore, followed by the name of the Service’s ConfigMap.
For example: default_myService
.
See also
See Manage pools without virtual servers for more information.
[1] | If you want to configure multiple SSL profiles, use f5ProfileNames instead of f5ProfileName . The two parameters are mutually exclusive. |
The frontend.virtualServer
properties provide the information required to deploy an iApp on the BIG-IP system.
Tip
The iappOptions
represent information that the user would provide if deploying the iApp via the BIG-IP configuration utility.
Property | Type | Required | Description | Allowed Values |
---|---|---|---|---|
partition | string | Required | The BIG-IP partition you want the k8s-bigip-ctlr to manage. |
|
iapp | string | Required | BIG-IP iApp template to use to create the application Service. | Any iApp template that already exists on the BIG-IP system. |
iappPoolMemberTable | JSON object | Required | Define the name and layout of the pool member table in the iApp. |
|
iappTables | JSON object array | Optional | Define iApp tables to apply to the Application Service Example: "iappTables": {
"monitor__Monitors":
{"columns": ["Index", "Name", "Type", "Options"],
"rows": [[0, "mon1", "tcp", "" ],
[1, "mon2", "http", ""]]}}"
|
|
iappOptions | key-value object | Required | Define the App configurations | See Controller Configuration Parameters. |
iappVariables | key-value object | Required | Define the iApp variables needed for Service creation. |
You can use the iappPoolMemberTable
option to describe the layout of the pool-member table that the Controller should configure. It is a JSON object with these properties:
name
(required): A string that specifies the name of the table that contains the pool members.columns
(required): An array that specifies the columns that the Controller will configure in the pool-member table, in order.Each entry in columns
is an object that has a name
property and either a kind
or value
property:
name
(required): A string that specifies the column name.kind
: A string that tells the Controller what property from the node to substitute. The Controller supports "IPAddress"
and "Port"
.value
: A string that specifies a value. The Controller will not perform any substitution, it uses the value as specified.For example: If you configure an application with two pods at 1.2.3.4:20123 and 1.2.3.5:20321 and you specify the following JSON:
"iappPoolMemberTable" = {
"name": "pool__members",
"columns": [
{"name": "Port", "kind": "Port"},
{"name": "IPAddress", "kind": "IPAddress"},
{"name": "ConnectionLimit", "value": "0"}
]
}
the k8s-bigip-ctlr
creates the table below on the BIG-IP system.
{
"name": "pool__members",
"columnNames": [
"Port",
"IPAddress",
"ConnectionLimit",
],
"rows": [
{
"row": [
"20123",
"1.2.3.4",
"0",
]
},
{
"row": [
"20321",
"1.2.3.5",
"0",
]
},
]
}
You will need to adjust this for the particular iApp template that you are using. One way to discover the format is to configure an iApp manually from a template, then check its configuration using tmsh list sys app Service <appname>.
The backend
section tells the k8s-bigip-ctlr
about the Service you want to manage.
Property | Type | Required | Default | Description | Allowed Values |
---|---|---|---|---|---|
ServiceName | string | Required | none | The Kubernetes Service representing the server pool. | |
ServicePort | integer | Required | none | Kubernetes Service port number | |
healthMonitors | JSON object array | Optional | none | Array of TCP or HTTP Health Monitors. |
You can use the k8s-bigip-ctlr
as a Kubernetes Ingress Controller to expose Services to external traffic.
Annotation | Type | Required | Description | Default | |
---|---|---|---|---|---|
virtual-server.f5.com/ip | string | Required | The IP address you want to assign to the virtual server. | N/A | |
virtual-server.f5.com/partition | string | Optional | The BIG-IP partition in which the Controller should create/update/delete objects for this Ingress. | N/A | |
kubernetes.io/ingress.class | string | Optional | Tells the Controller it should only manage Ingress resources in the f5 class.
If defined, the value must be f5 . |
f5 | |
virtual-server.f5.com/balance | string | Optional | Specifies the load balancing mode. | round-robin | |
virtual-server.f5.com/http-port | integer | Optional | Specifies the HTTP port. | 80 | |
virtual-server.f5.com/https-port | integer | Optional | Specifies the HTTPS port. | 443 | |
virtual-server.f5.com/health | JSON object | Optional | Defines a health monitor for the Ingress resource. | N/A | |
path | string | Required [5] | The path for the Service specified in the Ingress resource. | N/A | |
send | string | Required [5] | The send string to set in the health monitor. [6] | N/A | |
interval | integer | Required [5] | The interval at which to check the health of the virtual server. | N/A | |
timeout | integer | Required [5] | Number of seconds before the check times out. | N/A | |
ingress.kubernetes.io/allow-http | boolean | Optional | Tells the Controller to allow HTTP traffic for HTTPS Ingress resources. | false | |
ingress.kubernetes.io/ssl-redirect | boolean | Optional | Tells the Controller to redirect HTTP traffic to the HTTPS port for HTTPS Ingress resources (see TLS Ingress resources, below). | true |
If the Ingress resource contains a tls section, the allow-http and ssl-redirect annotations provide a method of controlling HTTP traffic. In this case, the Controller uses the value set in the allow-http annotation to enable or disable HTTP traffic. Use the ssl-redirect annotation to redirect all HTTP traffic to the HTTPS Virtual Server.
You can specify one (1) or more SSL profiles in the Ingress resource.
/Common/clientssl
).To configure health monitors on your Ingress resource, define the virtual-server.f5.com/health
annotation with a JSON object.
Provide an array for each path specified in the Ingress resource.
For example
{
"path": "ServiceName/path",
"send": "<send string to set in the health monitor>",
"interval": <health check interval>,
"timeout": <number of seconds before the check has timed out>
}
Note
You can use OpenShift Route resources in an existing deployment once you replace the OpenShift F5 Router with the BIG-IP Controller.
Type | Client Connection Encrypted | Server Connection Encrypted | Path Support | SSL Termination on BIG-IP | Description |
---|---|---|---|---|---|
Unsecured | No | No | Yes | No | The BIG-IP system forwards unsecured traffic from the client to the endpoint. |
Edge Terminated | Yes | No | Yes | Yes | The Controller maintains a new client SSL profile on the BIG-IP system based on the client certificate and key from the Route resource.
|
Passthrough Terminated | Yes | Yes | No | No | The BIG-IP system uses an iRule to select the destination pool based on SNI and forward the re-encrypted traffic. |
Re-encrypt Terminated | Yes | Yes | Yes | Yes | The Controller maintains a new BIG-IP client SSL profile based on the client certificate and key from the Route resource. The Controller maintains a new BIG-IP server SSL profile based on the server CA certificate from the Route resource for re-encrypting the traffic. The BIG-IP system uses an iRule to select the destination pool based on SNI and forward the re-encrypted traffic. |
Important
Please see the example configuration files for more details.
sample-k8s-bigip-ctlr-secrets.yaml
sample-bigip-credentials-secret.yaml
example-vs-resource.configmap.yaml
example-vs-resource.json
example-vs-resource-iapp.json
example-advanced-vs-resource-iapp.json
single-service-ingress.yaml
single-service-tls-ingress.yaml
simple-ingress-fanout.yaml
name-based-ingress.yaml
ingress-with-health-monitors.yaml
sample-rbac.yaml
sample-unsecured-route.yaml
sample-edge-route.yaml
sample-passthrough-route.yaml
sample-reencrypt-route.yaml
Footnotes
[2] | The k8s-bigip-ctlr creates and manages objects in the BIG-IP partition defined in the F5 resource ConfigMap. It cannot manage objects in the /Common partition. |
[3] | The k8s-bigip-ctlr forwards traffic to the NodePort assigned to the Service by Kubernetes. See the Kubernetes Services documentation for more information. |
[4] | You can secure your BIG-IP credentials using a Kubernetes Secret. |
[5] | (1, 2, 3, 4) Required if defining the virtual-server.f5.com/health Ingress annotation. |
[6] | See the HTTP monitor settings section of the BIG-IP LTM Monitors Reference Guide for more information about defining send strings. |