Install the BIG-IP Controller: OpenShift

Use a Deployment to install the BIG-IP Controller for OpenShift.

If you use helm, you can use the f5-bigip-ctlr chart to create and manage the resources below.

Attention

These instructions are for the Openshift Kubernetes distribution. If you are using standard Kubernetes, see Install the BIG-IP Controller in Kubernetes.

Task Summary
Step Task
Initial Set-up

Create a Kubernetes Deployment

Upload the Deployment to the OpenShift API Server
Verify Pod(s)

Initial Set-up

Follow the steps in the guides linked to below to set up your BIG-IP device(s) and OpenShift cluster for use with the BIG-IP Controller.

Important

The steps in this section require either Administrator or Resource Administrator permissions on the BIG-IP system.

  1. If you want to use BIG-IP High Availability (HA), set up two or more F5 BIG-IPs in a Device Service Cluster (DSC).

  2. Create a new partition on your BIG-IP system.

    Note

    • The BIG-IP Controller can not manage objects in the /Common partition.
    • [Optional] The Controller can decorate the IP addresses it configures on the BIG-IP with a Route Domain identifier. You may want to use route domains if you have many applications using the same IP address space that need isolation from one another. After you create the partition on your BIG-IP system, you can 1) create a route domain and 2) assign the route domain as the partition’s default. See create and set a non-zero default Route Domain for a partition for setup instructions.
    • [Optional] If you’re using a BIG-IP HA pair or cluster, sync your changes across the group.
  3. Store your BIG-IP login credentials in a Secret.

  4. If you need to pull the k8s-bigip-ctlr image from a private Docker registry, store your Docker login credentials as a Secret.

Set up RBAC Authentication

You can create RBAC resources in the project in which you will run your BIG-IP Controller. Each Controller that manages a device in a cluster or active-standby pair can use the same Service Account, Cluster Role, and Cluster Role Binding.

Required RBAC Permissions
API groups Resources Actions
“” endpoints, namespaces, nodes, routes, services, secrets get, list, watch
“extensions” ingresses get, list, watch
“” configmaps, events get, list, watch, update, create, patch
“extensions” ingresses/status get, list, watch, update, create, patch

Tip

Create the RBAC resources in the same Project (or namespace) as the BIG-IP Controller, or in a Project the BIG-IP Controller can access.

If you need to be able to access the RBAC resources from all Projects, an OpenShift administrator should create them in the kube-system namespace (-n kube-system).

In these cases, you can either:

  • use the Controller’s default “watch all namespaces” setting (requires no additional configuration); or
  • set the Controller to watch both the kube-system namespace and the Project’s namespace.
  1. Create a Service Account for the BIG-IP Controller.

    oc create serviceaccount bigip-ctlr [-n kube-system]
    serviceaccount "bigip-ctlr" created
    
  2. Create a Cluster Role and Cluster Role Binding with the required permissions.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    # For use in OpenShift clusters
    apiVersion: v1
    kind: ClusterRole
    metadata:
      annotations:
        authorization.openshift.io/system-only: "true"
      name: system:bigip-ctlr
    rules:
    - apiGroups: ["", "extensions"]
      resources: ["nodes", "services", "endpoints", "namespaces", "ingresses", "routes" ]
      verbs: ["get", "list", "watch"]
    - apiGroups: ["", "extensions"]
      resources: ["configmaps", "events", "ingresses/status"]
      verbs: ["get", "list", "watch", "update", "create", "patch" ]
    - apiGroups: ["", "extensions"]
      resources: ["secrets"]
      resourceNames: ["<secret-containing-bigip-login>"]
      verbs: ["get", "list", "watch"]
    
    ---
    
    apiVersion: v1
    kind: ClusterRoleBinding
    metadata:
        name: bigip-ctlr-role
    userNames:
    - system:serviceaccount:kube-system:bigip-ctlr
    subjects:
    - kind: ServiceAccount
      name: bigip-ctlr
    roleRef:
      name: system:bigip-ctlr
    

    f5-kctlr-openshift-clusterrole.yaml

  3. Upload the Cluster Role and Cluster Role Binding to the API server.

    oc create -f f5-kctlr-openshift-clusterrole.yaml [-n kube-system]
    clusterrole "system:bigip-ctlr" created
    clusterrolebinding "bigip-ctlr-role" created
    

Create a Kubernetes Deployment

Note

OpenShift supports two types of Deployments: Deployment Configurations and Kubernetes Deployments. See Kubernetes Deployment Support in the OpenShift documentation for more information.

