Container Ingress Services and AS3 Extension integration

You can use Container Ingress Services (CIS) to expose services to external traffic using Application Services 3 (AS3) Extension declarations.

Prerequisites

To use AS3 declarations with CIS, ensure you meet the following requirements:

  • The BIG-IP system is running software version 12.1.x or higher.
  • The BIG-IP sytem has AS3 Extension version 3.10 or higher installed.
  • A BIG-IP system user account with the Administrator role.

Limitations

CIS has the following AS3 Extension limitations:

  • AS3 pool class declarations support only one load balancing pool.
  • CIS supports only one AS3 ConfigMap instance.
  • AS3 does not support moving BIG-IP nodes to new partitions.

Declaritive API

AS3 Extensions use a declarative API, meaning AS3 Extension declarations describe the desired configuration state of a BIG-IP system. When using AS3 Extenstions, CIS sends declaration files using a single Rest API call.

CIS service discovery

CIS can dynamically discover, and update the BIG-IP system’s load balancing pool members using Service Discovery. CIS maps each pool definition in the AS3 template to a Kubernetes Service resource using Labels. To create this mapping, add the following labels to your Kubernetes Service:

Label Description
app: <string>
This label associates the service with the deployment.
Important: This label must be included, and resolve in DNS.
cis.f5.com/as3-tenant: <string>
The name of the partition in your AS3 declaration.
Important: The string must not use a hyphen (-) character.
cis.f5.com/as3-app: <string> The name of the class in your AS3 declaration.
cis.f5.com/as3-pool: <string> The name of the pool in your AS3 Declaration.

Important

Multiple Kubernetes Service resources tagged with same set of labels will cause a CIS error, and service discovery failure.

Service label overview

../_images/k8s_service_labels.png

Example Service

apiVersion: v1
kind: Service
metadata:
  name: f5-hello-world
  namespace: kube-system
  labels:
    app: f5-hello-world
    cis.f5.com/as3-tenant: AS3
    cis.f5.com/as3-app: f5-hello-world
    cis.f5.com/as3-pool: web_pool
spec:
  ports:
  - name: f5-hello-world
    port: 80
    protocol: TCP
    targetPort: 80
  type: NodePort
  selector:
    app: f5-hello-world

Example Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: f5-hello-world
  namespace: kube-system
spec:
  replicas: 2
  selector:
    matchLabels:
      app: f5-hello-world
  template:
    metadata:
      labels:
        app: f5-hello-world
    spec:
      containers:
      - env:
        - name: service_name
          value: f5-hello-world
        image: f5devcentral/f5-hello-world:latest
        imagePullPolicy: Always
        name: f5-hello-world
        ports:
        - containerPort: 80
          protocol: TCP

Service discovery and controller mode

CIS service discovery adds IP address and service port information to AS3 declarations differently, depending on the controller mode.

Controller mode Configuration update
Cluster IP
  • Add the Kubernetes Service endpoint IP Addresses to the ServiceAddresses section.
  • Use the Kubernetes Service endpoint service ports to replace entries in the ServicePort section.
Node Port
  • Add the Kubernetes cluster node IP addresses to the ServerAddresses section.
  • Use the Kubernetes cluster NodePort ports to replace entries in the ServicePort section.

Ensure you expose Kubernetes services as type Nodeport.

AS3 declaration processing

To process an AS3 declaration using CIS, set the f5type label to virtual-server and the as3 label to the true.

Note

CIS uses gojsonschema to validate AS3 data. If the data structure does not conform with the schema, an error will be logged. Also, ensure the the AS3 label value is the string true, and not the boolean True.

Example AS3 ConfigMap

kind: ConfigMap
apiVersion: v1
metadata:
  name: as3-template
  namespace: kube-system
  labels:
    f5type: virtual-server
    as3: "true"
data:
  template: |
    {
          <YOUR AS3 DECLARATION>
    }

AS3 declaration processing involves these four steps:

  1. You submit the AS3 template inside the configMap resource and deploy it in Kubernetes.
  2. After the AS3 configMap becomes available for processing, CIS performs service discovery as described in the Service Discovery section.
  3. After Service discovery completes, CIS modifies the AS3 template to append discovered endpoints. CIS only modify these two values in the AS3 template:
    • serverAddresses array. If this array is not empty, CIS treats will not overwrite the entries.
    • servicePort value.
  4. CIS posts the generated AS3 declaration to the BIG-IP system and begins processing traffic.

CIS and AS3 deployment workflow

../_images/container_ingress_services.png

Parameters

Parameter Type Required Default Description Allowed Values
as3-validation Boolean Optional True Tells CIS whether or not to perform AS3 validation. “true”, “false”
insecure Boolean Optional False Tells CIS whether or not to allow communication with BIG-IP using invalid SSL certificates. For more info, refer to the next section; CIS and SSL certificate validation. “true”, “false”

Deleting CIS configmaps

Because CIS and AS3 use a Declarative API, the BIG-IP system configuration is not removed after you delete a configmap. To remove the BIG-IP system configuration objects created by an AS3 declaration, you must deploy a blank configmap, and restart the controller. Refer to Deleting CIS AS3 configmaps.

CIS and SSL certificate validation

CIS validates SSL certificates using the root CA certifictes bundled with the base Debian/Redhat image. Because of this, CIS will fail to validate a BIG-IP system’s self-signed SSL certificate, and log an error message similar to the following in the AS3 log file:

[ERROR] [as3_log] REST call error: Post https://10.10.10.100/mgmt/shared/appsvcs/declare: x509: cannot validate certificate for 10.10.10.100

To avoid this issue, you can perform one of the following:

  • Bypass certificate validation by including the --insecure=true option in your configuration when executing a Kubernetes deployment.
  • Establish trust with the BIG-IP system by Updating the CIS trusted certificate store.

CIS and administrative partitions

CIS requires a unique administrative partition on the BIG-IP system to manage the ARP entries of discovered services. Ensure that you set the --bigip-partition=<name> parameter to a unique value when executing a Kubernetes deployment.

Important

This unique BIG-IP partition does not allow the use of the AS3 Tenant class.

AS3 tenants

AS3 tenants are BIG-IP administrative partitions used to group configurations that support specific AS3 applications. An AS3 application may support a network-based business application or system. AS3 tenants may also include resources shared by applications in other tenants.

AS3 Resources