Skip to content

Commit

Permalink
Enhancements for beta release (#3412)
Browse files Browse the repository at this point in the history
  • Loading branch information
@arzzon
arzzon authored May 7, 2024
1 parent fea7547 commit c8ff031
Show file tree
Hide file tree
Showing 32 changed files with 2,623 additions and 5 deletions.
5 changes: 3 additions & 2 deletions build-tools/version-tool
View file
Original file line number Diff line number Diff line change
Expand Up @@ -169,8 +169,9 @@ class VersionInfo(object):
self._ver_file = Version(data)

if self._ver_file.pre or self._ver_file.build:
raise Exception("{} contains more than major.minor.patch"
.format(version_file.name))
if self._ver_file.pre not in ["alpha","beta","rc"]:
raise Exception("{} contains more than major.minor.patch"
.format(version_file.name))
self._vers = {
'major': self._ver_file.major,
'minor': self._ver_file.minor,
Expand Down
16 changes: 16 additions & 0 deletions docs/cis-3.x/RELEASE-NOTES.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
Release Notes for Container Ingress Services for Kubernetes & OpenShift
=======================================================================

3.0.0-beta
-------------

Added Functionality
```````````````````
**What's new:**
* Support for Central Manager and BigIP-Next
* Support for following resources:
* Transport Server CR
* Service Type Load balancer
* IngressLink CR
* Integration with FIC
* Support for Nodeport Mode
97 changes: 97 additions & 0 deletions docs/cis-3.x/config_examples/customResource/CustomResource.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Custom Resource Definitions

This page is created to document the behaviour of CIS in CRD Mode.

## What are CRDs?

* Custom resources are extensions of the Kubernetes API.
* A resource is an endpoint in the Kubernetes API that stores a collection of API objects of a certain kind; for example, the built-in pods resource contains a collection of Pod objects.
* A custom resource is an extension of the Kubernetes API that is not necessarily available in a default Kubernetes installation. It represents a customization of a particular Kubernetes installation. However, many core Kubernetes functions are now built using custom resources, making Kubernetes more modular.
* Custom resources can appear and disappear in a running cluster through dynamic registration, and cluster admins can update custom resources independently of the cluster itself. Once a custom resource is installed, users can create and access its objects using kubectl, just as they do for built-in resources like Pods.

## How CIS works with CRDs

* CIS registers to the kubernetes client-go using informers to retrieve Transport Server, Service, Endpoint and Node creation, updation and deletion events. Resources identified from such events will be pushed to a Resource Queue maintained by CIS.
* Resource Queue holds the resources to be processed.
* Transport Server is the Primary citizen. Any changes in Service, Endpoint, Node will process their affected Transport Servers. For Example, If svc-a is part of foo-TransportServer and bar-TransportServer, Any changes in svc-a will put foo-TransportServer and bar-TransportServer in resource queue.
* Worker fetches the affected Transport Servers from Resource Queue to populate a common structure which holds the configuration of all the Transport Servers such as Virtual Server IP, Pool Members etc.
* LTM Configuration(using AS3) will be created in CIS Managed Partition defined by the User.


## Label
* CIS will only process custom resources with f5cr Label as true.
```
labels:
f5cr: "true"
```

## Contents
* CIS supports following Custom Resources at this point of time.
- TransportServer
- IngressLink

## TransportServer
* TransportServer resource expose non-HTTP traffic configuration for a virtual server address in BIG-IP.
* Schema Validation
- OpenAPI Schema Validation

https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/cis-3.x/config_examples/customResourceDefinitions/customresourcedefinitions.yml


**TransportServer Components**

| PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
|----------------------|-------------------------|----------|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pool | pool | Required | NA | BIG-IP Pool member |
| virtualServerAddress | String | Optional | NA | IPv4/IPv6 IP Address of BIG-IP Virtual Server. IP address can also be replaced by a reference to a Service_Address. |
| ipamLabel | String | Optional | NA | IPAM label name for IP address management which is map to ip-range in IPAM controller deployment. |
| hostGroup | String | Optional | NA | To leverage the IP from VS CR using the same VS HostGroup name and Vice-versa. |
| policyName | String | Optional | NA | Name of Policy CRD to attach profiles/policies defined in it. |
| serviceAddress | List of service address | Optional | NA | Service address definition allows you to add a number of properties to your (virtual) server address |
| virtualServerPort | String | Required | NA | Port Address of BIG-IP Virtual Server |
| virtualServerName | String | Optional | NA | Custom name of BIG-IP Virtual Server |
| type | String | Optional | tcp | "tcp", "udp" or "sctp" L4 transport server type |
| mode | String | Required | NA | "standard" or "performance". A Standard mode transport server processes connections using the full proxy architecture. A Performance mode transport server uses FastL4 packet-by-packet TCP behavior. |
| snat | String | Optional | auto | |
| host | String | Optional | NA | HostName of the Virtual Server |
| partition | String | Optional | NA | bigip partition |

**Pool Components**

| PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
| ------ |---------| ------ | ------ |----------------------------------------------------|
| service | String | Required | NA | Service deployed in kubernetes cluster |
| servicePort | Integer or String | Required | NA | Port to access Service.Could be service port, service port name or targetPort of the service|
| monitor | monitor | Optional | NA | Health Monitor to check the health of Pool Members |
| loadBalancingMethod | String | Optional | round-robin | Allowed values are existing BIG-IP Load Balancing methods for pools.|
| nodeMemberLabel | String | Optional | NA | List of Nodes to consider in NodePort Mode as BIG-IP pool members. This Option is only applicable for NodePort Mode |
| serviceNamespace | String | Optional | NA | Namespace of service, define it if service is present in a namespace other than the one where transport Server Custom Resource is present |



**Health Monitor**

| PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
| ------ | ------ | ------ | ------ | ------ |
| type | String | Required | NA | http or https |
| interval | Int | Required | 5 | Seconds between health queries |
| timeout | Int | Optional | 16 | Seconds before query fails |

### Examples

https://github.com/F5Networks/k8s-bigip-ctlr/tree/master/docs/cis-3.x/config_examples/customResource/TransportServer

## IngressLink

Refer https://github.com/F5Networks/k8s-bigip-ctlr/tree/master/docs/cis-3.x/config_examples/customResource/IngressLink/README.md


# IP address management using the IPAM controller

CIS can manage the virtual server address for VS and TS using the IPAM controller. The IPAM controller is a container provided by F5 for IP address management and it runs in parallel to the F5 ingress controller a pod in the Kubernetes/Openshift cluster. You can use the F5 IPAM controller to automatically allocate IP addresses to Virtual Servers, Transport Servers from a specified IP address range. You can specify this IP range in the IPAM Controller deployment file while deploying the IPAM controller.

Specify the IPAM label `--ipamLabel` as an argument in VS and TS CRD.
Example: `--ipamLabel="Prod"`

[See Documentation](https://clouddocs.f5.com/containers/latest/userguide/ipam/)

3 changes: 3 additions & 0 deletions docs/cis-3.x/config_examples/customResource/IngressLink/Proxy_Protocol_iRule
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
when SERVER_CONNECTED {
TCP::respond "PROXY TCP[IP::version] [IP::client_addr] [clientside {IP::local_addr}] [TCP::client_port] [clientside {TCP::local_port}]\r\n"
}
86 changes: 86 additions & 0 deletions docs/cis-3.x/config_examples/customResource/IngressLink/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Integration with Nginx Ingress Controller

Using this integration, CIS can be used to configure the F5 BIG-IP device as a load balancer for [Nginx Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/) pods.

> **Feature Status**: The integration between CIS and Nginx Controller is available as a preview feature. It is suitable for experimenting and testing; however, it must be used with caution in production environments. Additionally, while the feature is in preview, we might introduce some backward-incompatible changes in the next releases. *The preview of the IngressLink solution requires a dedicated Container Ingress Services instance.*
## IngressLink Compatibility Matrix
Minimum version to use IngressLink:

| CIS | BIGIP | NGINX+ IC | AS3 |
| ------ | ------ | ------ | ------ |
| 2.3+ | v13.1+ | 1.10+ | 3.18+ |

With CIS 3.x:

| CIS 3.x | BIGIP-Next | CM | NGINX+ IC |
| ------ |------------------|----------------|-----------|
| 3.0.0-beta | v20.2.0-2.375.1+ | 20.2.0-0.5.41+ | 1.10+ |


## Configuration

### 1. Create IngressLink Custom Resource Definition

Create IngressLink Custom Resource definition as follows:

```
kubectl create -f https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/cis-3.x/config_examples/customResourceDefinitions/customresourcedefinitions.yml
```


### 2. Create the Proxy iRule on BIG-IP.

* Login to the BIG-IP GUI.
* On the Main tab, click **Local Traffic > iRules**.
* Click **Create**.
* In the Name field, type name as "Proxy_Protocol_iRule".
* In the Definition field, Copy the definition from [Proxy_Protocol_iRule](https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/config_examples/customResource/IngressLink/Proxy_Protocol_iRule) file.
* Click **Finished**.

### 3. Install the CIS Controller.

* Refer to [CIS Installation guide](https://clouddocs.f5.com/containers/latest/userguide/cis-helm.html) to install Container Ingress Services on Kubernetes or Openshift.
* Make sure that you deploy CIS in CRD mode (use "--custom-resource-mode=true" in your CIS Configuration).

### 4. Install the Nginx Ingress Controller.

* Refer to [Integration with F5 Container Ingress Services](https://docs.nginx.com/nginx-ingress-controller/installation/integrations/f5-ingresslink/) to deploy NGINX Ingress Controller.

### 5. Create an IngressLink Resource.

* Download the sample IngressLink Resource:

```curl -OL https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/cis-3.x/config_examples/customResource/IngressLink/ingresslink.yaml```

* Update the "virtualServerAddress" parameter in the ingresslink.yaml resource. This IP address will be used to configure the BIG-IP device. It will be used to accept traffic and load balance it among the NGINX Ingress Controller pods.

```kubectl apply -f ingresslink.yaml```

##### Note:
1. The name of the app label selector in IngressLink resource should match the labels of the service which exposes the NGINX Ingress Controller.
2. The service which exposes the NGINX Ingress Controller should be of type ``nodeport``.

### 6. Test the Integration.

To test the integration, deploy a sample application:

kubectl apply -f https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/cis-3.x/config_examples/customResource/IngressLink/ingress-example/cafe.yaml
kubectl apply -f https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/cis-3.x/config_examples/customResource/IngressLink/ingress-example/cafe-secret.yaml
kubectl apply -f https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/cis-3.x/config_examples/customResource/IngressLink/ingress-example/cafe-ingress.yaml

The Ingress Controller pods are behind the IP configured in Step 5 (virtualServerAddress parameter).

To test the traffic (in this example we used 192.168.10.5 as our VirtualServerAddress):

$ curl --resolve cafe.example.com:443:192.168.10.5 https://cafe.example.com:443/coffee --insecure
Server address: 10.12.0.18:80
Server name: coffee-7586895968-r26zn
...

If you check the status of the cafe-ingress, you will see the IP of the VirtualServerAddress (in this example we used 192.168.10.5 as our VirtualServerAddress):
```
$ kubectl get ing cafe-ingress
NAME HOSTS ADDRESS PORTS AGE
cafe-ingress cafe.example.com 192.168.10.5 80, 443 115s
```
31 changes: 31 additions & 0 deletions docs/cis-3.x/config_examples/customResource/IngressLink/ingress-example/cafe-ingress.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
# use annotations with k8s version < 1.18.0
annotations:
#kubernetes.io/ingress.class: nginx
spec:
ingressClassName: nginx # use only with k8s version >= 1.18.0
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: ImplementationSpecific
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: ImplementationSpecific
backend:
service:
name: coffee-svc
port:
number: 80
Loading

0 comments on commit c8ff031

Please sign in to comment.