Define a Kubernetes Deployment using valid YAML or JSON. The BIG-IP Controller has configuration parameters specific to OpenShift that you can define as best suits your needs.

At a minimum, all BIG-IP Controller Deployments should include the following:

  • --openshift-sdn-name=/path/to/bigip_openshift_vxlan
  • --pool-member-type=cluster

Danger

Do not increase the replica count in the Deployment. Running duplicate Controller instances may cause errors and/or service interruptions.

Important

The BIG-IP Controller requires Administrator permissions in order to provide full functionality.

Basic Deployment

The example below shows a Deployment with the basic config parameters required to run the BIG-IP Controller in OpenShift. With this configuration, you can Create BIG-IP virtual servers for Services and Deploy Application Services (iApps).

Example OpenShift Deployment
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: k8s-bigip-ctlr
spec:
  replicas: 1
  template:
    metadata:
      name: k8s-bigip-ctlr
      labels:
        app: k8s-bigip-ctlr
    spec:
      # Name of the Service Account bound to a Cluster Role with the required
      # permissions
      serviceAccountName: bigip-ctlr
      containers:
        - name: k8s-bigip-ctlr
          # replace the version as needed
          image: "f5networks/k8s-bigip-ctlr:1.5"
          env:
            - name: BIGIP_USERNAME
              valueFrom:
                secretKeyRef:
                  # Replace with the name of the Secret containing your login
                  # credentials
                  name: bigip-login
                  key: username
            - name: BIGIP_PASSWORD
              valueFrom:
                secretKeyRef:
                  # Replace with the name of the Secret containing your login
                  # credentials
                  name: bigip-login
                  key: password
          command: ["/app/bin/k8s-bigip-ctlr"]
          args: [
            # See the k8s-bigip-ctlr documentation for information about
            # all config options
            # http://clouddocs.f5.com/products/connectors/k8s-bigip-ctlr/latest
            "--bigip-username=$(BIGIP_USERNAME)",
            "--bigip-password=$(BIGIP_PASSWORD)",
            "--bigip-url=<ip_address-or-hostname>",
            "--bigip-partition=<name_of_partition>",
            "--pool-member-type=cluster",
            "--openshift-sdn-name=/Common/<tunnel>",
            ]
      imagePullSecrets:
        # Secret that gives access to a private Docker registry
        - name: f5-docker-images
        # Secret containing the BIG-IP system login credentials
        - name: bigip-login

f5-k8s-bigip-ctlr_openshift_basic.yaml

Use BIG-IP SNAT Pools and SNAT automap

Note

By default, the BIG-IP Controller uses BIG-IP Automap SNAT for all of the virtual servers it creates. From k8s-bigip-ctlr v1.5.0 forward, you can designate a specific SNAT pool in the Controller Deployment instead of using SNAT automap.

In environments where the BIG-IP connects to the Cluster network, the self IP used as the BIG-IP VTEP serves as the SNAT pool for all origin addresses within the Cluster. The subnet mask you provide when you create the self IP defines the addresses available to the SNAT pool.

See BIG-IP SNATs and SNAT automap for more information.

To use a specific SNAT pool, add the following to the args section of any k8s-bigip-ctlr Deployment:

"--vs-snat-pool-name=<snat-pool>"

Replace <snat-pool> with the name of any SNAT pool that already exists in the /Common partition on the BIG-IP device. The BIG-IP Controller cannot define a new SNAT pool for you.

f5-k8s-bigip-ctlr_openshift_snat.yaml

Deployments for Managing Routes

The BIG-IP Controller has a set of Route configuration parameters that you can add to any k8s-bigip-ctlr Deployment if you want to manage Routes.

See Manage Routes with the BIG-IP Controller for instructions and examples.

Deployments for BIG-IP HA pairs/groups

If you want to manage a BIG-IP HA pair or group, you’ll need to deploy one BIG-IP Controller instance per BIG-IP device.

See BIG-IP High Availability in OpenShift for instructions and examples.

Upload the Deployment to the OpenShift API Server

Use the oc create command to upload the Deployment to the OpenShift API server.

oc create -f f5-k8s-bigip-ctlr_openshift-sdn.yaml [-n kube-system]
deployment "k8s-bigip-ctlr" created

Verify Pod(s)

Use the oc get command to verify that the k8s-bigip-ctlr Pod launched successfully.

oc get pods
NAME                              READY     STATUS    RESTARTS   AGE
k8s-bigip-ctlr-1962020886-s31l4   1/1       Running   0          1m

Note

Once the Controller is running, you should be able to successfully send traffic through the BIG-IP system to and from endpoints within your OpenShift Cluster.